elephant.signal_processing.butter

elephant.signal_processing.butter(signal, highpass_frequency=None, lowpass_frequency=None, order=4, filter_function='filtfilt', sampling_frequency=1.0, axis=-1)[source]

Butterworth filtering function for neo.AnalogSignal.

Filter type is determined according to how values of highpass_frequency and lowpass_frequency are given (see “Parameters” section for details).

Parameters:
signalneo.AnalogSignal or pq.Quantity or np.ndarray

Time series data to be filtered. If pq.Quantity or np.ndarray, the sampling frequency should be given through the keyword argument fs.

highpass_frequencypq.Quantity of float, optional

High-pass cut-off frequency. If float, the given value is taken as frequency in Hz. Default: None

lowpass_frequencypq.Quantity or float, optional

Low-pass cut-off frequency. If float, the given value is taken as frequency in Hz. Filter type is determined depending on the values of lowpass_frequency and highpass_frequency:

  • highpass_frequency only (lowpass_frequency is None):

    highpass filter

  • lowpass_frequency only (highpass_frequency is None):

    lowpass filter

  • highpass_frequency < lowpass_frequency: bandpass filter

  • highpass_frequency > lowpass_frequency: bandstop filter

Default: None

orderint, optional

Order of the Butterworth filter. Default: 4

filter_function{‘filtfilt’, ‘lfilter’, ‘sosfiltfilt’}, optional

Filtering function to be used. Available filters:

  • ‘filtfilt’: scipy.signal.filtfilt;

  • ‘lfilter’: scipy.signal.lfilter;

  • ‘sosfiltfilt’: scipy.signal.sosfiltfilt.

In most applications ‘filtfilt’ should be used, because it doesn’t bring about phase shift due to filtering. For numerically stable filtering, in particular higher order filters, use ‘sosfiltfilt’ (see https://github.com/NeuralEnsemble/elephant/issues/220). Default: ‘filtfilt’

sampling_frequencypq.Quantity or float, optional

The sampling frequency of the input time series. When given as float, its value is taken as frequency in Hz. When signal is given as neo.AnalogSignal, its attribute is used to specify the sampling frequency and this parameter is ignored. Default: 1.0

axisint, optional

Axis along which filter is applied. Default: last axis (-1)

Returns:
filtered_signalneo.AnalogSignal or pq.Quantity or np.ndarray

Filtered input data. The shape and type is identical to those of the input signal.

Raises:
ValueError

If filter_function is not one of ‘lfilter’, ‘filtfilt’, or ‘sosfiltfilt’.

If both highpass_frequency and lowpass_frequency are None.

Examples

>>> import neo
>>> import numpy as np
>>> import quantities as pq
>>> from elephant.signal_processing import butter
>>> np.random.seed(0)
>>> noise = neo.AnalogSignal(np.random.normal(size=5000),
...     sampling_rate=1000 * pq.Hz, units='mV')
>>> filtered_noise = butter(noise, highpass_frequency=250.0 * pq.Hz)
>>> filtered_noise
<AnalogSignal(array([[-2.70236218e-05],
       [-3.44299631e-01],
       [-1.36890122e-01],
       ...,
       [ 1.12088277e-01],
       [-3.11053132e-01],
       [ 2.63563988e-03]]) * mV, [0.0 s, 5.0 s], sampling rate: 1000.0 Hz)>

Let’s check that the normal noise power spectrum at zero frequency is close to zero.

>>> from elephant.spectral import welch_psd
>>> freq, psd = welch_psd(filtered_noise, fs=1000.0)
>>> psd.shape
(1, 556)
>>> freq[0], psd[0, 0] 
(array(0.) * Hz, array(7.21464674e-08) * mV**2/Hz)