Preprocessing#

brainmaze_eeg.preprocessing.channel_data_rate_thresholding(x: ndarray[tuple[Any, ...], dtype[float64]], threshold_data_rate: float = 0.1)#

Masks the whole channel [nchans, nsamples] with nans if the channel data rate is below the threshold.

Parameters:

x (np.ndarray) – Input signal, either 1D or 2D array.
dr_threshold (float, optional) – Drop rate threshold for masking. Default is 0.1.

Returns:

Signal with masked values replaced by NaNs.

Return type:

np.ndarray

Raises:

ValueError – If the input signal is not 1D or 2D.

brainmaze_eeg.preprocessing.detect_flat_line_segments(x: ndarray[tuple[Any, ...], dtype[float64]], fs: float, window_s: float = 0.5, threshold: float = 5e-07)#

Detects flat-line segments in the input signal. A flat-line segment is identified when the mean absolute difference of the signal within a detection window is below a specified threshold. It drops the last segment if ndarray shape is not a multiple of whole seconds.

Parameters:

x (np.ndarray) – Input signal, either 1D or 2D array.
fs (float) – Sampling frequency.
window_s (float) – Length of the detection window in seconds. Default is 0.5 seconds.
threshold (float) – Threshold for detecting flat-line segments. Default is 0.5e-6.

Returns:

Boolean array indicating the presence of flat-line segments for each detection window.

Return type:

np.ndarray

Raises:

ValueError – If the input signal is not 1D or 2D.

brainmaze_eeg.preprocessing.detect_outlier_segments(x: ndarray[tuple[Any, ...], dtype[float64]], fs: float, window_s: float = 0.5, threshold: float = 10)#

Detects outlier noise in the input signal based on a threshold. The function evaluates the signal’s deviation from the mean and identifies segments with excessive noise. It drops the last segment if ndarray shape is not a multiple of whole seconds.

Parameters:

x (np.ndarray) – Input signal, either 1D or 2D array.
fs (float) – Sampling frequency.
window_s (float) – Length of the detection window in seconds. Default is 0.5 seconds.
threshold (float) – Threshold for detecting outliers. Default is 10.

Returns:

Boolean array indicating the presence of outlier noise for each detection window.

Return type:

np.ndarray

Raises:

ValueError – If the input signal is not 1D or 2D.

brainmaze_eeg.preprocessing.detect_powerline_segments(x: ndarray[tuple[Any, ...], dtype[float64]], fs: float, window_s: float = 0.5, powerline_freq: float = 60, threshold_ratio: float = 1000)#

Detect segments contaminated by powerline noise in EEG recordings.

Big Picture: Powerline noise contamination can vary over time due to changes in electrode impedance, patient movement, or proximity to electrical equipment. Rather than filtering all data uniformly, this function identifies time segments with severe powerline contamination, allowing for selective processing or exclusion of problematic data. This approach preserves clean data segments while flagging contaminated ones for special handling.

Technical Details: The detection algorithm:

Divides the signal into short windows (default 0.5s)
Computes power spectral density for each window
Calculates reference power in physiological band (2-40 Hz)
Measures power at powerline frequency and its harmonics (60, 120, 180 Hz, etc.)
Flags segments where powerline power exceeds physiological power by threshold_ratio

\[contaminated = \frac{P_{powerline}}{P_{2-40Hz}} > threshold\]

The default threshold of 1000 indicates that powerline power is 1000× greater than the average physiological power, suggesting severe contamination.

Harmonics Detection: The function checks not just the fundamental powerline frequency but also its harmonics, as powerline interference often creates spectral peaks at multiples of the base frequency (60 Hz, 120 Hz, 180 Hz, etc.).

Use Case: - Preprocessing pipeline for automatic data quality assessment - Adaptive filtering strategies (filter only contaminated segments) - Data quality reporting and visualization - Exclusion criteria for feature extraction in clean segments only

Practical Applications: - Sleep studies: Exclude epochs with excessive powerline noise from analysis - Real-time monitoring: Alert when powerline noise exceeds acceptable levels - Research studies: Ensure consistent data quality across recordings

Parameters:

x (np.ndarray) – Input signal, either 1D or 2D array.
fs (float) – Sampling frequency in Hz.
window_s (float) – Length of the detection window in seconds. Default is 0.5 seconds.
powerline_freq (float) – Frequency of the powerline noise (50 or 60 Hz). Default is 60 Hz.
threshold_ratio (float) – Threshold ratio indicating how many times the power of the powerline noise is higher than average power in 2-40 Hz band. Default is 1000.

Returns:

Boolean array indicating the presence of powerline noise for every detection window.: Shape is (n_channels, n_windows) or (n_windows,) for 1D input.

Return type:

np.ndarray

