spudtr.filters module

FIR filter wrappers and utility functions.

All filter functions require explicit parameters except check_filter_params() and show_filter() which will, respectively, return and display suggested defaults for window, width_hz (transition band) and ripple_db if these are not specified.

spudtr.filters.check_filter_params(ftype=None, cutoff_hz=None, sfreq=None, width_hz=None, ripple_db=None, window=None, allow_defaults=False)[source]

type check FIR filter parameters and optionally provide defaults

Values for ftype, cutoff_hz, and sfreq are obligatory.

If allow_defaults is True, reasonable defaults are provided if any of window, width_hz and ripple_db are None.

Parameters

  • ftype (str {'lowpass' , 'highpass', 'bandpass', 'bandstop'}) – filter type

  • cutoff_hz (float or 1D-array-like of floats, length 2) – 1/2 amplitude cutoff frequency in Hz

  • sfreq (float) – sampling frequency, e.g., 250.0, 500.0

  • width_hz (float) – pass-to-stop transition band width (Hz), symmetric for bandpass, bandstop

  • ripple_db (float) – ripple, in dB, e.g., 53.0, 60.0

  • window (str {'kaiser','hamming','hann','blackman'}) – window type for firwin

  • allow_defaults (bool {False, True}) – If True this makes width_hz, ripple_db, window optional and fills in sensible defaults for any left unspecified by the user.

Returns

params with key:val for all filter parameters specified, suitable for passing as **params to spudtr.filters FIR functions.

Return type

dict

spudtr.filters.filters_effect(ftype=None, cutoff_hz=None, sfreq=None, width_hz=None, ripple_db=None, window=None)[source]

Generate example filter input-output plots for pure sinewave data.

Parameters

key=val – see check_filter params() Parameters

Returns

fig, ax of the example plot

Return type

matplotlib.figure.Figure, matplotlib.axes.Axes

spudtr.filters.fir_filter_data(data, ftype=None, cutoff_hz=None, sfreq=None, width_hz=None, ripple_db=None, window=None)[source]

Finite Impulse Response filter

Parameters
Returns

filtered_data filter output, same length as data

Return type

1D array

Notes

The input data is zero-padded by the length of the FIR filter delay and trimmed back to the original length.

spudtr.filters.fir_filter_dt(dt, col_names, ftype=None, cutoff_hz=None, sfreq=None, width_hz=None, ripple_db=None, window=None)[source]

apply FIRLS filtering to columns of dataframe-like synchronized discrete time series

Parameters

  • dt (pd.DataFrame or structured numpy nd.array with named data types) – regularly sampled time-series data table: time (row) x data (columns)

  • col_names (list of str) – column names to apply the transform

  • key=val – see check_filter params() Parameters

Returns

table-like copy with filtered data columns, the same size and object type as dt

Return type

pd.DataFrame or np.ndarray

Notes

The input data is zero-padded by the length of the FIR filter delay and trimmed back to the original length.

Examples

>>> ftype = "bandpass"
>>> cutoff_hz = [18, 35]
>>> width_hz = 5
>>> ripple_db = 60
>>> window = "kaiser"
>>> sfreq = 250

>>> fir_filter_dt = epochs_filters(
    dt,
    col_names,
    ftype=ftype,
    window=window,
    cutoff_hz=cutoff_hz,
    width_hz=width_hz,
    ripple_db=ripple_db,
    sfreq=sfreq,
    trim_edges=False
)

>>> params = dict(ftype="lowpass", cutoff_hz=10, width_hz=5, ripple_db=60, sfreq=250, window="hamming")
>>> fir_filter_dt = epochs_filters(dt, col_names, **params)
spudtr.filters.show_filter(ftype=None, cutoff_hz=None, sfreq=None, width_hz=None, ripple_db=None, window=None, show_output=True)[source]

Text summary and graphic display of filter attributes for the specified parameters.

Figures are plotted for the transfer function, coefficients, and input-output performance on pure sine wave data with intervals of edge distortion highlighted.

Parameters

  • ftype (str {'lowpass' , 'highpass', 'bandpass', 'bandstop'}) – filter type

  • cutoff_hz (float or 1D array-like, length=2) – 1/2 amplitude cutoff frequency (Hz)

  • sfreq (float) – sampling frequency in samples per second

  • width_hz (float, optional) – pass-to-stop transition band width (Hz)

  • ripple_db (float, optional) – band ripple (dB)

  • window ({'kaiser','hamming','hann','blackman'}, optional) – window type for firwin

  • show_output (bool) – plot example filter input-output, default=True

Returns

  • freq_phase (matplotlib.Figure) – plots frequency and phase response

  • imp_resp (matplotlib.Figure) – plots impulse and step response

  • s_edge (float) – number of seconds distorted at edge boundaries

  • n_edge (int) – number of samples distorted at edge boundaries

Notes

For more information on the filter parameters see check_filter params() Parameters

Examples

>>> ftype = 'lowpass'
>>> cutoff_hz = 10.0
>>> sfreq = 250
>>> width_hz = 5.0
>>> ripple_db = 53.0
>>> window = 'kaiser'

>>> # fill in defaults for width_hz, ripple_db, window
>>> show_filter(
      ftype=ftype,
      cutoff_hz=cutoff_hz,
      sfreq=sfreq
    )

>>> # with all explicit parameters
>>> show_filter(
      ftype=ftype,
      cutoff_hz=cutoff_hz,
      sfreq=sfreq,
      width_hz=width_hz,
      ripple_db=ripple_db,
      window=window,
    )