API Overview¶

The public API centres on three data classes and a handful of signal-processing helpers. The full auto-generated reference is below; this page is a quick orientation.

At A Glance¶

Object	Purpose	Key methods
`TimeSeries`	Sampled time-domain data plus `dt`	`to_frequency_series()`, `to_wdm()`, `plot()`
`FrequencySeries`	FFT-domain data plus `df`	`to_time_series()`, `to_wdm()`, `plot()`
`WDM`	Packed \((N_t,\, N_f+1)\) real coefficients plus transform metadata	`to_time_series()`, `to_frequency_series()`, `plot()`

All three accept either a single array (n,) or a leading-batch layout (batch, n) and store data canonically as batched. The WDM class stores coefficients as (batch, nt, nf + 1).

Window Selection And Reconstruction¶

Every full forward path accepts the same keyword-only window options:

import numpy as np
from wdm_transform import TimeSeries

ts = TimeSeries(np.sin(2*np.pi*np.arange(8192)/128), dt=5.0)
meyer = ts.to_wdm(nt=256, window="meyer")
gaussian = ts.to_wdm(nt=256, window="gaussian", nu=0.5, support=16)
recovered = gaussian.to_time_series()

This applies to both series classes, WDM.from_time_series, WDM.from_frequency_series, and the low-level full transform functions. WDM.window, WDM.nu, and WDM.support retain the effective configuration. Their fields follow the historical positional constructor arguments and are keyword-only. Gaussian resolves omitted nu to 0.5 and omitted support to min(16,nf). nu is currently validated in [0.3,0.8], and explicit support must be an integer in [1,nf].

WDM inverse methods automatically use these stored parameters. Inverse functions receiving a bare coefficient array require the caller to preserve and pass its window configuration. Identical shape does not make projections in the two bases interchangeable: reconstruct and transform again to switch.

The full Fourier interface accepts the complete complex FFT grid, including negative frequencies. Its existing projection onto a Hermitian spectrum is preserved; it does not accept an rFFT half-spectrum as a substitute.

Compact subband functions and span helpers accept the same window, nu and support options. Omitted Fourier bins or coefficient channels are treated as zero. Reuse the originating settings for inverse synthesis; Gaussian requires wider frequency margins. See Choosing a window for support and noise-model limitations and full function signatures.

Backend Selection¶

wdm-transform ships with a NumPy backend by default. The JAX backend is opt-in:

import wdm_transform as wt
wt.get_backend()                  # default NumPy backend
wt.get_backend("jax")             # opt in to the JAX backend (auto-loaded)

The WDM_BACKEND environment variable provides the same selection without code changes (e.g. WDM_BACKEND=jax).

See Reconstruction and Inference and the Benchmarks page for a runtime comparison.

Data Classes¶

TimeSeries `dataclass` ¶

Sampled time-domain data.

Parameters¶

data : array_like Sample values on a uniform time grid with shape (n,) or (batch, n). Stored internally as (batch, n). dt : float Time spacing between adjacent samples. backend : Backend Array backend used for computation.

n `property` ¶

n: int

Number of samples per series.

batch_size `property` ¶

batch_size: int | None

Leading batch size.

df `property` ¶

df: float

Fourier frequency spacing implied by the sample cadence.

fs `property` ¶

fs: float

Sampling frequency of the underlying time-domain grid.

nyquist `property` ¶

nyquist: float

Nyquist frequency of the underlying sampled signal.

duration `property` ¶

duration: float

Total signal duration n * dt.

This follows the discrete-Fourier convention used throughout the package, not times[-1] - times[0].

times `property` ¶

times: Any

Sample-time grid arange(n) * dt.

to_frequency_series ¶

to_frequency_series() -> 'FrequencySeries'

Return the discrete Fourier transform of this series.

The output keeps the same backend and uses the Fourier spacing implied by self.dt.

to_wdm ¶

to_wdm(*, nt: int, a: float = 1.0 / 3.0, d: float = 1.0, backend: str | Backend | None = None, window: Literal['meyer', 'gaussian'] = 'meyer', nu: float | None = None, support: int | None = None) -> 'WDM'

Compute Wilson coefficients, optionally using the Gaussian window.

Gaussian nu defaults to 0.5; support defaults to min(16, nf) half-band spacings. Both options must be omitted for Meyer.

plot ¶

plot(**kwargs: Any) -> tuple[Any, Any]