brainmaze_eeg.preprocessing.detect_stim_segments(x: ndarray[tuple[Any, ...], dtype[float64]], fs: float, window_s: float = 1, threshold_detection: float = 2000, freq_band: Tuple[float, float] = (80, 110))#

Detects stimulation artifacts in the input signal. Calculates differential signal of the input signal. Spectral power of the differential signal between the bands provided in frequency band is thresholded for each detection window.

Parameters:

x (np.ndarray) – Input signal, either 1D or 2D array.
fs (float) – Sampling frequency.
window_s (float) – Length of the detection window in seconds. Default is 1 second.
threshold_detection (float) – Threshold for detecting stimulation artifacts. Default is 2000.
freq_band (tuple) – Frequency band to consider for artifact detection (low, high). Default is (80, 110).

Returns:

np.ndarray: Boolean array indicating the presence of stimulation artifacts for each detection window.
np.ndarray: Spectral power within the specified frequency band for each detection window.

Return type:

tuple

Raises:

ValueError – If the input signal is not 1D or 2D.

brainmaze_eeg.preprocessing.detection_dilatation(mask: ndarray, extend_left: int = 2, extend_right: int = 2)#

Extends True values in a boolean mask by a fixed number of positions to the left and right.

Parameters:

mask (np.ndarray) – 1D or 2D boolean array indicating detection.
extend_left (int) – Number of positions to extend left of each detection.
extend_right (int) – Number of positions to extend right of each detection.

Returns:

Extended boolean mask with same shape.

Return type:

np.ndarray

Raises:

ValueError – If the input signal is not 1D or 2D.

brainmaze_eeg.preprocessing.filter_powerline(x: ndarray[tuple[Any, ...], dtype[float64]], fs: float, frequency_powerline: float = 60)#

Remove powerline noise from EEG signals using a notch filter.

Big Picture: Powerline interference (50 Hz in Europe, 60 Hz in North America) is one of the most common artifacts in electrophysiological recordings. This narrow-band noise arises from electromagnetic coupling with the electrical grid and can obscure physiological signals. This function applies a notch filter to remove this interference while preserving the EEG signal content at other frequencies.

Technical Details: The function uses an infinite impulse response (IIR) notch filter with: - Quality factor Q=10, providing a narrow rejection bandwidth - Zero-phase filtering (filtfilt) to avoid phase distortion - Automatic handling of NaN values by temporarily replacing them with median values

The notch filter attenuates frequencies in a narrow band centered at the powerline frequency while minimally affecting adjacent frequencies. After filtering, NaN values are restored to their original locations to preserve data quality indicators.

Important Considerations: - This approach may cause ringing artifacts around data gaps (NaN regions) - Alternative: Use robust filtering methods that handle missing data explicitly - The filter is applied independently to each channel in multi-channel recordings

Use Case: Apply during preprocessing of raw EEG/iEEG recordings before feature extraction or sleep stage classification. Essential for clean spectral analysis and preventing powerline noise from being misinterpreted as physiological rhythms.

Parameters:

x (np.ndarray) – Input signal, either 1D or 2D array.
fs (float) – Sampling frequency in Hz.
frequency_powerline (float) – Powerline noise frequency (typically 50 or 60 Hz).

Returns:

Signal filtered with notch filter, same shape as input.

Return type:

np.ndarray

Raises:

ValueError – If the input signal is not 1D or 2D.

brainmaze_eeg.preprocessing.mask_segments_with_nans(x: ndarray[tuple[Any, ...], dtype[float64]], segment_mask: ndarray[tuple[Any, ...], dtype[float64]], fs: float, window_s: float)#

Masks EEG signal segments based on provided mask setting them to NaN.

Parameters:

x (np.ndarray) – 1D or 2D array of EEG data with shape (n_channels, n_samples).
fs (int) – Sampling rate of the EEG signal in Hz.
window_s (int) – Duration of each masking segment in seconds.
segment_mask (np.ndarray) – Binary matrix of shape (n_channels, n_sec * window_s) where 1 indicates the presence of a stimulation artifact in given window.

Returns:

EEG signal with artifact segments replaced by NaN.

Return type:

np.ndarray

Raises:

ValueError – If the input signal is not 1D or 2D.

brainmaze_eeg.preprocessing.replace_nans_with_median(x: ndarray[tuple[Any, ...], dtype[float64]])#

Replaces NaN values in the input signal with the median of the non-NaN values along each channel.

Parameters:

x (np.ndarray) – Input signal, either 1D or 2D array.

Returns:

A tuple containing:

processed_signal (np.ndarray): Signal with NaN values replaced by the median.
mask (np.ndarray): Boolean mask indicating the positions of NaN values in the original signal.

Return type:

Tuple[np.ndarray, np.ndarray, np.ndarray]

Raises:

ValueError – If the input signal is not 1D or 2D.

Preprocessing

Contents

Preprocessing#