mth5.timeseries.scipy_filters

Scipy filter wrappers for xarray.

This module provides xarray-compatible wrappers for scipy.signal filtering functions, enabling efficient filtering operations on labeled N-dimensional arrays with automatic dimension handling.

Notes

Adapted from xr-scipy: https://github.com/fujiisoup/xr-scipy
Filters can be applied along any dimension with automatic sampling rate detection.
Supports both IIR and FIR filter types with forward/backward filtering.

Examples

Apply a bandpass filter to an xarray DataArray:

>>> import xarray as xr
>>> import numpy as np
>>> data = xr.DataArray(np.random.randn(1000), dims=['time'])
>>> data['time'] = np.arange(1000) / 100.0  # 100 Hz
>>> filtered = data.sps_filters.bandpass(10, 40)  # 10-40 Hz

Attributes

sosfiltfilt

Exceptions

`UnevenSamplingWarning`	Base class for warning categories.
`FilteringNaNWarning`	Base class for warning categories.
`DecimationWarning`	Base class for warning categories.

Classes

FilterAccessor

Accessor exposing common frequency and filtering methods.

Functions

`get_maybe_only_dim`(→ str)	Determine the dimension along which to operate.
`get_maybe_last_dim_axis`(→ tuple[str, int])	Get dimension name and axis index.
`get_sampling_step`(→ float)	Compute the sampling step along a dimension.
`frequency_filter`(→ xarray.DataArray \| xarray.Dataset)	Apply a frequency filter to an xarray.
`lowpass`(→ xarray.DataArray \| xarray.Dataset)	Apply a lowpass filter.
`highpass`(→ xarray.DataArray \| xarray.Dataset)	Apply a highpass filter.
`bandpass`(→ xarray.DataArray \| xarray.Dataset)	Apply a bandpass filter.
`bandstop`(→ xarray.DataArray \| xarray.Dataset)	Apply a bandstop (notch) filter.
`decimate`(→ xarray.DataArray \| xarray.Dataset)	Decimate data using Chebyshev filter and downsampling.
`resample_poly`(→ xarray.DataArray \| xarray.Dataset)	Resample using polyphase filtering.
`savgol_filter`(→ xarray.DataArray \| xarray.Dataset)	Apply a Savitzky-Golay filter.
`detrend`(→ xarray.DataArray \| xarray.Dataset)	Remove linear or constant trend from data.

Module Contents

mth5.timeseries.scipy_filters.sosfiltfilt = None[source]

exception mth5.timeseries.scipy_filters.UnevenSamplingWarning[source]

Bases: Warning

Base class for warning categories.

exception mth5.timeseries.scipy_filters.FilteringNaNWarning[source]

Bases: Warning

Base class for warning categories.

exception mth5.timeseries.scipy_filters.DecimationWarning[source]

Bases: Warning

Base class for warning categories.

mth5.timeseries.scipy_filters.get_maybe_only_dim(darray: xarray.DataArray | xarray.Dataset, dim: str | None) → str[source]

Determine the dimension along which to operate.

If dim is None and the array is 1-D, returns the single dimension. Otherwise, returns the provided dim.

Parameters:

darray (xarray.DataArray | xarray.Dataset) – An xarray DataArray or Dataset.
dim (str | None) – Dimension name, or None to auto-detect for 1-D arrays.

Returns:

The dimension name.

Return type:

str

Raises:

ValueError – If dim is None and the array is not 1-D.

mth5.timeseries.scipy_filters.get_maybe_last_dim_axis(darray: xarray.DataArray | xarray.Dataset, dim: str | None = None) → tuple[str, int][source]

Get dimension name and axis index.

Parameters:

darray (xarray.DataArray | xarray.Dataset) – Input array.
dim (str | None, default None) – Dimension name. If None, uses the last dimension.

Returns:

Dimension name and corresponding axis index.

Return type:

tuple[str, int]

mth5.timeseries.scipy_filters.get_sampling_step(darray: xarray.DataArray | xarray.Dataset, dim: str | None = None, rtol: float = 0.001) → float[source]

Compute the sampling step along a dimension.