Plot the time-domain samples using the shared plotting helper.

FrequencySeries `dataclass` ¶

FFT-domain data with spacing metadata.

Parameters¶

data : array_like Spectrum samples on the discrete Fourier grid with shape (n,) or (batch, n). Stored internally as (batch, n). df : float Frequency spacing between adjacent Fourier bins. backend : Backend Array backend used for computation.

n `property` ¶

n: int

Number of Fourier bins per series.

batch_size `property` ¶

batch_size: int | None

Leading batch size.

dt `property` ¶

dt: float

Time spacing implied by the discrete Fourier grid.

fs `property` ¶

fs: float

Sampling frequency of the underlying time-domain signal.

nyquist `property` ¶

nyquist: float

Nyquist frequency of the underlying sampled signal.

duration `property` ¶

duration: float

Total signal duration n * dt represented by the spectrum.

freqs `property` ¶

freqs: Any

Discrete Fourier frequency grid.

to_time_series ¶

to_time_series(*, real: bool = False) -> TimeSeries

Return the inverse discrete Fourier transform as a time series.

Parameters¶

real : bool, default=False If True, discard any residual imaginary part after the inverse FFT and return a real-valued series.

to_wdm ¶

to_wdm(*, nt: int, a: float = 1.0 / 3.0, d: float = 1.0, backend: str | Backend | None = None, window: Literal['meyer', 'gaussian'] = 'meyer', nu: float | None = None, support: int | None = None) -> 'WDM'

Compute Wilson coefficients from full complex Fourier samples.

Gaussian nu defaults to 0.5; support defaults to min(16, nf) half-band spacings. Both options must be omitted for Meyer.

plot ¶

plot(**kwargs: Any) -> tuple[Any, Any]

Plot the spectrum using the shared plotting helper.

WDM `dataclass` ¶

Real-valued Wilson coefficients together with transform metadata.

Parameters¶

coeffs : array, shape (nt, nf + 1) or (batch, nt, nf + 1) Real-valued coefficient matrix. Column m corresponds to frequency channel m (0 ≤ m ≤ nf). Stored internally as (batch, nt, nf + 1). dt : float Sampling interval of the original time-domain signal. a : float Window roll-off parameter (default 1/3). d : float Reserved window parameter (default 1, currently unused). backend : Backend Array backend used for computation. window : {"meyer", "gaussian"}, keyword-only Window family used to compute the coefficients. Gaussian means the orthogonalized modified-Gaussian Wilson window, not a raw taper. nu : float or None, keyword-only Gaussian shape parameter; defaults to 0.5 for Gaussian and must be omitted for Meyer. support : int or None, keyword-only Gaussian half-band spacings retained on each side of the window center. Defaults to min(16, nf) and must be omitted for Meyer.

Notes¶

The inverse always uses these originating window parameters. Changing basis requires reconstructing and transforming again; changing metadata alone does not convert the coefficients to another basis. The default a=1/3 and d=1 are ignored for Gaussian; other values are rejected.

from_time_series `classmethod` ¶

from_time_series(series: TimeSeries, *, nt: int, a: float = 1.0 / 3.0, d: float = 1.0, backend: str | Backend | None = None, window: Literal['meyer', 'gaussian'] = 'meyer', nu: float | None = None, support: int | None = None) -> 'WDM'

Compute Wilson coefficients of a time-domain signal.

Parameters¶

series : TimeSeries Input signal. Its length must be divisible by nt. nt : int Number of WDM time bins (must be even). a : float Window roll-off parameter. d : float Reserved (unused). backend : str, Backend, or None Override backend; defaults to the series' backend. window : {"meyer", "gaussian"} Window family. Meyer preserves the historical default. nu : float or None Gaussian shape parameter (default 0.5); omitted for Meyer. support : int or None Gaussian support in half-band spacings (default min(16, nf)). Small nf can limit reconstruction accuracy.

from_frequency_series `classmethod` ¶

from_frequency_series(series: FrequencySeries, *, nt: int, a: float = 1.0 / 3.0, d: float = 1.0, backend: str | Backend | None = None, window: Literal['meyer', 'gaussian'] = 'meyer', nu: float | None = None, support: int | None = None) -> 'WDM'

Compute the forward WDM transform from a frequency-domain signal.

Any non-Hermitian component of series is discarded so the result matches applying the WDM transform to real(ifft(series.data)).

Parameters¶

