pynapple.process.filtering#

Functions for highpass, lowpass, bandpass or bandstop filtering.

Functions

apply_bandpass_filter(data, cutoff[, fs, ...])

Apply a band-pass filter to the provided signal.

apply_bandstop_filter(data, cutoff[, fs, ...])

Apply a band-stop filter to the provided signal.

apply_highpass_filter(data, cutoff[, fs, ...])

Apply a high-pass filter to the provided signal.

apply_lowpass_filter(data, cutoff[, fs, ...])

Apply a low-pass filter to the provided signal.

detect_oscillatory_events(data, epoch, ...)

Simple helper for detecting oscillatory events (e.g. ripples, spindles).

get_filter_frequency_response(cutoff, fs, ...)

Utility function to evaluate the frequency response of a particular type of filter.
pynapple.process.filtering.apply_bandpass_filter(data, cutoff, fs=None, mode='butter', order=4, transition_bandwidth=0.02)[source]#

Apply a band-pass filter to the provided signal. Mode can be :

  • “butter” for Butterworth filter. In this case, order determines the order of the filter.

  • “sinc” for Windowed-Sinc convolution. transition_bandwidth determines the transition bandwidth.

Parameters:

  • data (Tsd, TsdFrame, or TsdTensor) – The signal to be filtered.

  • cutoff ((Numeric, Numeric)) – Cutoff frequencies in Hz.

  • fs (float, optional) – The sampling frequency of the signal in Hz. If not provided, it will be inferred from the time axis of the data.

  • mode ({'butter', 'sinc'}, optional) – Filtering mode. Default is ‘butter’.

  • order (int, optional) – The order of the Butterworth filter. Higher values result in sharper frequency cutoffs. Default is 4.

  • transition_bandwidth (float, optional) – The transition bandwidth. 0.2 corresponds to 20% of the frequency band between 0 and the sampling frequency. The smaller the transition bandwidth, the larger the windowed-sinc kernel. Default is 0.02.

Returns:

filtered_data – The filtered signal, with the same data type as the input.

Return type:

Tsd, TsdFrame, or TsdTensor

Raises:

ValueError – If data is not a Tsd, TsdFrame, or TsdTensor. If cutoff is not a tuple of two floats for “bandpass” and “bandstop” filters. If fs is not float or None. If mode is not “butter” or “sinc”. If order is not an int. If “transition_bandwidth” is not a float.

Notes

For the Butterworth filter, the cutoff frequency is defined as the frequency at which the amplitude of the signal is reduced by -3 dB (decibels).

pynapple.process.filtering.apply_bandstop_filter(data, cutoff, fs=None, mode='butter', order=4, transition_bandwidth=0.02)[source]#

Apply a band-stop filter to the provided signal. Mode can be :

  • “butter” for Butterworth filter. In this case, order determines the order of the filter.

  • “sinc” for Windowed-Sinc convolution. transition_bandwidth determines the transition bandwidth.

Parameters:

  • data (Tsd, TsdFrame, or TsdTensor) – The signal to be filtered.

  • cutoff ((Numeric, Numeric)) – Cutoff frequencies in Hz.

  • fs (float, optional) – The sampling frequency of the signal in Hz. If not provided, it will be inferred from the time axis of the data.

  • mode ({'butter', 'sinc'}, optional) – Filtering mode. Default is ‘butter’.

  • order (int, optional) – The order of the Butterworth filter. Higher values result in sharper frequency cutoffs. Default is 4.

  • transition_bandwidth (float, optional) – The transition bandwidth. 0.2 corresponds to 20% of the frequency band between 0 and the sampling frequency. The smaller the transition bandwidth, the larger the windowed-sinc kernel. Default is 0.02.

Returns:

filtered_data – The filtered signal, with the same data type as the input.

Return type:

Tsd, TsdFrame, or TsdTensor

Raises:

ValueError – If data is not a Tsd, TsdFrame, or TsdTensor. If cutoff is not a tuple of two floats for “bandpass” and “bandstop” filters. If fs is not float or None. If mode is not “butter” or “sinc”. If order is not an int. If “transition_bandwidth” is not a float.

Notes

For the Butterworth filter, the cutoff frequency is defined as the frequency at which the amplitude of the signal is reduced by -3 dB (decibels).

pynapple.process.filtering.apply_highpass_filter(data, cutoff, fs=None, mode='butter', order=4, transition_bandwidth=0.02)[source]#

Apply a high-pass filter to the provided signal. Mode can be :

  • “butter” for Butterworth filter. In this case, order determines the order of the filter.

  • “sinc” for Windowed-Sinc convolution. transition_bandwidth determines the transition bandwidth.

