Ir al contenido

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(
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,
) -> MultitaperSpectralDensityResult

Thomson 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(
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(
ax: Axes | None = None,
*,
language: Literal['en', 'es'] = 'en',
**kwargs: Any,
) -> Axes

Plot the multitaper density in dB with its confidence band.

Parameters

Name Description
language Label language, "en" (default) or "es".