Automatically detects time unit (ns, us, ms, s) and scales accordingly. Issues a warning if sampling is not uniform (average vs first step mismatch).

Parameters:

darray (xarray.DataArray | xarray.Dataset) – Input array with coordinates.
dim (str | None, default None) – Dimension name. Auto-detected for 1-D arrays.
rtol (float, default 1e-3) – Relative tolerance for detecting uneven sampling.

Returns:

Sampling step in appropriate units (seconds for time coordinates).

Return type:

float

Raises:

ValueError – If the coordinate has fewer than 2 samples.

Warning

UnevenSamplingWarning: If average sampling step differs from first step by more than rtol.

Examples

Get sampling step from a time series:

>>> dt = get_sampling_step(data, dim='time')
>>> sample_rate = 1.0 / dt

mth5.timeseries.scipy_filters.frequency_filter(darray: xarray.DataArray | xarray.Dataset, f_crit: float | list[float] | tuple[float, float], order: int | None = None, irtype: str = 'iir', filtfilt: bool = True, apply_kwargs: dict[str, Any] | None = None, in_nyq: bool = False, dim: str | None = None, **kwargs: Any) → xarray.DataArray | xarray.Dataset[source]

Apply a frequency filter to an xarray.

Supports IIR (infinite impulse response) and FIR (finite impulse response) filters with optional forward-backward filtering for zero-phase response.

Parameters:

darray (xarray.DataArray | xarray.Dataset) – Data to be filtered.
f_crit (float | list[float] | tuple[float, float]) – Critical frequency or frequencies (in Hz). Scalar for lowpass/highpass, 2-element for bandpass/bandstop.
order (int | None, default None) – Filter order. If None, uses default (8 for IIR, 29 for FIR).
irtype ({'iir', 'fir'}, default 'iir') – Impulse response type: ‘iir’ or ‘fir’.
filtfilt (bool, default True) – Apply filter forwards and backwards for zero-phase response.
apply_kwargs (dict | None, default None) – Additional kwargs passed to the filter function.
in_nyq (bool, default False) – If True, f_crit values are already normalized by Nyquist frequency.
dim (str | None, default None) – Dimension along which to filter. Auto-detected for 1-D arrays.
**kwargs – Passed to filter design function (scipy.signal.iirfilter or firwin).

Returns:

Filtered data with same structure as input.

Return type:

xarray.DataArray | xarray.Dataset

Raises:

ValueError – If irtype is not ‘iir’ or ‘fir’, or if dim is ambiguous.

Warning

FilteringNaNWarning: If input contains NaN values.

Examples

Apply a 4th-order IIR lowpass at 10 Hz:

>>> filtered = frequency_filter(data, 10, order=4, btype='low')

FIR bandpass filter from 5 to 15 Hz:

>>> filtered = frequency_filter(data, [5, 15], irtype='fir', btype='band')

mth5.timeseries.scipy_filters.lowpass(darray: xarray.DataArray | xarray.Dataset, f_cutoff: float, *args: Any, **kwargs: Any) → xarray.DataArray | xarray.Dataset[source]

Apply a lowpass filter.

Parameters:

darray (xarray.DataArray | xarray.Dataset) – Data to filter.
f_cutoff (float) – Cutoff frequency in Hz.
*args – Passed to frequency_filter: (order, irtype, filtfilt, apply_kwargs, in_nyq, dim).
**kwargs – Passed to filter design (see frequency_filter).

Returns:

Lowpass-filtered data.

Return type:

xarray.DataArray | xarray.Dataset

Examples

Remove components above 50 Hz:

>>> filtered = lowpass(data, 50)

mth5.timeseries.scipy_filters.highpass(darray: xarray.DataArray | xarray.Dataset, f_cutoff: float, *args: Any, **kwargs: Any) → xarray.DataArray | xarray.Dataset[source]

Apply a highpass filter.

Parameters:

darray (xarray.DataArray | xarray.Dataset) – Data to filter.
f_cutoff (float) – Cutoff frequency in Hz.
*args – Passed to frequency_filter: (order, irtype, filtfilt, apply_kwargs, in_nyq, dim).
**kwargs – Passed to filter design (see frequency_filter).

Returns:

Highpass-filtered data.

Return type:

xarray.DataArray | xarray.Dataset

Examples

Remove components below 1 Hz:

>>> filtered = highpass(data, 1.0)

mth5.timeseries.scipy_filters.bandpass(darray: xarray.DataArray | xarray.Dataset, f_low: float, f_high: float, *args: Any, **kwargs: Any) → xarray.DataArray | xarray.Dataset[source]

Apply a bandpass filter.

Parameters:

darray (xarray.DataArray | xarray.Dataset) – Data to filter.
f_low (float) – Lower cutoff frequency in Hz.
f_high (float) – Upper cutoff frequency in Hz.
*args – Passed to frequency_filter: (order, irtype, filtfilt, apply_kwargs, in_nyq, dim).
**kwargs – Passed to filter design (see frequency_filter).

Returns:

Bandpass-filtered data.

Return type:

xarray.DataArray | xarray.Dataset

Examples

Keep components between 10 and 50 Hz:

>>> filtered = bandpass(data, 10, 50)

mth5.timeseries.scipy_filters.bandstop(darray: xarray.DataArray | xarray.Dataset, f_low: float, f_high: float, *args: Any, **kwargs: Any) → xarray.DataArray | xarray.Dataset[source]

Apply a bandstop (notch) filter.

Parameters:

darray (xarray.DataArray | xarray.Dataset) – Data to filter.
f_low (float) – Lower cutoff frequency in Hz.
f_high (float) – Upper cutoff frequency in Hz.
*args – Passed to frequency_filter: (order, irtype, filtfilt, apply_kwargs, in_nyq, dim).
**kwargs – Passed to filter design (see frequency_filter).

Returns:

Bandstop-filtered data (removes frequencies between f_low and f_high).

Return type:

xarray.DataArray | xarray.Dataset

Examples

Remove 50-60 Hz powerline noise:

>>> filtered = bandstop(data, 50, 60)

mth5.timeseries.scipy_filters.decimate(darray: xarray.Dataset | xarray.DataArray, target_sample_rate: float, n_order: int = 8, dim: str | None = None) → xarray.DataArray | xarray.Dataset[source]

Decimate data using Chebyshev filter and downsampling.

Applies an 8th-order Chebyshev type I filter with zero-phase filtering (sosfiltfilt) before downsampling.

Parameters:

darray (xarray.DataArray | xarray.Dataset) – Data to decimate.
target_sample_rate (float) – Target sample rate in samples per second (or per space unit).
n_order (int, default 8) – Order of the Chebyshev type I filter.
dim (str | None, default None) – Dimension to decimate along. Auto-detected for 1-D arrays.

Returns:

Decimated data with adjusted coordinates.

Return type:

xarray.DataArray | xarray.Dataset

Raises:

ValueError – If dim is None and array is not 1-D.

Warning

UserWarning: If decimation factor > 13, suggest calling decimate multiple times.

Notes

If sample_rate / target_sample_rate > 13, call decimate multiple times to avoid aliasing artifacts.

Examples

Decimate from 100 Hz to 10 Hz:

>>> decimated = decimate(data, target_sample_rate=10.0)

mth5.timeseries.scipy_filters.resample_poly(darray: xarray.DataArray | xarray.Dataset, new_sample_rate: float, dim: str | None = None, pad_type: str = 'mean') → xarray.DataArray | xarray.Dataset[source]

Resample using polyphase filtering.

Computes rational resampling ratio (up/down) and applies scipy.signal.resample_poly. Automatically handles coordinate updates.

Parameters:

darray (xarray.DataArray | xarray.Dataset) – Data to resample.
new_sample_rate (float) – Target sample rate.
dim (str | None, default None) – Dimension to resample along. Auto-detected for 1-D arrays.
pad_type (str, default 'mean') – Padding type passed to scipy.signal.resample_poly. Options: ‘constant’, ‘line’, ‘mean’, ‘median’, etc.

Returns:

Resampled data with updated coordinates.

Return type:

xarray.DataArray | xarray.Dataset

Raises:

ValueError – If dim is None and array is not 1-D.

Warning

