Filters

class ptsa.data.filters.MorletWaveletFilter(freqs: _Buffer | _SupportsArray[dtype[Any]] | _NestedSequence[_SupportsArray[dtype[Any]]] | complex | bytes | str | _NestedSequence[complex | bytes | str], width: int = 5, output: str | Iterable[str] = ('power', 'phase'), verbose: bool = True, cpus: int = 1, output_dim: str = 'output', complete: bool = True)

Applies a Morlet wavelet transform to a time series, returning the power and phase spectra over time.

Changed in version 2.0.6: Return type is now a TimeSeries to conform with other filter types.

Parameters:

  • freqs (np.ndarray) – The frequencies to use in the decomposition.

  • width (int, optional) – The width of the wavelet (default: 5).

  • output (Union[Iterable[str], str], optional) – A string or a list of strings containing 'power', 'phase', and/or 'complex' (default: ('power', 'phase')).

  • verbose (bool, optional) – Print out the wavelet parameters (default: True).

  • cpus (int, optional) – Number of threads to use when computing the transform (default: 1).

  • output_dim (str, optional) – Name of the output dimension when returning both power and phase (default: 'output').

  • complete (bool, optional) – Use complete Morlet wavelets with a zero mean, which is required for power and phase accuracy with small wavelet widths. The frequency is kept consistent with standard Morlet wavelets (default: True).

Notes

Let \(f\) be the centre frequency, \(w\) the width (number of cycles of the carrier under the Gaussian envelope), \(\sigma_f = f / w\) the frequency-domain width of the Gaussian, and \(\sigma_t = 1 / (2 \pi \sigma_f)\) the corresponding time-domain width.

With complete=False the wavelet is the standard complex Morlet,

\[\psi(t) = \frac{1}{\sqrt{\sigma_t \sqrt{\pi}}}\, e^{-t^{2} / (2 \sigma_t^{2})}\, e^{i\, 2 \pi f t}.\]

With complete=True (the default since PTSA 2.0.6) PTSA uses the “complete” (zero-mean) form: a zero-mean correction \(e^{-w^{2}/2}\) is subtracted from the cosine arm, the amplitudes \(a_c\) (real part) and \(a_s\) (imaginary part) are rescaled analytically so the wavelet keeps unit energy, and the time axis is rescaled by

\[\textrm{freq\_scale} = \frac{2}{\pi}\, \arccos\!\left(e^{-w^{2}/2}\right)\]

so the peak frequency stays at \(f\) despite the offset:

\[\psi_{\text{complete}}(t) = a_c\, e^{-t^{2}/(2\sigma_t^{2})} \left(\cos(\text{freq\_scale} \cdot 2 \pi f t) - e^{-w^{2}/2}\right) + i\, a_s\, e^{-t^{2}/(2\sigma_t^{2})} \sin(2 \pi f t).\]

Larger width tightens the wavelet’s frequency resolution (narrower \(\sigma_f\)) at the cost of widening its time resolution (broader \(\sigma_t\)); this is the standard Heisenberg/Gabor time-frequency tradeoff.

See ptsa.extensions.morlet.get_time_domain_wavelet() for a Python reference implementation of the formula, and tests/test_morlet_formula.py for independent validation of PTSA’s FFT-based kernel against direct time-domain convolution with that reference.

filter(timeseries: TimeSeries) → TimeSeries | None

Apply the constructed filter.

Returns either a TimeSeries carrying the requested output (power, phase, complex coefficients, or stacked power+phase) or None if no output was requested. In practice filter always returns a TimeSeries for any valid configuration constructed via __init__(); the Optional reflects the defensive return phases_ts path below where the local phases_ts may not have been assigned in pathological subclasses.

class ptsa.data.filters.MorletWaveletFilterCpp

The same as ptsa.data.filters.MorletWaveletFilter, except it utilizes a C++ thread pool to parallelize the computations.

Additional keyword arguments:

  • cpus (int) - The number of threads to launch

class ptsa.data.filters.ButterworthFilter(freq_range: Sequence[float], order: int = 4, filt_type: str = 'stop')

Applies Butterworth filter to a time series.

Keyword Arguments:

  • timeseries – TimeSeries object

  • order – Butterworth filter order

  • freq_range (list-like) – Array [min_freq, max_freq] describing the filter range

  • versionchanged: (..) – 2.0: Parameter “time_series” was renamed to “timeseries”.

filter(timeseries: TimeSeries) → TimeSeries

Applies Butterwoth filter to input time series and returns filtered TimeSeries object.

Returns:

filtered – The filtered time series

Return type:

TimeSeries

class ptsa.data.filters.ResampleFilter(resamplerate: float, round_to_original_timepoints: bool = False, time_axis_name: str = 'time')

Resample a time series to a new sample rate.

Parameters:

  • resamplerate (float) – new sampling frequency

  • round_to_original_timepoints (bool) – Flag indicating if timepoints from original time axis should be reused after proper rounding. Defaults to False

  • time_axis_name (str) – Name of the time axis.

  • versionchanged: (..) – 2.0: Parameter “time_series” was renamed to “timeseries”. Parameter “time_axis_index” was removed; the time axis is assumed to be named “time”

filter(timeseries: TimeSeries) → TimeSeries

Resample a time series.

Returns:

resampled – resampled time series with sampling frequency set to resamplerate

Return type:

TimeSeries