segment_rejection.annotate_uncorrelated_segments#

autoclean.functions.segment_rejection.segment_rejection.annotate_uncorrelated_segments(raw, 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_segment', verbose=None)[source]#

Identify and annotate segments with poor channel-neighbor correlations.

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.

The method works by: 1. Creating temporary fixed-length epochs from continuous data 2. Finding spatial neighbors for each channel based on montage positions 3. Calculating correlations between each channel and its neighbors in each epoch 4. Using IQR-based outlier detection to identify abnormally low correlations 5. Flagging epochs where too many channels show poor neighbor correlations 6. Adding annotations to mark these problematic time periods

Parameters:

rawmne.io.Raw: The continuous EEG data to analyze. Must have a montage set for channel positions.
epoch_durationfloat, default 2.0: Duration of epochs in seconds for correlation analysis.
epoch_overlapfloat, default 0.0: Overlap between epochs in seconds.
pickslist of str, str, or 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. Higher values use more neighbors but may dilute local effects.
corr_methodstr, default “max”: Method to aggregate correlations with neighbors: - “max”: Maximum absolute correlation with any neighbor - “mean”: Mean absolute correlation across all neighbors - “trimmean”: Trimmed mean (removes extreme values)
corr_trim_percentfloat, default 10.0: If corr_method is “trimmean”, percentage to trim from each end before averaging (e.g., 10.0 = trim 10% from each end).
outlier_kfloat, default 4.0: Multiplier for the IQR when defining outlier thresholds for low correlations. A channel’s correlation in an epoch is an outlier if it’s k IQRs below Q1 of its own distribution across all epochs.
outlier_flag_critfloat, default 0.2: Proportion threshold (0.0-1.0). If more than this proportion of picked channels are marked as outliers (having low correlations) within an epoch, that epoch is flagged as uncorrelated.
annotation_descriptionstr, default “BAD_uncorrelated_segment”: Description for MNE annotations marking these segments.
verbosebool or None, default None: Control verbosity of output during processing.

Returns:

raw_annotatedmne.io.Raw: Copy of input Raw object with added annotations for uncorrelated segments.

Raises:

TypeError: If raw is not an MNE Raw object.
ValueError: If parameters are invalid or no montage is set.
RuntimeError: If processing fails due to insufficient data or other errors.

See also

annotate_noisy_segments: Detect segments with high noise levels
mne.channels.find_ch_adjacency: Find channel adjacency for correlation analysis
scipy.spatial.distance_matrix: Spatial distance calculations

Notes

Requirements: - Raw object must have a montage set for channel positions - Sufficient good channels around each channel for meaningful correlations - At least n_nearest_neighbors + 1 channels total

Detection Algorithm: 1. For each epoch and channel, calculate correlations with spatial neighbors 2. Aggregate neighbor correlations using specified method (max/mean/trimmean) 3. For each channel, analyze distribution of correlations across epochs 4. Use IQR-based outlier detection to identify abnormally low correlations 5. Flag epochs where proportion of low-correlation channels exceeds threshold

Parameter Guidelines: - n_nearest_neighbors: 3-8 typical. Higher for dense arrays, lower for sparse - corr_method: “max” most sensitive, “mean” most stable, “trimmean” robust - outlier_k: 3-5 typical. Higher values = fewer false positives - outlier_flag_crit: 0.1-0.3 typical. Lower = more sensitive

References

This implementation adapts concepts from the PREP pipeline:

Bigdely-Shamlo, N., Mullen, T., Kothe, C., Su, K. M., & Robbins, K. A. (2015). The PREP pipeline: standardized preprocessing for large-scale EEG analysis. Frontiers in neuroinformatics, 9, 16.

Examples

Basic correlation-based detection:

>>> from autoclean import annotate_uncorrelated_segments
>>> # Ensure montage is set
>>> raw.set_montage('standard_1020')
>>> raw_clean = annotate_uncorrelated_segments(raw)

Conservative detection with more neighbors:

>>> raw_clean = annotate_uncorrelated_segments(
...     raw,
...     n_nearest_neighbors=8,
...     corr_method="mean",
...     outlier_k=5.0,
...     outlier_flag_crit=0.3
... )

Sensitive detection for artifact-prone channels:

>>> raw_clean = annotate_uncorrelated_segments(
...     raw,
...     n_nearest_neighbors=3,
...     corr_method="max",
...     outlier_k=3.0,
...     outlier_flag_crit=0.15
... )

Robust detection with trimmed mean:

>>> raw_clean = annotate_uncorrelated_segments(
...     raw,
...     corr_method="trimmean",
...     corr_trim_percent=20.0,
...     epoch_duration=3.0
... )