series : FrequencySeries Input spectrum. Its length must be divisible by nt. nt : int Number of WDM time bins (must be even). a : float Window roll-off parameter. d : float Reserved (unused). backend : str, Backend, or None Override backend; defaults to the series' backend. window : {"meyer", "gaussian"} Window family. Meyer preserves the historical default. nu : float or None Gaussian shape parameter (default 0.5); omitted for Meyer. support : int or None Gaussian support in half-band spacings (default min(16, nf)). Small nf can limit reconstruction accuracy.

nt `property` ¶

nt: int

Number of WDM time bins.

nf `property` ¶

nf: int

Number of interior frequency channels.

The total number of frequency channels is nf + 1 (m = 0, 1, …, nf), so coeffs.shape[-1] == nf + 1.

shape `property` ¶

shape: tuple[int, ...]

Shape of the stored coefficient array.

batch_size `property` ¶

batch_size: int | None

Leading batch size.

n `property` ¶

n: int

Total number of time-domain samples represented by this transform.

df `property` ¶

df: float

Fourier-bin spacing of the underlying original signal.

This is the discrete-Fourier spacing implied by the original sample cadence. For the WDM frequency-grid spacing, use :attr:delta_f.

fs `property` ¶

fs: float

Sampling frequency of the underlying original time series.

nyquist `property` ¶

nyquist: float

Nyquist frequency of the underlying original signal.

This is also the frequency of the highest WDM channel, freq_grid[-1].

delta_t `property` ¶

delta_t: float

Spacing of the WDM time grid.

Each WDM time bin spans nf * dt in the original sampling. For the underlying original sample spacing, use :attr:dt.

delta_f `property` ¶

delta_f: float

Spacing of the WDM frequency grid.

This is the spacing between adjacent WDM channels. For the underlying Fourier-bin spacing of the original signal, use :attr:df.

duration `property` ¶

duration: float

Total signal duration nt * delta_t represented by this transform.

Equivalently, this is nt * nf * dt. This convention matches the transform construction and is not the same as time_grid[-1] - time_grid[0].

time_grid `property` ¶

time_grid: Any

WDM time-grid coordinates arange(nt) * delta_t.

freq_grid `property` ¶

freq_grid: Any

WDM frequency-grid coordinates arange(nf + 1) * delta_f.

dc_channel `property` ¶

dc_channel: Any

DC edge-channel coefficients (m = 0).

nyquist_channel `property` ¶

nyquist_channel: Any

Nyquist edge-channel coefficients (m = nf).

to_time_series ¶

to_time_series() -> TimeSeries

Reconstruct the time-domain signal via the inverse WDM transform.

to_frequency_series ¶

to_frequency_series() -> FrequencySeries

Reconstruct the frequency-domain signal from the Gabor atom expansion.

plot ¶

plot(**kwargs: Any) -> tuple[Any, Any]

Plot the WDM coefficient grid using the shared plotting helper.

Signal Processing Helpers¶

matched_filter_snr_rfft ¶

matched_filter_snr_rfft(coeffs: ndarray, noise_psd: ndarray, freqs: ndarray, *, dt: float) -> float

Matched-filter SNR using one-sided PSD and NumPy rFFT coefficients.

matched_filter_snr_wdm ¶

matched_filter_snr_wdm(coeffs: ndarray, noise_var: ndarray) -> float

Matched-filter SNR for real WDM coefficients with diagonal noise variance.

Equal to sqrt(<h, h>) with :func:wdm_inner_product; NaN-flagged DC/Nyquist edge channels are skipped automatically.

noise_characteristic_strain ¶

noise_characteristic_strain(noise_psd: ndarray, freqs: ndarray) -> np.ndarray

Convert a one-sided PSD into characteristic noise strain.

rfft_characteristic_strain ¶

rfft_characteristic_strain(coeffs: ndarray, freqs: ndarray, dt: float) -> np.ndarray

Convert deterministic one-sided rFFT coefficients into characteristic strain.

rfft_periodogram_characteristic_strain ¶

rfft_periodogram_characteristic_strain(coeffs: ndarray, freqs: ndarray, dt: float) -> np.ndarray

Convert one-sided rFFT coefficients into a PSD-estimator characteristic strain.

This is the quantity comparable to :func:noise_characteristic_strain for a stochastic data realization. It uses the one-sided periodogram S_hat = 2 * df * dt**2 * |X_k|**2 for positive-frequency bins.