UserWarning: If new sample rate is not an integer multiple of original rate.

Notes

In newer scipy versions, data is cast to float and returns float dtype.

Examples

Resample to 50 Hz:

>>> resampled = resample_poly(data, new_sample_rate=50.0)

mth5.timeseries.scipy_filters.savgol_filter(darray: xarray.DataArray | xarray.Dataset, window_length: int, polyorder: int, deriv: int = 0, delta: float | None = None, dim: str | None = None, mode: str = 'interp', cval: float = 0.0) → xarray.DataArray | xarray.Dataset[source]

Apply a Savitzky-Golay filter.

Smooths data using least-squares polynomial fit over a sliding window. Can also compute derivatives.

Parameters:

darray (xarray.DataArray | xarray.Dataset) – Data to filter. Converted to float64 if not already float.
window_length (int) – Length of the filter window (number of coefficients). Must be positive odd integer.
polyorder (int) – Order of polynomial for fitting. Must be < window_length.
deriv (int, default 0) – Order of derivative to compute (0 = no differentiation).
delta (float | None, default None) – Sample spacing for derivative computation. Only used if deriv > 0.
dim (str | None, default None) – Dimension along which to filter. Auto-detected for 1-D arrays.
mode (str, default 'interp') – Extension mode: ‘mirror’, ‘constant’, ‘nearest’, ‘wrap’, or ‘interp’.
cval (float, default 0.0) – Fill value when mode=’constant’.

Returns:

Filtered data.

Return type:

xarray.DataArray | xarray.Dataset

Raises:

ValueError – If window_length is not positive odd, polyorder >= window_length, or dim is None for multi-dimensional arrays.

Examples

Smooth with 11-point window, 2nd-order polynomial:

>>> smoothed = savgol_filter(data, window_length=11, polyorder=2)

Compute first derivative:

>>> deriv1 = savgol_filter(data, 11, 2, deriv=1, delta=0.01)

mth5.timeseries.scipy_filters.detrend(darray: xarray.DataArray | xarray.Dataset, dim: str | None = None, trend_type: str = 'linear') → xarray.DataArray | xarray.Dataset[source]

Remove linear or constant trend from data.

Parameters:

darray (xarray.DataArray | xarray.Dataset) – Data to detrend.
dim (str | None, default None) – Dimension along which to detrend. Auto-detected for 1-D arrays.
trend_type ({'linear', 'constant'}, default 'linear') – Type of detrending: ‘linear’ removes linear trend via least-squares, ‘constant’ removes mean.

Returns:

Detrended data.

Return type:

xarray.DataArray | xarray.Dataset

Raises:

ValueError – If dim is None and array is not 1-D.

Examples

Remove linear trend:

>>> detrended = detrend(data, trend_type='linear')

Remove mean (DC component):

>>> demeaned = detrend(data, trend_type='constant')

class mth5.timeseries.scipy_filters.FilterAccessor(darray: xarray.DataArray | xarray.Dataset)[source]

Accessor exposing common frequency and filtering methods.

Registered as xarray accessor under .sps_filters for both DataArray and Dataset objects.

darray[source]

The wrapped xarray object.

Type:: xarray.DataArray | xarray.Dataset

Examples

Apply filters via accessor:

>>> data.sps_filters.low(10)  # lowpass at 10 Hz
>>> data.sps_filters.bandpass(5, 15)  # bandpass 5-15 Hz

darray: xarray.DataArray | xarray.Dataset[source]

property dt: float[source]: Sampling step of last axis.

property fs: float[source]: Sampling frequency in inverse units of self.dt.

property dx: numpy.ndarray[source]: Sampling steps for all axes as array.

low(f_cutoff: float, *args: Any, **kwargs: Any) → xarray.DataArray | xarray.Dataset[source]

Apply lowpass filter.

Parameters:

f_cutoff (float) – Cutoff frequency in Hz.
*args – Passed to lowpass: (order, irtype, filtfilt, apply_kwargs, in_nyq, dim).
**kwargs – Passed to filter design.

Returns:

Lowpass-filtered data.

Return type:

xarray.DataArray | xarray.Dataset

