Preprocessing

Preprocessing#

brainmaze_eeg.preprocessing.channel_data_rate_thresholding(x: ndarray[tuple[int, ...], dtype[float64]], data_rate_threshold: 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[int, ...], dtype[float64]], fs: float, detection_window: 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.

  • detection_window (float) – Length of the segment 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[int, ...], dtype[float64]], fs: float, detection_window: 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.

  • detection_window (float) – Length of the segment 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 segment.

Return type:

np.ndarray

Raises:

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

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

Detects Powerline noise in the input signal using. Detection evaluates the power in the spectrum at powerline and its harmonics to the average power of the iEEG in 2 Hz - 40 Hz band. 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.

  • detection_window (float) – Length of the segment in seconds. Default is 0.5 seconds.

  • powerline_freq (float) – Frequency of the powerline noise. Default is 60 Hz.

  • threshold_ratio (float) – Threshold ratio for detection how many times the power of the powerline noise is higher than average power in 2 Hz - 40 Hz band. Default is 1000.

Returns:

Boolean array indicating the presence of powerline noise for every 1 second segment.

Return type:

np.ndarray

brainmaze_eeg.preprocessing.detect_stim_segments(x: ndarray[tuple[int, ...], dtype[float64]], fs: float, detection_window: float = 1, detection_threshold: 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.

  • detection_window (float) – Length of the segment in seconds. Default is 1 second.

  • detection_threshold (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[int, ...], dtype[float64]], fs: float, frequency_powerline: float = 60)#

Filters powerline noise from the input signal using a notch filter. The function replaces NaN values with the median and returns nan values after filtering. This can possibly cause ringing around artifacts and edges.

brainmaze_eeg.preprocessing.mask_segments_with_nans(x: ndarray[tuple[int, ...], dtype[float64]], segment_mask: ndarray[tuple[int, ...], dtype[float64]], fs: float, segment_len_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.

  • segment_len_s (int) – Duration of each segment in seconds.

  • segment_mask (np.ndarray) – Binary matrix of shape (n_channels, n_sec) where 1 indicates the presence of a stimulation artifact in that second.

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[int, ...], 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.

  • data_rate (np.ndarray): Data rate for each channel, calculated as the proportion of non-NaN values.

  • 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.

Contents