Note

This page is a reference documentation. It only explains the function signature, and not how to use it. Please refer to the user guide for the big picture.

nilearn.signal.butterworth

nilearn.signal.butterworth(signals, sampling_rate, low_pass=None, high_pass=None, order=5, padtype='odd', padlen=None, copy=False)

Apply a low-pass, high-pass or band-pass Butterworth filter.

Apply a filter to remove signal below the low frequency and above the high frequency.

Parameters:

signalsnumpy.ndarray (1D sequence or n_samples x n_sources)

Signals to be filtered. A signal is assumed to be a column of signals.

sampling_ratefloat

Number of samples per second (sample frequency, in Hertz).

low_passfloat or int or None, default=None

Low cutoff frequency in Hertz. If specified, signals above this frequency will be filtered out. If None, no low-pass filtering will be performed.

high_passfloat or int or None, default=None

High cutoff frequency in Hertz. If specified, signals below this frequency will be filtered out.

orderint, default=5

Order of the Butterworth filter. When filtering signals, the filter has a decay to avoid ringing. Increasing the order sharpens this decay. Be aware that very high orders can lead to numerical instability.

padtype{“odd”, “even”, “constant”, None}, default=”odd”

Type of padding to use for the Butterworth filter. For more information about this, see scipy.signal.filtfilt.

padlenint or None, default=None

The size of the padding to add to the beginning and end of signals. If None, the default value from scipy.signal.filtfilt will be used.

copybool, default=False

If False, signals is modified inplace, and memory consumption is lower than for copy=True, though computation time is higher.

Returns:

filtered_signalsnumpy.ndarray

Signals filtered according to the given parameters.

Examples

>>> import numpy as np
>>> from nilearn.signal import butterworth
>>>
>>> # Generate a single time series
>>> # and apply Butterworth filter to the signal.
>>> signals = np.random.default_rng(42).standard_normal(size=40)
>>> filtered_signals = butterworth(
...     signals,
...     sampling_rate=1,
...     low_pass=0.25,
...     high_pass=0.12,
...     copy=True
... )
>>>
>>> # Plot both signals and filtered_signals
>>> # (if matplotlib is installed).
>>> import matplotlib.pyplot as plt
>>>
>>> fig = plt.plot(signals, color="red")
>>> fig = plt.plot(filtered_signals, color="green")
>>> leg = plt.legend(["Initial signals", "Filtered signals"])
>>> plt.grid(True)
>>> plt.show()