Independent Component Analysis#
This section documents the Independent Component Analysis (ICA) functions for decomposition and component classification.
ICA Decomposition#
- eegprep.eeg_amica(EEG, posact='off', sortcomps='off', num_models=1, max_iter=2000, num_mix_comps=3, pcakeep=None, outdir=None, amica_binary=None, max_threads=4, **kwargs)
Perform ICA decomposition using AMICA (Adaptive Mixture ICA).
AMICA fits one or more ICA models with generalized Gaussian mixture source distributions via an external Fortran binary. Standard ICA fields are populated from model 0. The full multi-model output is stored in EEG[‘etc’][‘amica’].
EEGPrep wheels do not ship AMICA binaries. Provide the executable with the amica_binary argument, the AMICA_BINARY environment variable, or PATH.
Parameters#
- EEGdict
EEGLAB-like data structure.
- posactstr | bool, optional
If ‘on’ or True, normalize component signs so max(abs(activations)) is positive. Default is ‘off’.
- sortcompsstr | bool, optional
If ‘on’ or True, sort components by descending activation variance. Default is ‘off’.
- num_modelsint
Number of ICA models to fit.
- max_iterint
Maximum number of training iterations.
- num_mix_compsint
Number of mixture components per source.
- pcakeepint or None
Number of principal components to retain. Default: nbchan.
- outdirstr or None
Output directory for AMICA. If None, a temporary directory is used.
- amica_binarystr or None
Path to AMICA binary. If None, auto-detected from AMICA_BINARY, a source-tree development binary, EEGLAB’s AMICA plugin, or PATH.
- max_threadsint
Maximum number of threads for the binary.
- kwargsdict
Additional AMICA parameters passed through to the binary.
Returns#
- dict
The updated EEG structure with ICA fields.
- eegprep.eeg_picard(EEG, engine=None, posact='off', sortcomps='off', **kwargs)
Perform ICA decomposition using Picard algorithm.
This function can use either a Python implementation or an EEGLAB (via MATLAB or Octave) implementation.
Parameters#
- EEGdict
EEGLAB-like data structure.
- engineobject, optional
MATLAB or Octave engine instance. If None (default), the Python implementation is used.
- posactstr | bool, optional
If ‘on’ or True, normalize component signs so max(abs(activations)) is positive. Default is ‘off’.
- sortcompsstr | bool, optional
If ‘on’ or True, sort components by descending activation variance. Default is ‘off’.
- kwargsdict
Additional keyword arguments to pass to the Picard algorithm. For example,
{"maxiter": 500}.
Returns#
- dict
The updated EEG structure with ICA fields.
- eegprep.eeg_runica(EEG, posact='off', sortcomps='off', **kwargs)
Perform ICA decomposition using runica (infomax) algorithm.
Parameters#
- EEGdict
EEGLAB-like data structure.
- posactstr | bool, optional
If ‘on’ or True, normalize component signs so max(abs(activations)) is positive. Default is ‘off’.
- sortcompsstr | bool, optional
If ‘on’ or True, sort components by descending activation variance. Default is ‘off’.
- kwargsdict
Additional keyword arguments to pass to the runica algorithm.
Returns#
- dict
The updated EEG structure with ICA fields.
Component Classification#
- eegprep.iclabel(EEG, algorithm='default', engine=None)
Apply ICLabel to classify independent components.
Parameters#
- EEGdict
EEGLAB EEG structure
- algorithmstr
Algorithm to use for classification, passed to the MATLAB/Octave implementation. Default is ‘default’.
- enginestr or None
Engine to use for implementation. Options are: - None: Use the default Python implementation - ‘matlab’: Use MATLAB engine - ‘octave’: Use Octave engine
Returns#
- EEGdict
EEGLAB EEG structure with ICLabel classifications added
- eegprep.eeg_icalabelstat(EEG, threshold=0.9, *, verbose=True, stream=None)
Return and optionally print ICLabel class statistics.
This mirrors EEGLAB’s
plugins/ICLabel/eeg_icalabelstat.msummary, including class order and the historicalIClabelconsole label, while returning structured Python statistics for programmatic use.- Parameters:
EEG (dict[str, Any]) – EEGPrep/EEGLAB-style dataset with ICLabel classifications under
EEG["etc"]["ic_classification"]["ICLabel"].threshold (float | list[float] | tuple[float, ...] | ndarray) – Scalar probability threshold applied to every class, or one threshold per ICLabel class.
verbose (bool) – Print EEGLAB-style summary lines when true.
stream (TextIO | None) – Destination for printed summary lines. Defaults to stdout.
- Returns:
Dictionary containing class names, thresholds, per-class counts, 1-based component indices above threshold, mean probabilities, dominant class counts, and current rejected/kept tallies.
- Return type: