segment_rejection.SegmentRejectionMixin#

class autoclean.mixins.signal_processing.segment_rejection.SegmentRejectionMixin[source]#

Mixin for segment rejection.

annotate_noisy_epochs(raw=None, epoch_duration=2.0, epoch_overlap=0.0, picks=None, quantile_k=3.0, quantile_flag_crit=0.2, annotation_description='BAD_noisy_epoch')[source]#

Identifies noisy epochs in continuous EEG data and annotates them.

This function temporarily epochs the continuous data, calculates channel-wise standard deviations for each epoch, and then identifies epochs where a significant proportion of channels exhibit outlier standard deviations. The outlier detection is based on the interquartile range (IQR) method, similar to what’s used in the pylossless pipeline.

Parameters:

rawmne.io.Raw: The continuous MNE Raw object to process.
epoch_durationfloat, default 2.0: Duration of epochs in seconds for noise detection.
epoch_overlapfloat, default 0.0: Overlap between epochs in seconds.
pickslist of str | str | None, default None: Channels to include. If None, defaults to ‘eeg’. Can be channel names or types (e.g., [‘EEG 001’, ‘EEG 002’] or ‘grad’).
quantile_kfloat, default 3.0: Multiplier for the IQR when defining outlier thresholds for channel standard deviations. A channel’s std in an epoch is an outlier if it’s k IQRs above Q3 or below Q1 relative to its own distribution of stds across all epochs.
quantile_flag_critfloat, default 0.2: Proportion threshold. If more than this proportion of picked channels are marked as outliers (having outlier std) within an epoch, that epoch is flagged as noisy.
annotation_descriptionstr, default “BAD_noisy_epoch”: The description to use for MNE annotations marking noisy epochs.

Returns:

mne.io.Raw: The input Raw object with added annotations for noisy epochs.

Notes

The noise detection criteria are: 1. For each channel, its standard deviation is calculated within each epoch. 2. For each channel, the distribution of its standard deviations across all epochs is considered. Outlier thresholds (lower and upper bounds) are determined using quantile_k times the IQR of this distribution. 3. An epoch is marked as noisy if the proportion of channels whose standard deviation in that epoch falls outside their respective outlier bounds exceeds quantile_flag_crit. This implementation adapts concepts from flag_noisy_epochs and related helper functions in pylossless.pipeline.

annotate_uncorrelated_epochs(raw=None, epoch_duration=2.0, epoch_overlap=0.0, picks=None, n_nearest_neighbors=5, corr_method='max', corr_trim_percent=10.0, outlier_k=4.0, outlier_flag_crit=0.2, annotation_description='BAD_uncorrelated_epoch')[source]#

Identifies epochs with low channel-neighbor correlations and annotates them.

This function temporarily epochs data, calculates correlations between each channel and its spatial neighbors for each epoch, and then flags epochs where a significant proportion of channels show unusually low correlations. Outlier detection for low correlations is based on the IQR method.

Parameters:

rawmne.io.Raw: The continuous MNE Raw object to process. Must have a montage set.
epoch_durationfloat, default 2.0: Duration of epochs in seconds.
epoch_overlapfloat, default 0.0: Overlap between epochs in seconds.
pickslist of str | str | None, default None: Channels to include. If None, defaults to ‘eeg’.
n_nearest_neighborsint, default 5: Number of nearest spatial neighbors to consider for correlation.
corr_methodstr, default “max”: Method to aggregate correlations with neighbors: “max”, “mean”, or “trimmean”. “max” takes the maximum absolute correlation.
corr_trim_percentfloat, default 10.0: If corr_method is “trimmean”, the percentage to trim from each end of the distribution of neighbor correlations before averaging.
outlier_kfloat, default 3.0: Multiplier for the IQR when defining outlier thresholds for low correlations. A channel’s aggregated neighbor correlation in an epoch is an outlier if it’s k IQRs below Q1 of its own distribution of correlations across all epochs.
outlier_flag_critfloat, default 0.2: Proportion threshold. If more than this proportion of picked channels are marked as outliers (having low neighbor correlation) within an epoch, that epoch is flagged.
annotation_descriptionstr, default “BAD_uncorrelated_epoch”: Description for MNE annotations marking these epochs.

Returns:

mne.io.Raw: The input Raw object with added annotations for uncorrelated epochs.

Notes

Requires scipy for distance matrix and xarray for data handling.
The raw object must have a montage set for channel locations.
The first_samp correction for annotations assumes that raw.annotations.orig_time is the true start of the original recording (e.g., raw.info[‘meas_date’]). If your orig_time is different or None, you may need to adjust the onset calculation.