high(f_cutoff: float, *args: Any, **kwargs: Any) → xarray.DataArray | xarray.Dataset[source]

Apply highpass filter.

Parameters:

f_cutoff (float) – Cutoff frequency in Hz.
*args – Passed to highpass: (order, irtype, filtfilt, apply_kwargs, in_nyq, dim).
**kwargs – Passed to filter design.

Returns:

Highpass-filtered data.

Return type:

xarray.DataArray | xarray.Dataset

bandpass(f_low: float, f_high: float, *args: Any, **kwargs: Any) → xarray.DataArray | xarray.Dataset[source]

Apply bandpass filter.

Parameters:

f_low (float) – Lower cutoff frequency in Hz.
f_high (float) – Upper cutoff frequency in Hz.
*args – Passed to bandpass: (order, irtype, filtfilt, apply_kwargs, in_nyq, dim).
**kwargs – Passed to filter design.

Returns:

Bandpass-filtered data.

Return type:

xarray.DataArray | xarray.Dataset

bandstop(f_low: float, f_high: float, *args: Any, **kwargs: Any) → xarray.DataArray | xarray.Dataset[source]

Apply bandstop filter.

Parameters:

f_low (float) – Lower cutoff frequency in Hz.
f_high (float) – Upper cutoff frequency in Hz.
*args – Passed to bandstop: (order, irtype, filtfilt, apply_kwargs, in_nyq, dim).
**kwargs – Passed to filter design.

Returns:

Bandstop-filtered data.

Return type:

xarray.DataArray | xarray.Dataset

Apply general frequency filter.

Parameters:

f_crit (float | list[float] | tuple[float, float]) – Critical frequency or frequencies in Hz.
order (int | None, default None) – Filter order.
irtype ({'iir', 'fir'}, default 'iir') – Impulse response type.
filtfilt (bool, default True) – Apply forward-backward filtering.
apply_kwargs (dict | None, default None) – Additional filter function kwargs.
in_nyq (bool, default False) – If True, f_crit is normalized by Nyquist frequency.
dim (str | None, default None) – Dimension along which to filter.
**kwargs – Passed to filter design.

Returns:

Filtered data.

Return type:

xarray.DataArray | xarray.Dataset

savgol(window_length: int, polyorder: int, deriv: int = 0, delta: float | None = None, dim: str | None = None, mode: str = 'interp', cval: float = 0.0) → xarray.DataArray | xarray.Dataset[source]

Apply Savitzky-Golay filter.

Parameters:

window_length (int) – Filter window length (positive odd integer).
polyorder (int) – Polynomial order (< window_length).
deriv (int, default 0) – Derivative order.
delta (float | None, default None) – Sample spacing.
dim (str | None, default None) – Dimension to filter along.
mode (str, default 'interp') – Extension mode.
cval (float, default 0.0) – Constant fill value.

Returns:

Filtered data.

Return type:

xarray.DataArray | xarray.Dataset

decimate(target_sample_rate: float, n_order: int = 8, dim: str | None = None) → xarray.DataArray | xarray.Dataset[source]

Decimate signal.

Parameters:

target_sample_rate (float) – Target sample rate.
n_order (int, default 8) – Chebyshev filter order.
dim (str | None, default None) – Dimension to decimate along.

Returns:

Decimated data.

Return type:

xarray.DataArray | xarray.Dataset

detrend(trend_type: str = 'linear', dim: str | None = None) → xarray.DataArray | xarray.Dataset[source]

Remove trend from data.

Parameters:

trend_type ({'linear', 'constant'}, default 'linear') – Type of trend to remove.
dim (str | None, default None) – Dimension to detrend along.

Returns:

Detrended data.

Return type:

xarray.DataArray | xarray.Dataset

resample_poly(target_sample_rate: float, pad_type: str = 'mean', dim: str | None = None) → xarray.DataArray | xarray.Dataset[source]

Resample using polyphase filtering.

Parameters:

target_sample_rate (float) – Target sample rate.
pad_type (str, default 'mean') – Padding type for resampling.
dim (str | None, default None) – Dimension to resample along.

Returns:

Resampled data.

Return type:

xarray.DataArray | xarray.Dataset