Parameters:

  • data (Tsd, TsdFrame, or TsdTensor) – The signal to be filtered.

  • cutoff (Numeric) – Cutoff frequency in Hz.

  • fs (float, optional) – The sampling frequency of the signal in Hz. If not provided, it will be inferred from the time axis of the data.

  • mode ({'butter', 'sinc'}, optional) – Filtering mode. Default is ‘butter’.

  • order (int, optional) – The order of the Butterworth filter. Higher values result in sharper frequency cutoffs. Default is 4.

  • transition_bandwidth (float, optional) – The transition bandwidth. 0.2 corresponds to 20% of the frequency band between 0 and the sampling frequency. The smaller the transition bandwidth, the larger the windowed-sinc kernel. Default is 0.02.

Returns:

filtered_data – The filtered signal, with the same data type as the input.

Return type:

Tsd, TsdFrame, or TsdTensor

Raises:

ValueError – If data is not a Tsd, TsdFrame, or TsdTensor. If cutoff is not a number. If fs is not float or None. If mode is not “butter” or “sinc”. If order is not an int. If “transition_bandwidth” is not a float.

Notes

For the Butterworth filter, the cutoff frequency is defined as the frequency at which the amplitude of the signal is reduced by -3 dB (decibels).

pynapple.process.filtering.apply_lowpass_filter(data, cutoff, fs=None, mode='butter', order=4, transition_bandwidth=0.02)[source]#

Apply a low-pass filter to the provided signal. Mode can be :

  • “butter” for Butterworth filter. In this case, order determines the order of the filter.

  • “sinc” for Windowed-Sinc convolution. transition_bandwidth determines the transition bandwidth.

Parameters:

  • data (Tsd, TsdFrame, or TsdTensor) – The signal to be filtered.

  • cutoff (Numeric) – Cutoff frequency in Hz.

  • fs (float, optional) – The sampling frequency of the signal in Hz. If not provided, it will be inferred from the time axis of the data.

  • mode ({'butter', 'sinc'}, optional) – Filtering mode. Default is ‘butter’.

  • order (int, optional) – The order of the Butterworth filter. Higher values result in sharper frequency cutoffs. Default is 4.

  • transition_bandwidth (float, optional) – The transition bandwidth. 0.2 corresponds to 20% of the frequency band between 0 and the sampling frequency. The smaller the transition bandwidth, the larger the windowed-sinc kernel. Default is 0.02.

Returns:

filtered_data – The filtered signal, with the same data type as the input.

Return type:

Tsd, TsdFrame, or TsdTensor

Raises:

ValueError – If data is not a Tsd, TsdFrame, or TsdTensor. If cutoff is not a number. If fs is not float or None. If mode is not “butter” or “sinc”. If order is not an int. If “transition_bandwidth” is not a float.

Notes

For the Butterworth filter, the cutoff frequency is defined as the frequency at which the amplitude of the signal is reduced by -3 dB (decibels).

pynapple.process.filtering.detect_oscillatory_events(data, epoch, freq_band, thresh_band, duration_band, min_inter_duration, fs=None, wsize=51)[source]#

Simple helper for detecting oscillatory events (e.g. ripples, spindles)

Parameters:

  • data (Tsd) – 1-dimensional time series

  • epoch (IntervalSet) – The epoch for restricting the detection

  • freq_band (tuple) – The (low, high) frequency to bandpass the signal

  • thresh_band (tuple) – The (min, max) value for thresholding the normalized squared signal after filtering

  • duration_band (tuple) – The (min, max) duration of an event in second

  • min_inter_duration (float) – The minimum duration between two events otherwise they are merged (in seconds)

  • fs (float, optional) – The sampling frequency of the signal in Hz. If not provided, it will be inferred from the time axis of the data.

  • wsize (int, optional) – The size of the window for digital filtering

Returns:

The interval set of detected events with metadata containing the power, amplitude, and peak_time

Return type:

IntervalSet

pynapple.process.filtering.get_filter_frequency_response(cutoff, fs, filter_type, mode, order=4, transition_bandwidth=0.02)[source]#

Utility function to evaluate the frequency response of a particular type of filter. The arguments are the same as the function apply_lowpass_filter, apply_highpass_filter, apply_bandpass_filter and apply_bandstop_filter.

This function returns a pandas Series object with the index as frequencies.

Parameters:

  • cutoff (Numeric or tuple of Numeric) – Cutoff frequency in Hz.

  • fs (float) – The sampling frequency of the signal in Hz.

  • filter_type (str) – Can be “lowpass”, “highpass”, “bandpass” or “bandstop”

  • mode (str) – Can be “butter” or “sinc”.

  • order (int, optional) – The order of the Butterworth filter. Higher values result in sharper frequency cutoffs. Default is 4.

  • transition_bandwidth (float, optional) – The transition bandwidth. 0.2 corresponds to 20% of the frequency band between 0 and the sampling frequency. The smaller the transition bandwidth, the larger the windowed-sinc kernel. Default is 0.02.

Return type:

pandas.Series