eegproc.preprocessing module

eegproc.preprocessing.apply_detrend(detrend, df)[source]
Parameters:

  • detrend (str | None)

  • df (DataFrame)

Return type:

DataFrame

eegproc.preprocessing.bandpass_filter(df, fs, bands={'alpha': (8.0, 13.0), 'betaH': (20.0, 30.0), 'betaL': (13.0, 20.0), 'delta': (0.5, 4.0), 'gamma': (30.0, 45.0), 'theta': (4.0, 8.0)}, low=None, high=None, *, order=4, notch_hz=[60, 120], notch_q=30.0, reref=True, detrend=True)[source]

Applies band-pass filtering over raw EEG data on each channel.

Pipeline

  1. Coerce to numeric (with interpolation).

  2. Optional common average reference (CAR) across channels (reref=True).

  3. Optional notch filtering at notch_hz (and 2x harmonics when safe).

4a) If bands is a dict: apply a per-band Butterworth band-pass (SOS) and

return columns named {channel}_{band}.

4b) Else: require (low, high) and apply a single band-pass to each channel,

returning the original channel names.

  1. Optional constant detrending per output column.

type df:

DataFrame

param df:

Raw data EEG dataframe. Numeric columns; NaNs are interpolated internally by _numeric_interp before filtering.

type df:

pandas.DataFrame

type fs:

float

param fs:

Sampling rate in Hz.

type fs:

float

type bands:

dict[str, tuple[float, float]], default: {'delta': (0.5, 4.0), 'theta': (4.0, 8.0), 'alpha': (8.0, 13.0), 'betaL': (13.0, 20.0), 'betaH': (20.0, 30.0), 'gamma': (30.0, 45.0)}

param bands:

If provided, a mapping from band name to (low, high) in Hz. When given, one output column per {channel}_{band} is produced. If None, low and high must be provided to define a single passband.

type bands:

dict[str, tuple[float, float]] or None, default=FREQUENCY_BANDS

type low:

Optional[float], default: None

param low:

Low cutoff in Hz for the single band-pass path (ignored if bands provided).

type low:

float or None, default=None

type high:

Optional[float], default: None

param high:

High cutoff in Hz for the single band-pass path (ignored if bands provided).

type high:

float or None, default=None

type order:

int, default: 4

param order:

Butterworth filter order for band-pass design.

type order:

int, default=4

type notch_hz:

float | int | list | tuple | None, default: [60, 120]

param notch_hz:

Fundamental notch frequency/frequencies. None disables notch filtering.

type notch_hz:

float | int | list | tuple | None, default=[60, 120]

type notch_q:

float, default: 30.0

param notch_q:

Quality factor for the notch (higher = narrower).

type notch_q:

float, default=30.0

type reref:

bool, default: True

param reref:

If True and there are ≥2 channels, apply common average reference (CAR).

type reref:

bool, default=True

type detrend:

bool, default: True

param detrend:

If True, remove the mean (constant detrend) after filtering.

type detrend:

bool, default=True

rtype:

DataFrame

returns:

pandas.DataFrame – Filtered dataframe indexed like the input. If bands is provided, columns are {channel}_{band}; otherwise, the original channel names are preserved.

raises ValueError:

  • When bands is None and either low or high is missing. - When any cutoff does not satisfy 0 < low < high < fs/2. - When a band in bands violates Nyquist constraints.

Warning

RuntimeWarning

Emitted when reref=True but only one channel is present (CAR requires ≥2).

Notes

  • Band-pass filters are designed with scipy.signal.butter(..., output="sos") and applied with a NaN-robust zero-phase filter via _sosfiltfilt_safe().

  • Notch filtering is applied once before band-pass filtering.

  • Constant detrend uses scipy.signal.detrend(..., type="constant").

  • For stability, very short columns may be skipped inside helper routines.

eegproc.preprocessing.detrend_df(df, kind='linear')[source]
Parameters:

  • df (DataFrame)

  • kind (str, default: 'linear')

Return type:

DataFrame