quality.gfp_clean_epochs#

autoclean.functions.epoching.quality.gfp_clean_epochs(epochs, gfp_threshold=3.0, number_of_epochs=None, random_seed=None, return_gfp_values=False, verbose=None)[source]#

Clean epochs based on Global Field Power (GFP) outlier detection.

This function removes epochs with abnormal Global Field Power values, which represent the spatial standard deviation across all electrodes at each time point. GFP is useful for identifying epochs with widespread artifacts affecting multiple channels simultaneously.

Optionally, the function can randomly subsample epochs after cleaning to achieve a target number of epochs for analysis.

Parameters:

epochsmne.Epochs: The epochs object to clean.
gfp_thresholdfloat, default 3.0: The z-score threshold for GFP-based outlier detection. Epochs with mean GFP z-scores exceeding this threshold will be removed.
number_of_epochsint or None, default None: If specified, randomly selects this number of epochs from the cleaned data. Useful for ensuring consistent epoch counts across conditions.
random_seedint or None, default None: Seed for random number generator when selecting epochs. Ensures reproducible results when number_of_epochs is specified.
return_gfp_valuesbool, default False: If True, returns a tuple of (epochs_clean, gfp_values) where gfp_values contains the computed GFP z-scores for each original epoch.
verbosebool or None, default None: Control verbosity of output.

Returns:

epochs_cleanmne.Epochs: The cleaned epochs object with GFP outliers removed and optionally randomly subsampled.
gfp_valuesnp.ndarray, optional: Array of GFP z-scores for each original epoch (only if return_gfp_values=True).

Raises:

TypeError: If epochs is not an MNE Epochs object.
ValueError: If threshold is not positive, number_of_epochs is invalid, or insufficient epochs remain after cleaning.
RuntimeError: If GFP cleaning fails due to processing errors.

See also

mne.Epochs.drop_bad: Drop bad epochs
autoclean.detect_outlier_epochs: Detect outliers using multiple measures

Notes

Global Field Power (GFP): GFP is calculated as the spatial standard deviation across all electrodes at each time point. It provides a reference-free measure of global brain activity and is particularly sensitive to artifacts that affect multiple channels simultaneously.

GFP Formula: GFP(t) = sqrt(sum((V_i(t) - V_mean(t))^2) / N) where V_i(t) is the voltage at electrode i and time t, V_mean(t) is the mean voltage across all electrodes at time t, and N is the number of electrodes.

Outlier Detection: The function computes the mean GFP for each epoch, converts to z-scores, and removes epochs exceeding the threshold. This approach effectively identifies epochs with abnormal global activity patterns.

Random Subsampling: When number_of_epochs is specified, the function randomly selects epochs from the cleaned data. This is useful for: - Equalizing epoch counts across conditions - Reducing computational load for subsequent analyses - Creating balanced datasets for machine learning

References

Lehmann, D., & Skrandies, W. (1980). Reference-free identification of components of checkerboard-evoked multichannel potential fields. Electroencephalography and clinical neurophysiology, 48(6), 609-621.

Examples

Clean epochs with default GFP threshold:

>>> from autoclean import gfp_clean_epochs
>>> clean_epochs = gfp_clean_epochs(epochs, gfp_threshold=3.0)

Clean and subsample to specific number of epochs:

>>> clean_epochs = gfp_clean_epochs(
...     epochs,
...     gfp_threshold=2.5,
...     number_of_epochs=40,
...     random_seed=42
... )

Clean epochs and return GFP values for analysis:

>>> clean_epochs, gfp_scores = gfp_clean_epochs(
...     epochs,
...     return_gfp_values=True
... )