# signals.multitaper

> One page of the phonometry documentation, as Markdown. Index: https://docs.jmrp.io/phonometry/llms.txt

Canonical: https://docs.jmrp.io/phonometry/reference/api/signals/multitaper/
Language: en
Version: phonometry 4.0.0
Install: pip install "phonometry[full]"
Author: José Manuel Requena Plens (https://orcid.org/0000-0003-1250-6212)
Published: 2026-08-05
Updated: 2026-11-11T17:49:24Z
License: MIT (https://github.com/jmrplens/phonometry/blob/main/LICENSE)
Summary: Thomson multitaper spectral estimation (Percival & Walden 1993, Ch. 7).

---

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`](https://docs.jmrp.io/phonometry/reference/api/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 $2K$ 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 $A^2/2$ at a tone's peak)
matches [`phonometry.signals.spectra`](https://docs.jmrp.io/phonometry/reference/api/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

```python
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
$[-W, W]$, 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 $2K$ chi-square degrees of freedom and
$1/K$ of
the periodogram's variance *without* segmenting the record: the
estimator of choice for short records, where Welch's method
([`power_spectral_density`](https://docs.jmrp.io/phonometry/reference/api/signals/spectra/#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
$\sigma^2$ driving the weights is
$\operatorname{mean}(x^2)$ 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`](https://docs.jmrp.io/phonometry/reference/api/signals/spectra/) exactly: no
detrending, `'density'` scaling integrates to the signal power
(units²/Hz, one-sided) and `'spectrum'` scaling reads
$A^2/2$ 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
$\left( \sum_t h_{tk} \right)^2$; a tone's power in
`'density'` scaling is spread over
the resolution bandwidth $2W$).

**Parameters**

| Name | Description |
| :--- | :--- |
| `x` | Signal, 1-D (used whole; no segmentation). Accepts a [`phonometry.io.Signal`](https://docs.jmrp.io/phonometry/reference/api/io/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`](https://docs.jmrp.io/phonometry/reference/api/io/io/#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 $W = NW f_\mathrm{s} / N$ Hz; larger `NW` admits more tapers (lower variance) at the cost of resolution $2W$. |
| `n_tapers` | Number of tapers `K`; `None` picks $2 NW - 1$ (all tapers with near-unity concentration, P&W Section 7.1). At most the Shannon number $2 NW$. |
| `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`](https://docs.jmrp.io/phonometry/reference/api/signals/multitaper/#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

```python
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 $2K$, without segmenting the record as Welch's
method does. The chi-square machinery mirrors
[`SpectralDensityResult`](https://docs.jmrp.io/phonometry/reference/api/signals/spectra/#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 $\hat{S}^{(mt)}(f)$ (units²/Hz for `'density'` scaling, units² for `'spectrum'`). |
| `confidence_lower` | Lower chi-square confidence bound, $\nu \hat{S}/\chi^2_{\nu;\alpha/2}$ with the per-frequency $\nu$ (the same interval form as B&P Eq. 8.163, with $\nu$ 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 $\nu(f) = 2 \left( \sum_k d_k \right)^2 / \sum_k d_k^2$ with $d_k = b_k^2(f) \lambda_k$ (P&W Eq. 370b); $2K \left( \sum \lambda_k / K \right)^2 K / \sum \lambda_k^2 \approx 2K$ 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 $\varepsilon[\hat{S}^{(mt)}] = \sqrt{2/\nu}$ ($\approx 1/\sqrt{K}$), the multitaper counterpart of B&P Eq. 8.158. |
| `weights` | Normalized combination weights $d_k(f) / \sum_j d_j(f)$, shape `(n_tapers, n_frequencies)`. Adaptive weighting makes them frequency dependent; they converge to $\approx 1/K$ where the spectrum is locally white (exactly uniform weights would be $\lambda_k / \sum \lambda_j$). |
| `eigenvalues` | Concentration ratios $\lambda_k(N, W)$ of the tapers: the fraction of each taper's spectral-window energy inside the design band $[-W, W]$ (P&W Section 7.1; near unity for $k < 2NW$). |
| `time_half_bandwidth` | The duration x half-bandwidth product `NW` (dimensionless; $W = NW/(N \Delta t)$). |
| `n_tapers` | Number of tapers `K` averaged. |
| `resolution_bandwidth` | The resolution bandwidth $2W$ of the estimator, in Hz, the multitaper analog of the Welch $B_\mathrm{e}$ (P&W call $2W$ *the* natural resolution measure of the method). |
| `adaptive` | Whether Thomson's adaptive weights were used. |
| `scaling` | `'density'` or `'spectrum'`. |

### MultitaperSpectralDensityResult.plot()

```python
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"`. |
