specmod 0.2.0__py3-none-any.whl

specmod/transforms/multitaper.py

@@ -0,0 +1,357 @@
+"""Thomson multitaper estimation on DPSS tapers.
+
+This replaces ``mtspec``, which is a ctypes wrapper around Fortran, ships as
+source with no wheels, has had no release since 2016, and does not build
+without a Fortran compiler — so it made the whole package uninstallable.
+
+The implementation here uses :func:`scipy.signal.windows.dpss`, in SciPy since
+1.1, and adds Thomson's adaptive weighting. That is a few dozen lines and no
+new dependency, and it puts the normalisation under our control, which is what
+lets one contract cover every backend.
+
+Prieto's pure-Python ``multitaper`` package remains available behind the
+``specmod[multitaper]`` extra for the things it does that this does not:
+jackknife confidence intervals, the F-test for spectral lines, and coherence.
+
+.. warning::
+
+   **Multitaper assumes stationarity, and estimated energy depends on where in
+   the window a transient sits.** This is about the analysis window's own
+   contents, not about signal leaking into a noise window.
+
+   Measured through this class on an identical 10%-wide burst moved across a
+   2000-sample window (estimated energy / true energy):
+
+   ======== ============ ======== ============== ==============
+   Position ``adaptive`` flat     sum of taper^2 FFT, 5% Tukey
+   ======== ============ ======== ============== ==============
+   10%      0.956        0.973    0.948          1.031
+   25%      1.079        1.075    1.071          1.031
+   50%      1.151        1.145    1.148          1.031
+   75%      1.070        1.066    1.072          1.031
+   90%      0.898        0.916    0.951          1.031
+   uniform  1.010        1.009    --             0.995
+   ======== ============ ======== ============== ==============
+
+   The bias is modest, +/-15%, it is the *same* under either weighting, and it
+   tracks the summed taper envelope almost exactly — compare against the
+   ``taper^2`` column. That is simply the taper weighting the middle of the
+   record more than the ends, and it applied equally to ``mtspec``, which uses
+   the same tapers. It is therefore present in pre-refactor results rather than
+   introduced here, and nothing is silently corrected — see
+   ``docs/REFACTOR_PLAN.md`` §5.2.6.
+
+   It matters for the published workflow specifically: refining the window to
+   the 1st-99th percentiles of cumulative energy trims the quiet lead-in while
+   the coda tail remains, which pushes the arrival away from centre.
+
+   Two ways out, both opt-in. Set ``center=True`` to remove the position
+   dependence entirely — a circular shift leaves ``|FFT|`` unchanged, so it is
+   free. Or prefer :class:`~specmod.transforms.fft.FFTEstimator` with a light
+   taper, which holds 1.03x regardless of position, when absolute energy
+   fidelity matters more than variance reduction.
+
+.. note::
+
+   **Validated against Prieto's** ``multitaper``. With
+   ``normalize_to_variance=True`` putting both on the same absolute scale, the
+   two agree to within 0.3% across the band, under adaptive and flat weighting
+   alike, for stationary noise and for bursts at 10%, 50% and 90%.
+
+   The check that earns that is the transient one. A Parseval test on
+   stationary noise passes for a whole family of weighting errors — the signal
+   term is large at every frequency, so the regularisation in Eq. 5.1b never
+   gets a chance to dominate. See :func:`_adaptive_weights` for the units trap
+   that hides there.
+
+References
+----------
+Thomson, D.J. (1982). Spectrum estimation and harmonic analysis.
+*Proc. IEEE* 70(9), 1055-1096.
+
+Prieto, G.A. (2022). The multitaper spectrum analysis package in Python.
+*Seismological Research Letters* 93(3), 1922-1929.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+from scipy.signal.windows import dpss
+
+from ..core.spectrum import Spectrum
+from ..core.units import AmplitudeKind, Motion
+from .base import build_spectrum, prepare_record
+
+__all__ = ["MultitaperEstimator"]
+
+
+def _broadband_power(eigenspectra: NDArray[np.float64], n: int) -> float:
+    """Mean eigenspectral power per two-sided bin — Thomson's ``sigma^2``.
+
+    This is the white level that a taper's out-of-band leakage would deliver,
+    and it is what Thomson's Eq. 5.1b multiplies by ``1 - lambda_k``. It must
+    be expressed in the *same units as the eigenspectra*, which is the whole
+    reason it is computed from them here rather than taken from the record.
+
+    Accepts either layout. Given the full ``n`` two-sided bins the mean is
+    direct; given the ``n // 2 + 1`` non-negative bins of an ``rfft`` the
+    two-sided sum is recovered by doubling and removing the double-counted DC
+    and (for even ``n``) Nyquist terms. The two cannot be confused, since
+    ``n // 2 + 1 != n`` for any ``n >= 2``.
+    """
+    if eigenspectra.shape[-1] == n:
+        return float(eigenspectra.mean())
+    total = 2.0 * eigenspectra.sum(axis=-1) - eigenspectra[..., 0]
+    if n % 2 == 0:
+        total -= eigenspectra[..., -1]
+    return float((total / n).mean())
+
+
+def center_on_energy_centroid(
+    x: NDArray[np.float64], edge_tolerance: float
+) -> NDArray[np.float64]:
+    """Circularly shift ``x`` so its energy centroid sits mid-window.
+
+    Legitimate because ``|FFT|`` is invariant under a circular shift: the
+    quantity being estimated does not change, only its alignment with the
+    tapers. Shared by every estimator that offers ``center``, so the wrap
+    check cannot drift between them.
+
+    Raises when the window edges are not quiet enough to roll without
+    splicing a discontinuity into the record.
+    """
+    energy = x**2
+    centroid = int((np.arange(x.size) * energy).sum() / energy.sum())
+    rolled: NDArray[np.float64] = np.roll(x, x.size // 2 - centroid)
+    peak = float(np.abs(rolled).max())
+    if peak > 0:
+        step = abs(float(rolled[0]) - float(rolled[-1])) / peak
+        if step > edge_tolerance:
+            raise ValueError(
+                f"Centring would introduce a discontinuity of {step:.3f} of "
+                f"the record's peak at the wrap point, above "
+                f"center_edge_tolerance={edge_tolerance}. The "
+                f"window edges are not quiet enough to roll; taper first, "
+                f"widen the window, or use FFTEstimator, which is "
+                f"position-stable without centring."
+            )
+    return rolled
+
+
+def _adaptive_weights(
+    eigenspectra: NDArray[np.float64],
+    eigenvalues: NDArray[np.float64],
+    n: int,
+    *,
+    max_iter: int = 1000,
+    tol: float = 9.5e-7,
+) -> NDArray[np.float64]:
+    """Thomson's adaptive weights.
+
+    Higher-order tapers leak more, so weighting them equally lets out-of-band
+    power contaminate the estimate. The weights downweight a taper wherever its
+    broadband leakage would dominate the local signal, which matters here: a
+    seismic spectrum spans orders of magnitude in amplitude, so leakage from the
+    peak can swamp the high-frequency tail entirely.
+
+    Iterates ``w_k = sqrt(lambda_k) * S / (lambda_k * S + b_k)`` to convergence,
+    with ``b_k = (1 - lambda_k) * sigma^2`` from Thomson Eq. 5.1b, and clips the
+    weights at unity so that an unbiased taper is weighted exactly once.
+
+    ``sigma^2`` is derived from the eigenspectra rather than supplied, which
+    makes the routine invariant to how the caller has scaled them. That is not
+    a stylistic choice: passing the record's *time-domain* variance against
+    eigenspectra already scaled to PSD overstates ``b_k`` by a factor of
+    ``1/dt``, which drives every weight towards zero for any record whose
+    energy is concentrated away from the taper centre. See the module docstring.
+    """
+    sigma2 = _broadband_power(eigenspectra, n)
+    b_k = (1.0 - eigenvalues)[:, None] * sigma2
+    sqrt_lambda = np.sqrt(eigenvalues)[:, None]
+    lam = eigenvalues[:, None]
+
+    # Start from the two least-leaky tapers, as Thomson recommends.
+    spectrum = eigenspectra[:2].mean(axis=0)
+    weights = np.ones_like(eigenspectra)
+    for _ in range(max_iter):
+        denom = np.maximum(lam * spectrum + b_k, 1e-300)
+        weights = np.minimum(sqrt_lambda * spectrum / denom, 1.0)
+        w2 = weights**2
+        updated = (w2 * eigenspectra).sum(axis=0) / np.maximum(w2.sum(axis=0), 1e-300)
+        change = np.abs(updated - spectrum) / np.maximum(updated + spectrum, 1e-300)
+        spectrum = updated
+        if change.max() < tol:
+            break
+    return weights
+
+
+@dataclass(frozen=True)
+class MultitaperEstimator:
+    """Multitaper spectrum estimate.
+
+    Parameters
+    ----------
+    time_bandwidth
+        The time-bandwidth product ``NW``. Larger values reduce variance and
+        leakage at the cost of frequency resolution. In the pre-refactor code
+        this was the literal ``3`` passed positionally to ``mtspec``, with no
+        way to configure it.
+    n_tapers
+        Number of DPSS tapers. Must not exceed ``2*NW - 1``, beyond which the
+        tapers are poorly concentrated and add leakage rather than reducing
+        variance; exceeding it raises rather than silently degrading.
+    adaptive
+        Apply Thomson's adaptive weighting. When ``False``, tapers are averaged
+        with equal weight.
+
+        On by default, because leakage suppression is the reason to reach for
+        multitaper at all and flat weighting does not provide it. Measured on a
+        2 Hz line 10^6 times stronger than the background — a mild version of
+        what a seismic spectrum does across its band — the recovered noise
+        floor between 20 and 49 Hz sits **287x** above the truth with flat
+        weighting and **1.1x** with adaptive. A Brune fit reads ``t*`` and
+        ``f_c`` off exactly that high-frequency decay, so an inflated floor is
+        not a cosmetic problem.
+
+        The cost is resolution: adaptive weighting downweights the higher-order
+        tapers wherever leakage would dominate, so it uses fewer effective
+        degrees of freedom and gives a noisier estimate in bands where the
+        signal is strong. Turn it off for a well-conditioned record with little
+        dynamic range, where the extra averaging is worth more than the leakage
+        rejection.
+    center
+        Circularly shift the record so its energy centroid sits mid-window
+        before estimating.
+
+        This removes the position dependence **entirely** rather than reducing
+        it: measured across start positions from 2% to 78%, the recovered
+        energy ratio is identical to three decimal places once centred, and the
+        spectrum matches the naturally-centred case exactly. It is legitimate
+        because ``|FFT|`` is invariant under a circular shift, so the quantity
+        being estimated does not change.
+
+        What remains after centring is the taper concentration itself — a
+        compact centred transient still reads about 1.16x high with flat
+        weighting. That bias is *consistent* rather than position-dependent,
+        which matters: a consistent multiplicative bias cancels in any ratio
+        (signal-to-noise, spectral ratios, relative amplitudes between stations)
+        and can be calibrated, where a position-dependent one cannot.
+
+        Off by default because a circular shift wraps. It is safe when the
+        window edges are quiet, and refuses when they are not — see
+        ``center_edge_tolerance``.
+    center_edge_tolerance
+        Maximum amplitude at the wrap point, as a fraction of the record's
+        peak, before centring raises rather than introducing a discontinuity.
+        A window whose coda is still strong at the end cannot be safely rolled.
+    normalize_to_variance
+        Rescale the whole spectrum so it integrates to the record's variance,
+        as Prieto's ``multitaper`` package does (``mtspec.py``: ``sscal =
+        xvar / (sum(spec)*df)``). ``mtspec`` wrapped the same lineage, so
+        **enable this when reproducing pre-refactor results.**
+
+        Off by default because it costs you a diagnostic. With it on,
+        ``Spectrum.energy()`` returns the input energy whatever else is wrong,
+        so it can no longer tell you whether the normalisation is sound — the
+        one check that would catch a mis-scaled spectrum always passes. Left
+        off, ``energy()`` is a live measurement of your own record.
+
+        It is a calibration, not a derivation: a single scalar chosen to force
+        the integral, which is why it cannot change spectral *shape*. Total
+        power comes out right and the shape absorbs whatever error remains, so
+        it does not make the long-period level position-independent — see the
+        warning above, and ``center`` for something that does.
+    """
+
+    time_bandwidth: float = 3.0
+    n_tapers: int = 5
+    adaptive: bool = True
+    center: bool = False
+    center_edge_tolerance: float = 0.05
+    normalize_to_variance: bool = False
+    drop_dc: bool = True
+    name: str = "multitaper"
+
+    def __post_init__(self) -> None:
+        if self.time_bandwidth <= 0:
+            raise ValueError(
+                f"time_bandwidth must be positive, got {self.time_bandwidth}"
+            )
+        limit = int(2 * self.time_bandwidth - 1)
+        if self.n_tapers < 1:
+            raise ValueError(f"n_tapers must be at least 1, got {self.n_tapers}")
+        if self.n_tapers > limit:
+            raise ValueError(
+                f"n_tapers={self.n_tapers} exceeds 2*NW-1={limit} for "
+                f"time_bandwidth={self.time_bandwidth}. Tapers beyond that are "
+                f"poorly concentrated and add leakage rather than reducing "
+                f"variance; raise time_bandwidth or lower n_tapers."
+            )
+
+    def _centered(self, x: NDArray[np.float64]) -> NDArray[np.float64]:
+        return center_on_energy_centroid(x, self.center_edge_tolerance)
+
+    def estimate(
+        self,
+        data: ArrayLike,
+        dt: float,
+        *,
+        motion: Motion | str = Motion.VELOCITY,
+        meta: dict[str, Any] | None = None,
+    ) -> Spectrum:
+        x, n, duration = prepare_record(data, dt)
+        if self.center:
+            x = self._centered(x)
+
+        tapers, eigenvalues = dpss(
+            n, self.time_bandwidth, self.n_tapers, sym=False, return_ratios=True
+        )
+        # DPSS tapers are unit-norm; scale so each eigenspectrum is a PSD in
+        # [x]^2/Hz, then fold to one-sided.
+        spectra = np.fft.rfft(tapers * x, axis=-1)
+        eigenspectra = (np.abs(spectra) ** 2) * dt
+
+        if self.adaptive and self.n_tapers > 1:
+            weights = _adaptive_weights(eigenspectra, eigenvalues, n)
+            w2 = weights**2
+            psd = (w2 * eigenspectra).sum(axis=0) / np.maximum(w2.sum(axis=0), 1e-300)
+        else:
+            psd = eigenspectra.mean(axis=0)
+
+        freq: NDArray[np.float64] = np.fft.rfftfreq(n, d=dt).astype(np.float64)
+        psd[1:] *= 2.0  # fold negative frequencies
+        if n % 2 == 0:
+            psd[-1] /= 2.0
+
+        if self.normalize_to_variance:
+            # Prieto's convention: pin the integral to the record variance.
+            df = float(freq[1] - freq[0])
+            total = float(psd.sum() * df)
+            if total > 0:
+                psd = psd * (float(x.var()) / total)
+
+        if self.drop_dc:
+            freq, psd = freq[1:], psd[1:]
+
+        spectrum = build_spectrum(
+            freq,
+            psd,
+            kind=AmplitudeKind.PSD,
+            motion=motion,
+            duration=duration,
+            sampling_rate=1.0 / dt,
+            meta={
+                **(meta or {}),
+                "time_bandwidth": self.time_bandwidth,
+                "n_tapers": self.n_tapers,
+                "adaptive": self.adaptive,
+                "centered": self.center,
+                "normalize_to_variance": self.normalize_to_variance,
+            },
+            estimator=self.name,
+        )
+        return spectrum.to_kind(AmplitudeKind.FAS)

specmod/transforms/prieto.py

@@ -0,0 +1,272 @@
+"""Backend for Prieto's ``multitaper`` package.
+
+The direct successor to the Fortran library that ``mtspec`` wrapped, by the same
+author and pure Python. It is worth having alongside
+:class:`~specmod.transforms.multitaper.MultitaperEstimator` for three reasons:
+
+1. **It is the closest available proxy for pre-refactor behaviour.** ``mtspec``
+   wrapped the same lineage, so when the phase-0 comparison asks "did the old
+   code do this", this is the cheapest way to ask.
+2. **Jackknife confidence intervals** and the **F-test for spectral lines**,
+   which the native implementation does not provide.
+3. It is an independent implementation, so disagreement between the two is
+   informative rather than invisible.
+
+Installed with ``pip install specmod[multitaper]``.
+
+What actually works
+-------------------
+Verified against ``multitaper`` 1.2 on numpy 2. Several of the package's less
+travelled paths carry shape bugs that only surface under current numpy, so the
+usable surface is narrower than the documentation implies:
+
+============= ========= ========== ==============
+Method        adaptive  constant   eigenvalue
+============= ========= ========== ==============
+``spec``      works     works      works
+``ftest``     works     works      works
+``jackspec``  works     **fails**  works
+``qiinv``     **fails** **fails**  **fails**
+============= ========= ========== ==============
+
+``qiinv`` is the quadratic multitaper of Prieto *et al.* (2007) — the
+higher-resolution estimate the 2022 paper recommends over adaptive weighting
+for resolving peaks, and therefore the one that would most interest a corner
+frequency measurement. It raises ``ValueError`` in
+``multitaper.utils.qiinv`` for every weighting, so it is **not exposed here**.
+Both failures are upstream and neither is worked around; they are reported with
+their cause so the fix is obvious if upstream lands one.
+
+Normalisation
+-------------
+**This backend always rescales the spectrum to integrate to the record
+variance** (``mtspec.py``: ``sscal = xvar / (sum(spec)*df)``). That is baked
+into ``MTSpec`` and cannot be switched off.
+
+The consequence matters: ``Spectrum.energy()`` on the result recovers the input
+energy *by construction*, whatever the taper weighting did. It is therefore not
+an independent check that the estimate is sound, and it means this backend is
+immune to the position-dependent energy bias described in
+:mod:`specmod.transforms.multitaper` — but only for total energy, not for the
+shape of the spectrum. See ``docs/choosing-a-transform.md``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any, Literal
+
+import numpy as np
+from numpy.typing import ArrayLike, NDArray
+
+from ..core.spectrum import Spectrum
+from ..core.units import AmplitudeKind, Motion
+from .base import build_spectrum, prepare_record
+
+__all__ = ["PrietoMultitaperEstimator"]
+
+Weighting = Literal["adaptive", "constant", "eigenvalue"]
+
+#: Prieto's ``iadapt`` codes.
+_IADAPT: dict[str, int] = {"adaptive": 0, "constant": 1, "eigenvalue": 2}
+
+
+def _require_multitaper() -> Any:
+    try:
+        # Deferred so the package stays importable without the extra: this is
+        # an optional backend, and a missing one should be a clear error at
+        # call time rather than an ImportError from `import specmod`.
+        from multitaper import MTSpec  # noqa: PLC0415
+    except ImportError as exc:  # pragma: no cover - depends on the environment
+        raise ImportError(
+            "The 'multitaper' package is not installed. It is an optional "
+            "backend; install it with `pip install specmod[multitaper]`."
+        ) from exc
+    return MTSpec
+
+
+def _one_sided(
+    freq: NDArray[np.float64], spec: NDArray[np.float64]
+) -> tuple[NDArray[np.float64], NDArray[np.float64]]:
+    """Fold ``MTSpec``'s output into SpecMod's one-sided PSD convention.
+
+    Two conversions, both easy to get wrong silently:
+
+    - ``MTSpec.freq`` comes back in **FFT order** (0, +f..., -f...), not sorted.
+      Integrating over it without sorting runs backwards through the negative
+      half and returns a partly-cancelled, sometimes negative, result.
+    - The spectrum is **two-sided**, normalised so the full integral equals the
+      variance. SpecMod's PSD is one-sided with the same total, so folding
+      doubles every non-DC bin.
+    """
+    order = np.argsort(freq)
+    freq, spec = freq[order], spec[order]
+    positive = freq > 0
+    return freq[positive], spec[positive] * 2.0
+
+
+@dataclass(frozen=True)
+class PrietoMultitaperEstimator:
+    """Multitaper estimate via Prieto's ``multitaper`` package.
+
+    Parameters
+    ----------
+    time_bandwidth, n_tapers
+        As for :class:`~specmod.transforms.multitaper.MultitaperEstimator`.
+    weighting
+        ``adaptive`` is Prieto's default. ``constant`` weights the tapers
+        equally; ``eigenvalue`` weights by the concentration ratios.
+    n_fft
+        Transform length. ``None`` leaves ``MTSpec``'s own default, which pads.
+        Padding refines the frequency grid; ``duration`` stays the physical
+        record length either way.
+    """
+
+    time_bandwidth: float = 3.0
+    n_tapers: int = 5
+    weighting: Weighting = "adaptive"
+    n_fft: int | None = None
+    drop_dc: bool = True
+    name: str = "prieto"
+
+    def __post_init__(self) -> None:
+        if self.weighting not in _IADAPT:
+            raise ValueError(
+                f"Unknown weighting {self.weighting!r}; "
+                f"expected one of {sorted(_IADAPT)}."
+            )
+        if self.time_bandwidth <= 0:
+            raise ValueError(
+                f"time_bandwidth must be positive, got {self.time_bandwidth}"
+            )
+        limit = int(2 * self.time_bandwidth - 1)
+        if not 1 <= self.n_tapers <= limit:
+            raise ValueError(
+                f"n_tapers={self.n_tapers} must be between 1 and 2*NW-1={limit} "
+                f"for time_bandwidth={self.time_bandwidth}."
+            )
+
+    def _mtspec(self, x: NDArray[np.float64], dt: float) -> Any:
+        MTSpec = _require_multitaper()
+        return MTSpec(
+            x,
+            nw=self.time_bandwidth,
+            kspec=self.n_tapers,
+            dt=dt,
+            nfft=0 if self.n_fft is None else int(self.n_fft),
+            iadapt=_IADAPT[self.weighting],
+        )
+
+    def estimate(
+        self,
+        data: ArrayLike,
+        dt: float,
+        *,
+        motion: Motion | str = Motion.VELOCITY,
+        meta: dict[str, Any] | None = None,
+    ) -> Spectrum:
+        x, _n, duration = prepare_record(data, dt)
+        mt = self._mtspec(x, dt)
+        freq, psd = _one_sided(
+            np.asarray(mt.freq, dtype=np.float64).ravel(),
+            np.asarray(mt.spec, dtype=np.float64).ravel(),
+        )
+        if not self.drop_dc:  # DC was dropped by the f > 0 mask
+            freq = np.concatenate([[0.0], freq])
+            psd = np.concatenate([[0.0], psd])
+
+        spectrum = build_spectrum(
+            freq,
+            psd,
+            kind=AmplitudeKind.PSD,
+            motion=motion,
+            duration=duration,
+            sampling_rate=1.0 / dt,
+            meta={
+                **(meta or {}),
+                "time_bandwidth": self.time_bandwidth,
+                "n_tapers": self.n_tapers,
+                "weighting": self.weighting,
+                # Not optional in this backend — see the module docstring.
+                "normalize_to_variance": True,
+            },
+            estimator=self.name,
+        )
+        return spectrum.to_kind(AmplitudeKind.FAS)
+
+    def confidence_interval(
+        self, data: ArrayLike, dt: float, *, motion: Motion | str = Motion.VELOCITY
+    ) -> tuple[Spectrum, Spectrum]:
+        """Jackknife 95% confidence bounds, as two FAS spectra.
+
+        The main reason to reach for this backend rather than the native one.
+        The interval is log-symmetric about the estimate — measured at roughly
+        2.5x either way for ``nw=3, kspec=5``.
+
+        .. note::
+
+           Upstream inverts the two bounds for a small fraction of bins (~2%
+           in testing), so ``low <= high`` does not hold everywhere. Sort the
+           pair per-bin if you need that guarantee.
+
+        Raises
+        ------
+        NotImplementedError
+            For ``weighting="constant"``. This is an upstream bug, not a
+            limitation: in ``multitaper.utils.jackspec`` the degrees-of-freedom
+            array ``se`` keeps shape ``(nfft, 1)`` under constant weighting, so
+            ``t.ppf(...) * sqrt(var[:, 0])`` broadcasts to ``(nfft, nfft)``
+            instead of elementwise and raises. ``adaptive`` and ``eigenvalue``
+            are unaffected.
+        """
+        if self.weighting == "constant":
+            raise NotImplementedError(
+                "Jackknife intervals are unavailable for weighting='constant' "
+                "due to a shape bug in multitaper.utils.jackspec. Use "
+                "weighting='adaptive' or 'eigenvalue'."
+            )
+        x, _n, duration = prepare_record(data, dt)
+        mt = self._mtspec(x, dt)
+        ci = np.asarray(mt.jackspec(), dtype=np.float64)
+        raw_freq = np.asarray(mt.freq, dtype=np.float64).ravel()
+
+        bounds = []
+        for column in (0, 1):
+            freq, psd = _one_sided(raw_freq, ci[:, column].ravel())
+            bounds.append(
+                build_spectrum(
+                    freq,
+                    psd,
+                    kind=AmplitudeKind.PSD,
+                    motion=motion,
+                    duration=duration,
+                    sampling_rate=1.0 / dt,
+                    meta={
+                        "weighting": self.weighting,
+                        "bound": ("low", "high")[column],
+                    },
+                    estimator=self.name,
+                ).to_kind(AmplitudeKind.FAS)
+            )
+        return bounds[0], bounds[1]
+
+    def f_test(
+        self, data: ArrayLike, dt: float
+    ) -> tuple[NDArray[np.float64], NDArray[np.float64], NDArray[np.float64]]:
+        """Thomson's F-test for periodic (line) components.
+
+        Returns ``(freq, F, p)`` on the one-sided axis. Useful for spotting
+        instrumental or cultural tones that would otherwise be mistaken for
+        source structure.
+        """
+        x, _n, _duration = prepare_record(data, dt)
+        mt = self._mtspec(x, dt)
+        f_statistic, p_value = mt.ftest()
+        raw_freq = np.asarray(mt.freq, dtype=np.float64).ravel()
+        order = np.argsort(raw_freq)
+        positive = raw_freq[order] > 0
+        return (
+            raw_freq[order][positive],
+            np.asarray(f_statistic, dtype=np.float64).ravel()[order][positive],
+            np.asarray(p_value, dtype=np.float64).ravel()[order][positive],
+        )