gwexpy.interop.multitaper_

Interoperate with multitaper spectral estimation packages.

Interoperability with multitaper spectral estimation packages.

Two packages are supported:

  • multitaper (Prieto) — object-oriented API via MTSpec / MTSine. Install with pip install multitaper.

  • mtspec (Krischer) — function-based API returning (spectrum, freq). Install with pip install mtspec.

Both are converted to FrequencySeries (or FrequencySeriesDict when confidence intervals are requested).

References

Prieto, G. A. (2022). The multitaper spectrum analysis package in Python. Seismological Research Letters.

Krischer, L. et al. — https://github.com/krischer/mtspec

Functions

from_mtspec(cls, mt, *[, quantity, include_ci])

Convert a Prieto MTSpec / MTSine object to a GWexpy type.

from_mtspec_array(cls, spectrum, freq, *[, ...])

Convert Krischer mtspec function output to a GWexpy type.
gwexpy.interop.multitaper_.from_mtspec(cls: type, mt: Any, *, quantity: Literal['psd', 'asd'] = 'psd', include_ci: bool = True) → Any[source]

Convert a Prieto MTSpec / MTSine object to a GWexpy type.

Parameters:

  • cls (type) – Target type. Pass FrequencySeries to always receive a plain spectrum (CI is discarded even when available). Pass FrequencySeriesDict to receive a dict that includes CI series when CI is available.

  • mt (multitaper.mtspec.MTSpec or multitaper.mtsine.MTSine) –

    Computed multitaper object. Expected attributes:

    • freq : ndarray (nf,) — frequency axis [Hz]

    • spec : ndarray (nf,) — adaptive-weighted PSD

    • spec_ci : ndarray (nf, 2) — 95 % jackknife CI [lower, upper] (optional; not present on MTSine)

    • se : ndarray (nf,) — degrees of freedom per bin (optional)

  • quantity ({"psd", "asd"}, default "psd") – Whether to return power or amplitude spectral density. "asd" applies np.sqrt to the PSD.

  • include_ci (bool, default True) – If True and the object carries spec_ci, return a FrequencySeriesDict with keys "psd"/"asd", "ci_lower", and "ci_upper". Ignored when the CI attribute is absent.

Returns:

  • FrequencySeries – When CI is unavailable or include_ci=False.

  • FrequencySeriesDict – When CI is available and include_ci=True.

Raises:

ValueError – If quantity is not "psd" or "asd", or if the frequency axis is empty.

gwexpy.interop.multitaper_.from_mtspec_array(cls: type, spectrum: ndarray, freq: ndarray, *, quantity: Literal['psd', 'asd'] = 'psd', ci_lower: ndarray | None = None, ci_upper: ndarray | None = None, unit: Any | None = None) → Any[source]

Convert Krischer mtspec function output to a GWexpy type.

Parameters:

  • cls (type) – Target type. Pass FrequencySeries to always receive a plain spectrum (CI is discarded even when available). Pass FrequencySeriesDict to receive a dict that includes CI series when CI is available.

  • spectrum (array-like, shape (nf,)) – PSD (or ASD, depending on quantity) array returned by mtspec.mtspec().

  • freq (array-like, shape (nf,)) – Frequency axis [Hz] returned by mtspec.mtspec().

  • quantity ({"psd", "asd"}, default "psd") – Whether spectrum is a PSD or ASD. Set to "asd" to interpret the input as amplitude spectral density.

  • ci_lower (array-like, shape (nf,), optional) – Lower confidence-interval bound (same units as spectrum).

  • ci_upper (array-like, shape (nf,), optional) – Upper confidence-interval bound (same units as spectrum).

  • unit (str or astropy.units.Unit, optional) – Physical unit of the spectral density values.

Returns:

  • FrequencySeries – When ci_lower and ci_upper are both None.

  • FrequencySeriesDict – When either CI array is provided. Keys: "psd"/"asd", "ci_lower", "ci_upper".

Raises:

ValueError – If quantity is not "psd" or "asd", if freq is not equally spaced, or if shapes are inconsistent.