resampling.resample_data#

autoclean.functions.preprocessing.resampling.resample_data(data, sfreq, npad='auto', window='auto', n_jobs=1, pad='auto', verbose=None)[source]#

Resample EEG data to a new sampling frequency.

This function changes the sampling frequency of continuous (Raw) or epoched EEG data using anti-aliasing filtering and interpolation. The function automatically applies appropriate anti-aliasing filters and handles edge effects to preserve data quality during resampling.

The function automatically detects the input data type and preserves it, returning the same type (Raw or Epochs) with identical structure but modified sampling frequency and adjusted time points.

Parameters:

datamne.io.BaseRaw or mne.Epochs: The EEG data to resample. Can be any MNE Raw object (e.g., RawFIF, RawEEGLAB, etc.) or Epochs object.
sfreqfloat: The target sampling frequency in Hz. Must be positive and typically should follow the Nyquist criterion relative to the highest frequency content in the data.
npadstr or int, default ‘auto’: Amount of padding to use. ‘auto’ uses a heuristic to determine optimal padding length. Can also be an integer specifying exact padding samples.
windowstr, default ‘auto’: Windowing function for resampling. ‘auto’ selects appropriate window based on resampling parameters. Other options include ‘boxcar’, ‘triang’, ‘blackman’, ‘hamming’, ‘hann’, ‘bartlett’, ‘flattop’, ‘parzen’, ‘bohman’.
n_jobsint, default 1: Number of parallel jobs to run. Use -1 for all available cores. Parallel processing can speed up resampling for large datasets.
padstr, default ‘auto’: Padding mode. ‘auto’ selects appropriate padding. Other options include ‘reflect_limited’, ‘zero’, ‘constant’, ‘edge’, ‘wrap’.
verbosebool or None, default None: Control verbosity of output. If None, uses MNE default.

Returns:

resampled_datamne.io.BaseRaw or mne.Epochs: The resampled data object, same type as input. Contains identical structure and metadata but with modified sampling frequency and adjusted time axis.

Raises:

TypeError: If data is not an MNE Raw or Epochs object.
ValueError: If target sampling frequency is not positive or is invalid.
RuntimeError: If resampling fails due to insufficient data or other processing errors.

See also

mne.io.Raw.resample: MNE’s raw data resampling method
mne.Epochs.resample: MNE’s epochs resampling method

Notes

Resampling modifies the sampling frequency and time axis but preserves all metadata including channel information, events, and annotations. The resampling is applied in-place on a copy of the data to avoid modifying the original.

When downsampling (reducing sampling frequency), anti-aliasing filtering is automatically applied to prevent aliasing artifacts. When upsampling (increasing sampling frequency), interpolation is used to estimate intermediate sample points.

For continuous data (Raw), edge effects may occur at the beginning and end of the recording due to filtering operations. For epoched data, edge effects occur at epoch boundaries and may affect short epochs more severely.

The function uses MNE’s resampling implementation, which applies appropriate anti-aliasing filters and windowing to minimize artifacts. For very long recordings, consider processing in chunks to manage memory usage.

Resampling can significantly affect subsequent processing steps: - Filtering parameters may need adjustment for new sampling frequency - Epoch length in samples will change proportionally - Event timing remains in seconds but sample indices will change

Examples

Downsample to reduce file size and processing time:

>>> from autoclean import resample_data
>>> downsampled_raw = resample_data(raw, sfreq=250)  # From 1000 Hz to 250 Hz

Upsample for higher temporal resolution:

>>> upsampled_epochs = resample_data(epochs, sfreq=500)  # From 250 Hz to 500 Hz

Resample with custom parameters for better quality:

>>> resampled_data = resample_data(
...     raw,
...     sfreq=250,
...     window='hamming',
...     n_jobs=4
... )

Check if resampling is needed before applying:

>>> current_sfreq = raw.info['sfreq']
>>> if abs(current_sfreq - target_sfreq) > 0.01:
...     resampled_raw = resample_data(raw, sfreq=target_sfreq)
... else:
...     resampled_raw = raw.copy()  # No resampling needed