quality.detect_outlier_epochs#

autoclean.functions.epoching.quality.detect_outlier_epochs(epochs, threshold=3.0, measures=None, return_scores=False, verbose=None)[source]#

Detect and mark outlier epochs based on statistical measures.

This function identifies epochs that are statistical outliers based on multiple measures, following principles from the FASTER algorithm. It calculates z-scores for various epoch properties and marks epochs as bad if they exceed the specified threshold in any measure.

The default statistical measures include: - Mean amplitude across channels and time - Variance across channels and time - Maximum amplitude range (max - min) - Mean gradient (rate of change)

This is particularly useful for removing epochs with extreme amplitude characteristics that could negatively impact subsequent processing steps like ICA or averaging.

Parameters:

epochsmne.Epochs: The epochs object to analyze for outliers.
thresholdfloat, default 3.0: The z-score threshold for outlier detection. Epochs with z-scores exceeding this threshold in any measure will be marked as bad.
measureslist of str or None, default None: List of measures to compute. If None, uses all available measures: [‘mean’, ‘variance’, ‘range’, ‘gradient’]. Available options: - ‘mean’: Mean amplitude across channels and time - ‘variance’: Variance across channels and time - ‘range’: Maximum amplitude range (max - min) - ‘gradient’: Mean gradient (rate of change)
return_scoresbool, default False: If True, returns a tuple of (epochs, scores_dict) where scores_dict contains the computed z-scores for each measure.
verbosebool or None, default None: Control verbosity of output.

Returns:

epochs_cleanmne.Epochs: Copy of input epochs with outlier epochs marked as bad.
scoresdict, optional: Dictionary of z-scores for each measure (only if return_scores=True). Keys are measure names, values are arrays of z-scores for each epoch.

Raises:

TypeError: If epochs is not an MNE Epochs object.
ValueError: If threshold is not positive or measures contains invalid options.
RuntimeError: If outlier detection fails due to processing errors.

See also

mne.Epochs.drop_bad: Drop bad epochs
autoclean.gfp_clean_epochs: Clean epochs using Global Field Power

Notes

Statistical Approach: The function computes multiple statistical measures for each epoch and converts them to z-scores. Epochs with z-scores exceeding the threshold are considered outliers and marked as bad.

FASTER Algorithm: This implementation is inspired by the FASTER (Fully Automated Statistical Thresholding for EEG artifact Rejection) algorithm, which uses statistical thresholding to identify artifacts in EEG data.

Measure Descriptions: - Mean: Average amplitude across all channels and time points - Variance: Measure of amplitude variability - Range: Difference between maximum and minimum amplitudes - Gradient: Average rate of change (temporal derivative)

Threshold Selection: - threshold=3.0: Conservative (marks ~0.3% of epochs as outliers) - threshold=2.5: Moderate (marks ~1.2% of epochs as outliers) - threshold=2.0: Liberal (marks ~4.6% of epochs as outliers)

References

Nolan, H., Whelan, R., & Reilly, R. B. (2010). FASTER: fully automated statistical thresholding for EEG artifact rejection. Journal of neuroscience methods, 192(1), 152-162.

Examples

Detect outliers with default parameters:

>>> from autoclean import detect_outlier_epochs
>>> clean_epochs = detect_outlier_epochs(epochs, threshold=3.0)

Detect outliers with custom measures and return scores:

>>> clean_epochs, scores = detect_outlier_epochs(
...     epochs,
...     threshold=2.5,
...     measures=['mean', 'variance'],
...     return_scores=True
... )

More conservative outlier detection:

>>> clean_epochs = detect_outlier_epochs(epochs, threshold=2.0)