pybemobil.preproc.compute_ica

pybemobil.preproc.compute_ica(raw, filter_bands_ica=(1.75, 100.0), downsample_ica=250, thresh=-1, rng_seed=None, exclude_labels=None, include_labels=None, ica_method='jamica', jamica_kwargs=None, reject_by_annotation=True)

Fit ICA on a filtered copy of raw and label components with ICLabel.

Parameters:

rawmne.io.Raw

Continuous EEG recording (must contain EEG channels).

filter_bands_icatuple of float

(l_freq, h_freq) for the ICA-specific bandpass filter. The default (1.75, 100.0) uses BeMoBIL’s 1.75 Hz AMICA high-pass and the 100 Hz low-pass ICLabel expects. EEGPreprocessor uses (1.75, None) because its data is already low-passed at 100 Hz.

downsample_icafloat

Target sampling rate for ICA fitting (anti-aliasing applied automatically). Skipped when the recording is already at or below this rate.

threshfloat

ICLabel decision rule. -1 (default) is popularity-vote mode, as in BeMoBIL (iclabel_threshold=-1): each IC is assigned to the class with the highest probability and excluded if that class is not kept. A value in [0, 1] is probability-threshold mode: an IC is excluded only when its winning class is one to remove and that class’s probability is at least thresh; uncertain ICs are kept.

rng_seedint | None

Random seed passed to mne.preprocessing.ICA for reproducibility.

exclude_labelslist of str | None

ICLabel classes to exclude (e.g. ["eye blink", "muscle artifact"]). Mutually exclusive with include_labels.

include_labelslist of str | None

ICLabel classes to keep; all other classes are excluded (e.g. ["brain", "other"]). If neither this nor exclude_labels is given, all classes except "eye blink" are kept, as in EEGPreprocessor and BeMoBIL. Valid names are "brain", "muscle artifact", "eye blink", "heart beat", "line noise", "channel noise" and "other". Mutually exclusive with exclude_labels.

ica_methodstr

ICA algorithm to use. "jamica" (default) uses jamica, a JAX-accelerated reimplementation of Adaptive Mixture ICA (AMICA), via jamica.fit_ica(). fit_ica replicates MNE’s whitening/PCA pipeline internally and returns a standard mne.preprocessing.ICA object directly. Any other string is passed directly as the method argument to mne.preprocessing.ICA (e.g. "picard", "fastica"). If "jamica" is requested but the jamica package is not installed, the method falls back to "picard" with an extended-infomax fit and a warning.

jamica_kwargsdict | None

Extra keyword arguments forwarded to jamica.fit_ica() when ica_method="jamica" (e.g. {"max_iter": 2000, "num_mix": 3}). AMICA’s likelihood-based sample rejection is on by default, matching the MATLAB BeMoBIL pipeline: fit_params defaults to pybemobil.preproc.utils.DEFAULT_JAMICA_FIT_PARAMS ({"do_reject": True, "rejsig": 3.0, "numrej": 10}) and any fit_params you pass are merged over it key by key. Pass {"fit_params": {"do_reject": False}} to disable rejection. Ignored when a non-jamica method is used.

reject_by_annotationbool

If True (default), 1 s epochs that overlap BAD_* annotations are left out of the ICA fit and of ICLabel.

Returns:

icamne.preprocessing.ICA

Fitted ICA object with ica.exclude populated according to the label criteria. ica.pybemobil_fit_info_ describes the fit that actually ran (method, requested_method, n_components, rng_seed, fit parameters, number of epochs and FASTER-dropped epochs); EEGPreprocessor records it in the provenance descriptor.

ic_labelsdict

Output of mne_icalabel.label_components() containing "labels" and "y_pred_proba" keys.

Raises:

ValueError

If both exclude_labels and include_labels are provided.