wdm_noise_variance ¶

wdm_noise_variance(noise_psd: ndarray, *, nt: int, nf: int, dt: float) -> np.ndarray

Diagonal WDM noise variance for interior channels.

For stationary noise with one-sided PSD S(f), the per-pixel WDM coefficient variance under the discrete-FFT normalisation used here is

sigma^2_{nm} = N * S(f_m) / (2 * dt)   for  1 <= m <= nf - 1

where N = nt * nf.

This channel-center PSD approximation does not integrate the selected window's spectral weights. It is not a calibrated colored-noise covariance model for Gaussian Wilson coefficients: their broader frequency support can mix different PSD values and generate correlations. For white noise, the same interior variance follows from the tested tight-frame identity, up to finite-support error. Colored-noise likelihood accuracy requires separate validation for the chosen window and support.

The DC (m=0) and Nyquist (m=nf) edge channels are returned as NaN. Those channels are overcomplete (rank-deficient) and must be excluded from any diagonal-Whittle SNR or likelihood sum. :func:matched_filter_snr_wdm skips NaN entries automatically, so callers can pass the full arrays returned by this function without manual slicing.

Parameters¶

noise_psd: One-sided physical PSD sampled at the WDM channel frequencies f_m = m * Delta_F for m = 0, 1, …, nf; shape (nf + 1,). nt, nf: WDM grid dimensions. dt: Sampling interval of the underlying time series.

Returns¶

sigma2 : ndarray, shape (nt, nf + 1) Per-pixel WDM variance, with DC (column 0) and Nyquist (column nf) set to NaN as a deliberate guardrail against including the rank-deficient edge channels in sums.

Backends¶

get_backend ¶

get_backend(backend: str | Backend | None = None) -> Backend

Resolve a backend object from a name, instance, or environment default.

register_backend ¶

register_backend(name: str, xp: Any, fft: Any) -> Backend

Register a backend by name and return the resulting backend object.

API Overview¶

At A Glance¶

Window Selection And Reconstruction¶

Backend Selection¶

Data Classes¶

TimeSeries dataclass ¶

Parameters¶

n property ¶

batch_size property ¶

df property ¶

fs property ¶

nyquist property ¶

duration property ¶

times property ¶

to_frequency_series ¶

to_wdm ¶

plot ¶

FrequencySeries dataclass ¶

Parameters¶

n property ¶

batch_size property ¶

dt property ¶

fs property ¶

nyquist property ¶

duration property ¶

freqs property ¶

to_time_series ¶

Parameters¶

to_wdm ¶

plot ¶

WDM dataclass ¶

Parameters¶

Notes¶

from_time_series classmethod ¶

Parameters¶

from_frequency_series classmethod ¶

Parameters¶

nt property ¶

nf property ¶

shape property ¶

batch_size property ¶

n property ¶

df property ¶

fs property ¶

nyquist property ¶

delta_t property ¶

delta_f property ¶

duration property ¶

time_grid property ¶

freq_grid property ¶

dc_channel property ¶

nyquist_channel property ¶

to_time_series ¶

to_frequency_series ¶

plot ¶

Signal Processing Helpers¶

matched_filter_snr_rfft ¶

matched_filter_snr_wdm ¶

noise_characteristic_strain ¶

rfft_characteristic_strain ¶

rfft_periodogram_characteristic_strain ¶

wdm_noise_variance ¶

Parameters¶

Returns¶

Backends¶

get_backend ¶

register_backend ¶

TimeSeries `dataclass` ¶

n `property` ¶

batch_size `property` ¶

df `property` ¶

fs `property` ¶

nyquist `property` ¶

duration `property` ¶

times `property` ¶

FrequencySeries `dataclass` ¶

n `property` ¶

batch_size `property` ¶

dt `property` ¶

fs `property` ¶

nyquist `property` ¶

duration `property` ¶

freqs `property` ¶

WDM `dataclass` ¶

from_time_series `classmethod` ¶

from_frequency_series `classmethod` ¶

nt `property` ¶

nf `property` ¶

shape `property` ¶

batch_size `property` ¶

n `property` ¶

df `property` ¶

fs `property` ¶

nyquist `property` ¶

delta_t `property` ¶

delta_f `property` ¶

duration `property` ¶

time_grid `property` ¶

freq_grid `property` ¶

dc_channel `property` ¶

nyquist_channel `property` ¶