Preprocessing
Data preprocessing functions
| Option | Description |
|---|---|
| title | prep.py |
| authors | Anaël Ayrolles, Florence Brun, Guillaume Dumas |
| date | 2020-03-18 |
DicAR
Bases: TypedDict
Dictionary type for storing epoch rejection information.
This type provides structured information about the rejection process, including the rejection strategy, threshold, and percentage of epochs rejected for each participant and the dyad.
Attributes
strategy : str The strategy used for epoch rejection ('union' or 'intersection')
float
The maximum allowed percentage of epochs to be rejected
float
Percentage of epochs rejected for participant 1
float
Percentage of epochs rejected for participant 2
float
Overall percentage of epochs rejected across both participants
AR_local(cleaned_epochs_ICA, strategy='union', threshold=50.0, verbose=False)
Apply local Autoreject to repair or reject bad epochs.
After ICA cleaning, this function identifies remaining problematic epochs and either repairs them (by interpolating bad channels) or rejects them entirely. It can use different strategies to handle epochs that are bad in only one participant.
Parameters
cleaned_epochs_ICA : List[mne.Epochs] List of Epochs objects after ICA cleaning (one for each participant)
str, optional
Strategy for handling bad epochs (default='union'): - 'union': Reject epochs that are bad in either participant - 'intersection': Reject only epochs that are bad in both participants, attempt to repair other bad epochs individually
float, optional
Maximum acceptable percentage of rejected epochs (default=50.0) If more epochs would be rejected, raises an error
bool, optional
Whether to plot before/after comparisons (default=False)
Returns
cleaned_epochs_AR : List[mne.Epochs] List of Epochs objects after Autoreject cleaning
DicAR
Dictionary with information about the rejection process: - 'strategy': Strategy used ('union' or 'intersection') - 'threshold': Maximum acceptable percentage of rejected epochs - 'S1': Percentage of epochs rejected for participant 1 - 'S2': Percentage of epochs rejected for participant 2 - 'dyad': Overall percentage of epochs rejected
Notes
This function uses the autoreject package to automatically identify and handle problematic epochs. The identification is based on statistical properties of the data and is more objective than manual rejection.
With the 'intersection' strategy, the function also equalizes the number of epochs between participants after cleaning.
Raises
RuntimeError If the percentage of rejected epochs exceeds the specified threshold
Examples
Apply Autoreject with default settings
cleaned_epochs, rejection_info = AR_local(ica_cleaned_epochs)
Use 'intersection' strategy with lower threshold
cleaned_epochs, rejection_info = AR_local( ... ica_cleaned_epochs, strategy='intersection', threshold=30.0, verbose=True ... ) print(f"Rejected {rejection_info['dyad']}% of epochs")
ICA_apply(icas, subject_id, component_id, epochs, plot=True)
Apply ICA artifact rejection using a template component.
This function uses a component from one participant as a template to identify similar artifact components in all participants, then removes these components from the data.
Parameters
icas : List[ICA] List of fitted ICA objects (one for each participant)
int
Index of the participant whose component will serve as the template
int
Index of the component to use as the template
List[mne.Epochs]
List of Epochs objects to clean (one for each participant)
bool, optional
Whether to plot the identified components (default=True)
Returns
cleaned_epochs_ICA : List[mne.Epochs] List of ICA-cleaned Epochs objects (one for each participant)
Notes
This function uses MNE's corrmap function to identify components similar to the template component. It then labels these components as 'blink' artifacts and removes them from the data.
The threshold for component similarity is set to 0.9 by default.
Examples
Use the first component of the first participant as template
cleaned_epochs = ICA_apply(icas, subject_id=0, component_id=0, epochs=epochs)
ICA_choice_comp(icas, epochs)
Select ICA components for artifact rejection and apply ICA cleaning to epochs.
This interactive function plots the Independent Components for each participant, lets the user choose relevant components for artifact rejection, and applies the cleaning to the epochs data.
Parameters
icas : List[ICA] List of fitted ICA objects (one for each participant)
List[mne.Epochs]
List of Epochs objects to clean (one for each participant)
Returns
cleaned_epochs_ICA : List[mne.Epochs] List of ICA-cleaned Epochs objects (one for each participant)
Notes
The function uses an interactive approach: 1. It plots the ICA components for each participant 2. It prompts the user to select a participant and component to use as a template 3. It uses corrmap to find similar components across participants 4. It removes the identified components from all participants' data
If you don't want to apply ICA cleaning, simply press Enter without typing anything when prompted for participant and component selection.
Examples
This function is interactive and prompts the user for input
cleaned_epochs = ICA_choice_comp(icas, epochs)
ICA_fit(epochs, n_components, method, fit_params, random_state)
Compute Independent Component Analysis (ICA) on epochs for artifact rejection.
This function applies global Autoreject to establish rejection thresholds, then fits ICA on the cleaned data. ICA is a commonly used technique to identify and remove artifacts such as eye blinks, muscle activity, and cardiac artifacts.
Parameters
epochs : List[mne.Epochs] List of Epochs objects (one for each participant)
int
Number of principal components to pass to the ICA algorithm For a first estimation, a value around 15 is often appropriate
str
ICA method to use. Options: - 'fastica': FastICA algorithm (most commonly used) - 'infomax': Infomax algorithm - 'picard': Picard algorithm
dict
Additional parameters passed to the ICA estimator For Extended Infomax, use method='infomax' and fit_params=dict(extended=True)
int
Random seed for reproducible results For 15 components, random_state=97 works well For 20 components, random_state=0 works well
Returns
icas : List[ICA] List of fitted ICA objects (one for each participant)
Notes
Pre-requisites: - Install autoreject: https://api.github.com/repos/autoreject/autoreject/zipball/master - Filter the Epochs between 2 and 30 Hz before ICA fitting
If Autoreject and ICA take too much time, try changing the 'decim' value in the ICA initialization to downsample the data during fitting.
Examples
Fit ICA with 15 components using FastICA
icas = ICA_fit(epochs_list, n_components=15, method='fastica', ... fit_params=None, random_state=97)
Fit ICA with Extended Infomax
icas = ICA_fit(epochs_list, n_components=15, method='infomax', ... fit_params=dict(extended=True), random_state=97)
filt(raw_S, freqs=(2.0, None))
Filter a list of raw EEG data to remove slow drifts or other unwanted frequency components.
This function applies a high-pass or band-pass filter to each Raw object in the input list. Filtering helps to remove low-frequency drifts, power line noise, or other frequency-specific artifacts from the EEG data.
Parameters
raw_S : List[mne.io.Raw] List of Raw objects containing continuous EEG data
Tuple[Union[float, None], Union[float, None]], optional
Frequency range for filtering (default=(2., None)): - First element: Lower frequency bound (high-pass filter cutoff) - Second element: Upper frequency bound (low-pass filter cutoff) - None for either bound means no filtering in that direction
Returns
raws : List[mne.io.Raw] List of filtered Raw objects with the same structure as the input
Notes
By default, a 2 Hz high-pass filter is applied, which effectively removes slow drifts while preserving most of the EEG signal content. This is appropriate for most EEG analyses but may need adjustment for specific paradigms.
Examples
Filter data with a high-pass at 1 Hz
filtered_raws = filt(raw_list, freqs=(1., None))
Apply a band-pass filter between 1 and 40 Hz
filtered_raws = filt(raw_list, freqs=(1., 40.))