signals.multitaper
La referencia de la API se publica en inglés en los dos idiomas: se genera a partir de los docstrings del código, que son su texto original.
Thomson multitaper spectral estimation (Percival & Walden 1993, Ch. 7).
Thomson’s multitaper estimator (Thomson 1982), as developed in Percival &
Walden, Spectral Analysis for Physical Applications (1993, Chapter 7),
is the whole-record alternative to the Welch segment averaging of
phonometry.signals.spectra: K orthogonal discrete prolate
spheroidal (Slepian) tapers of time-half-bandwidth NW produce K
nearly uncorrelated eigenspectra whose (adaptively weighted) average
carries about chi-square degrees of freedom without
splitting the record, which makes it the estimator of choice for short records where
Welch would leave too few segments.
The statistical apparatus is the same as that of the Welch estimators,
one step further: the chi-square confidence interval keeps the form of
Bendat & Piersol Eq. 8.163, but its degrees of freedom are
per-frequency, because Thomson’s adaptive weights (P&W Eq. 368a)
downweight leakage-prone tapers wherever the spectrum is locally weak
and that costs degrees of freedom there (P&W Eq. 370b). Calibration
(no detrending, one-sided 'density' scaling integrating to the signal
power, 'spectrum' scaling reading at a tone’s peak)
matches phonometry.signals.spectra exactly, so the two estimators
of the same record are directly comparable.
Auto-generated from the source docstrings by
scripts/generate_api_docs.py(make api-docs). Do not edit by hand.
multitaper_psd
Section titled “multitaper_psd”multitaper_psd( x: Signal | NumericArrayLike, fs: float | None = None, *, time_half_bandwidth: float = 4.0, n_tapers: int | np.integer[Any] | None = None, adaptive: bool = True, scaling: Literal['density', 'spectrum'] = 'density', confidence: float = 0.95,) -> MultitaperSpectralDensityResultThomson multitaper spectral density with chi-square interval.
Implements the multitaper estimator of Thomson (1982) as developed in
Percival & Walden (1993, Chapter 7): the record is multiplied by
K orthogonal discrete prolate spheroidal (Slepian) data tapers
(the sequences that maximize spectral concentration in the design band
, computed by scipy.signal.windows.dpss), and
the
K resulting eigenspectra (P&W Eq. 333) are averaged. Because the
tapers are orthogonal the eigenspectra are nearly uncorrelated, so the
average has about chi-square degrees of freedom and
of
the periodogram’s variance without segmenting the record: the
estimator of choice for short records, where Welch’s method
(power_spectral_density) would
leave too few segments.
With adaptive=True (default) the eigenspectra are combined with
Thomson’s frequency-dependent weights (P&W Eqs. 368a/370a, iterated to
convergence): wherever the local spectrum is weak relative to the
broad-band leakage each taper could carry, the leakier high-order
tapers are downweighted, trading degrees of freedom (Eq. 370b) for
leakage protection in high-dynamic-range spectra. The broadband
driving the weights is
with no mean removal,
consistent with the no-detrending calibration below. For a locally
white spectrum the weights converge to uniform and nothing is lost.
With adaptive=False the eigenvalue-weighted average of P&W
Eq. 369a is returned.
Calibration matches the Welch estimators of
phonometry.signals.spectra exactly: no
detrending, 'density' scaling integrates to the signal power
(units²/Hz, one-sided) and 'spectrum' scaling reads
at
the peak of a sinusoid of amplitude A (the tone calibration is
exact for the taper set in use, computed from the taper DC gains
; a tone’s power in
'density' scaling is spread over
the resolution bandwidth ).
Parameters
| Name | Description |
|---|---|
x |
Signal, 1-D (used whole; no segmentation). Accepts a phonometry.io.Signal, whose calibration is applied to the samples, so the density and its confidence interval come out in Pa²/Hz, or Pa² for scaling='spectrum'. |
fs |
Sample rate, in Hz. Required for a bare array; a Signal brings its own, and an explicit value that disagrees with it raises instead of silently winning. |
time_half_bandwidth |
Duration x half-bandwidth product NW (dimensionless; default 4, P&W’s worked choice). The design half-bandwidth is Hz; larger NW admits more tapers (lower variance) at the cost of resolution . |
n_tapers |
Number of tapers K; None picks (all tapers with near-unity concentration, P&W Section 7.1). At most the Shannon number . |
adaptive |
Use Thomson’s adaptive weights (default) or the eigenvalue-weighted average. |
scaling |
'density' (units²/Hz) or 'spectrum' (units², sinusoid-peak reading). |
confidence |
Confidence level for the chi-square interval. |
Returns: A MultitaperSpectralDensityResult.
Raises
| Exception | When |
|---|---|
| ValueError | If the inputs or parameters are invalid. |
| TypeError | if n_tapers is a flag, a text or an array where a count goes, or scaling is not a text. |
MultitaperSpectralDensityResult
Section titled “MultitaperSpectralDensityResult”MultitaperSpectralDensityResult( frequencies: NDArray[np.float64], psd: NDArray[np.float64], confidence_lower: NDArray[np.float64], confidence_upper: NDArray[np.float64], confidence: float, degrees_of_freedom: NDArray[np.float64], random_error: NDArray[np.float64], weights: NDArray[np.float64], eigenvalues: NDArray[np.float64], time_half_bandwidth: float, n_tapers: int, resolution_bandwidth: float, *, adaptive: bool, scaling: Literal['density', 'spectrum'],)Thomson multitaper spectral density (Percival & Walden Ch. 7).
One whole-record estimate from K orthogonal Slepian (dpss) tapers:
the K eigenspectra are nearly uncorrelated, so their weighted
average trades the two chi-square degrees of freedom of a periodogram
for about , without segmenting the record as Welch’s
method does. The chi-square machinery mirrors
SpectralDensityResult, but here
the degrees of freedom are
per-frequency: Thomson’s adaptive weights (P&W Eq. 368a) downweight
leakage-prone tapers wherever the spectrum is locally weak, which
costs degrees of freedom there (P&W Eq. 370b).
Attributes
| Name | Description |
|---|---|
frequencies |
One-sided frequency axis, in Hz. |
psd |
Multitaper spectral density (units²/Hz for 'density' scaling, units² for 'spectrum'). |
confidence_lower |
Lower chi-square confidence bound, with the per-frequency (the same interval form as B&P Eq. 8.163, with from P&W Eq. 370b). |
confidence_upper |
Upper chi-square confidence bound. |
confidence |
Confidence level of the interval (e.g. 0.95). |
degrees_of_freedom |
Per-frequency equivalent chi-square degrees of freedom with (P&W Eq. 370b); for unity weights. The DC bin (and the Nyquist bin for an even record length) carries half (a single real Fourier component per eigenspectrum). |
random_error |
Per-frequency normalized random error (), the multitaper counterpart of B&P Eq. 8.158. |
weights |
Normalized combination weights , shape (n_tapers, n_frequencies). Adaptive weighting makes them frequency dependent; they converge to where the spectrum is locally white (exactly uniform weights would be ). |
eigenvalues |
Concentration ratios of the tapers: the fraction of each taper’s spectral-window energy inside the design band (P&W Section 7.1; near unity for ). |
time_half_bandwidth |
The duration x half-bandwidth product NW (dimensionless; ). |
n_tapers |
Number of tapers K averaged. |
resolution_bandwidth |
The resolution bandwidth of the estimator, in Hz, the multitaper analog of the Welch (P&W call the natural resolution measure of the method). |
adaptive |
Whether Thomson’s adaptive weights were used. |
scaling |
'density' or 'spectrum'. |
MultitaperSpectralDensityResult.plot()
Section titled “MultitaperSpectralDensityResult.plot()”MultitaperSpectralDensityResult.plot( ax: Axes | None = None, *, language: Literal['en', 'es'] = 'en', **kwargs: Any,) -> AxesPlot the multitaper density in dB with its confidence band.
Parameters
| Name | Description |
|---|---|
language |
Label language, "en" (default) or "es". |