Filtering

pynapple.process.filtering

Filtering module.

apply_bandpass_filter

apply_bandpass_filter(
    data,
    cutoff,
    fs=None,
    mode="butter",
    order=4,
    transition_bandwidth=0.02,
)

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:

Name	Type	Description	Default
data	Tsd, TsdFrame, or TsdTensor	The signal to be filtered.	required
cutoff	(Numeric, Numeric)	Cutoff frequencies in Hz.	required
fs	float	The sampling frequency of the signal in Hz. If not provided, it will be inferred from the time axis of the data.	None
mode	(butter, sinc)	Filtering mode. Default is 'butter'.	'butter'
order	int	The order of the Butterworth filter. Higher values result in sharper frequency cutoffs. Default is 4.	4
transition_bandwidth	float	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.	0.02

Returns:

Name	Type	Description
filtered_data	Tsd, TsdFrame, or TsdTensor	The filtered signal, with the same data type as the input.

Raises:

Type	Description
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).

Source code in pynapple/process/filtering.py

def apply_bandpass_filter(
    data, cutoff, fs=None, mode="butter", order=4, transition_bandwidth=0.02
):
    """
    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 : Tsd, TsdFrame, or TsdTensor
        The filtered signal, with the same data type as the input.

    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).
    """
    return _compute_filter(
        data,
        cutoff,
        fs=fs,
        mode=mode,
        order=order,
        transition_bandwidth=transition_bandwidth,
        filter_type="bandpass",
    )

apply_bandstop_filter

apply_bandstop_filter(
    data,
    cutoff,
    fs=None,
    mode="butter",
    order=4,
    transition_bandwidth=0.02,
)

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:

Name	Type	Description	Default
data	Tsd, TsdFrame, or TsdTensor	The signal to be filtered.	required
cutoff	(Numeric, Numeric)	Cutoff frequencies in Hz.	required
fs	float	The sampling frequency of the signal in Hz. If not provided, it will be inferred from the time axis of the data.	None
mode	(butter, sinc)	Filtering mode. Default is 'butter'.	'butter'
order	int	The order of the Butterworth filter. Higher values result in sharper frequency cutoffs. Default is 4.	4
transition_bandwidth	float	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.	0.02

Returns:

Name	Type	Description
filtered_data	Tsd, TsdFrame, or TsdTensor	The filtered signal, with the same data type as the input.

Raises:

Type	Description
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).

Source code in pynapple/process/filtering.py

def apply_bandstop_filter(
    data, cutoff, fs=None, mode="butter", order=4, transition_bandwidth=0.02
):
    """
    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 : Tsd, TsdFrame, or TsdTensor
        The filtered signal, with the same data type as the input.

    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).
    """
    return _compute_filter(
        data,
        cutoff,
        fs=fs,
        mode=mode,
        order=order,
        transition_bandwidth=transition_bandwidth,
        filter_type="bandstop",
    )

apply_highpass_filter

apply_highpass_filter(
    data,
    cutoff,
    fs=None,
    mode="butter",
    order=4,
    transition_bandwidth=0.02,
)

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:

Name	Type	Description	Default
data	Tsd, TsdFrame, or TsdTensor	The signal to be filtered.	required
cutoff	Numeric	Cutoff frequency in Hz.	required
fs	float	The sampling frequency of the signal in Hz. If not provided, it will be inferred from the time axis of the data.	None
mode	(butter, sinc)	Filtering mode. Default is 'butter'.	'butter'
order	int	The order of the Butterworth filter. Higher values result in sharper frequency cutoffs. Default is 4.	4
transition_bandwidth	float	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.	0.02

Returns:

Name	Type	Description
filtered_data	Tsd, TsdFrame, or TsdTensor	The filtered signal, with the same data type as the input.

Raises:

Type	Description
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).

Source code in pynapple/process/filtering.py

def apply_highpass_filter(
    data, cutoff, fs=None, mode="butter", order=4, transition_bandwidth=0.02
):
    """
    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 : Tsd, TsdFrame, or TsdTensor
        The filtered signal, with the same data type as the input.

    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).
    """
    return _compute_filter(
        data,
        cutoff,
        fs=fs,
        mode=mode,
        order=order,
        transition_bandwidth=transition_bandwidth,
        filter_type="highpass",
    )

apply_lowpass_filter

apply_lowpass_filter(
    data,
    cutoff,
    fs=None,
    mode="butter",
    order=4,
    transition_bandwidth=0.02,
)

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:

Name	Type	Description	Default
data	Tsd, TsdFrame, or TsdTensor	The signal to be filtered.	required
cutoff	Numeric	Cutoff frequency in Hz.	required
fs	float	The sampling frequency of the signal in Hz. If not provided, it will be inferred from the time axis of the data.	None
mode	(butter, sinc)	Filtering mode. Default is 'butter'.	'butter'
order	int	The order of the Butterworth filter. Higher values result in sharper frequency cutoffs. Default is 4.	4
transition_bandwidth	float	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.	0.02

Returns:

Name	Type	Description
filtered_data	Tsd, TsdFrame, or TsdTensor	The filtered signal, with the same data type as the input.

Raises:

Type	Description
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).

Source code in pynapple/process/filtering.py

def apply_lowpass_filter(
    data, cutoff, fs=None, mode="butter", order=4, transition_bandwidth=0.02
):
    """
    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 : Tsd, TsdFrame, or TsdTensor
        The filtered signal, with the same data type as the input.

    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).
    """
    return _compute_filter(
        data,
        cutoff,
        fs=fs,
        mode=mode,
        order=order,
        transition_bandwidth=transition_bandwidth,
        filter_type="lowpass",
    )

get_filter_frequency_response

get_filter_frequency_response(
    cutoff,
    fs,
    filter_type,
    mode,
    order=4,
    transition_bandwidth=0.02,
)

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:

Name	Type	Description	Default
cutoff	Numeric or tuple of Numeric	Cutoff frequency in Hz.	required
fs	float	The sampling frequency of the signal in Hz.	required
filter_type		Can be "lowpass", "highpass", "bandpass" or "bandstop"	required
mode		Can be "butter" or "sinc".	required
order	int	The order of the Butterworth filter. Higher values result in sharper frequency cutoffs. Default is 4.	4
transition_bandwidth	float	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.	0.02

Returns:

Type	Description
Series

Source code in pynapple/process/filtering.py

@_validate_filtering_inputs
def get_filter_frequency_response(
    cutoff, fs, filter_type, mode, order=4, transition_bandwidth=0.02
):
    """
    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.

    Returns
    -------
    pandas.Series
    """
    cutoff = np.array(cutoff)

    if mode == "butter":
        sos = _get_butter_coefficients(cutoff, filter_type, fs, order)
        w, h = sosfreqz(sos, worN=1024, fs=fs)
        return pd.Series(index=w, data=np.abs(h))
    if mode == "sinc":
        kernel = _get_windowed_sinc_kernel(
            cutoff, filter_type, fs, transition_bandwidth
        )
        fft_result = np.fft.fft(kernel)
        fft_result = np.fft.fftshift(fft_result)
        fft_freq = np.fft.fftfreq(n=len(kernel), d=1 / fs)
        fft_freq = np.fft.fftshift(fft_freq)
        return pd.Series(
            index=fft_freq[fft_freq >= 0], data=np.abs(fft_result[fft_freq >= 0])
        )
    else:
        raise ValueError("Unrecognized filter mode. Choose either 'butter' or 'sinc'")