mne_denoise.icanclean.ICanClean

class mne_denoise.icanclean.ICanClean(sfreq: float, ref_channels: list[str] | list[int] | None = None, primary_channels: list[str] | list[int] | None = None, mode: str = 'sliding', clean_with: str = 'X', segment_len: float = 2.0, overlap: float = 0.0, threshold: float | str = 0.7, max_reject_fraction: float = 0.5, reref_primary: bool | str = False, reref_ref: bool | str = False, stats_segment_len: float | None = None, filter_ref: tuple | None = None, pseudo_ref: bool = False, null_random_state: int | None = None, global_threshold: float | str | None = None, global_clean_with: str | None = None, global_max_reject_fraction: float | None = None, verbose: bool | str | int | None = None)

Reference-based CCA artifact-removal estimator.

ICanClean compares primary channels with physical or derived reference channels and removes selected shared canonical components. Cleaning is estimated during transform; fit is a compatibility no-op.

Parameters:

sfreqfloat

Sampling frequency in Hz.

ref_channelslist of str, list of int, or None, default=None

Reference channels. Required unless pseudo_ref=True.

primary_channelslist of str, list of int, or None, default=None

Primary channels; by default all channels not in ref_channels.

mode{“sliding”, “global”, “calibrated”, “hybrid”}, default=”sliding”

CCA fitting and cleaning mode.

clean_with{“X”, “Y”, “both”}, default=”X”

Canonical basis used for artifact regression.

segment_lenfloat, default=2.0

Cleaning-window length in seconds.

overlapfloat, default=0.0

Fractional overlap between windows.

thresholdfloat or {“auto”, “null”}, default=0.7

Squared-correlation rejection threshold.

max_reject_fractionfloat, default=0.5

Maximum fraction of components removed per window.

reref_primarybool or str, default=False

Average-reference option for primary channels used in CCA.

reref_refbool or str, default=False

Average-reference option for reference channels used in CCA.

stats_segment_lenfloat or None, default=None

Broader statistics window for supported sliding modes.

filter_reftuple or None, default=None

Optional zero-phase Butterworth specification applied to reference data.

pseudo_refbool, default=False

Build the reference block from filtered primary data.

null_random_stateint or None, default=None

Seed for threshold=”null” surrogates.

global_thresholdfloat, str, or None, default=None

Threshold for the global pass in hybrid mode.

global_clean_with{“X”, “Y”, “both”} or None, default=None

Basis for the global pass in hybrid mode.

global_max_reject_fractionfloat or None, default=None

Removal cap for the global pass in hybrid mode.

verbosebool, str, int, or None, default=None

Logging level.

Attributes:

correlations_ndarray

Squared canonical correlations by window.

n_removed_ndarray

Number of removed components by window.

removed_idx_list of ndarray

Removed component indices by window.

filters_, patterns_list of ndarray

CCA filters and patterns by window.

n_windows_int

Number of processed windows.

primary_channels_, ref_channels_list

Fitted channel selections.

See also

mne_denoise.bss_cca.BSSCCA

Reference-free CCA using a lagged copy of the primary signal.

compute_icanclean

One-shot functional interface for continuous array data.

null_r2_threshold

Package circular-shift surrogate threshold for squared canonical correlations; this is an extension around the published method.

Notes

NumPy input is channel-first; MNE Raw, Epochs, and Evoked inputs are supported and returned as the same container type. A high shared correlation is not, by itself, evidence that a component is artifact [1][2][3].

References

[1]

Ryan J. Downey and Daniel P. Ferris. The icanclean algorithm: how to remove artifacts using reference noise recordings. 2022. arXiv:2201.11798, doi:10.48550/arXiv.2201.11798.

[2]

Ryan J. Downey and Daniel P. Ferris. Icanclean removes motion, muscle, eye, and line-noise artifacts from phantom eeg. Sensors, 23(19):8214, 2023. doi:10.3390/s23198214.

[3]

Colton B. Gonsisko, Daniel P. Ferris, and Ryan J. Downey. Icanclean improves independent component analysis of mobile brain imaging with eeg. Sensors, 23(2):928, 2023. doi:10.3390/s23020928.

Examples

>>> import numpy as np
>>> from mne_denoise.icanclean import ICanClean
>>> rng = np.random.default_rng(0)
>>> data = rng.standard_normal((8, 2000))
>>> model = ICanClean(sfreq=250.0, ref_channels=[6, 7])
>>> clean = model.fit_transform(data)

fit(X: Any, y=None, *, verbose: bool | str | int | None = None) → ICanClean

Return self without performing cleaning.

Cleaning is estimated during transform because the estimator operates on record-specific reference blocks and windows.

Parameters:

XRaw, Epochs, Evoked, or ndarray

Input data; not transformed by this method.

yNone, default=None

Ignored for scikit-learn compatibility.

verbosebool, str, int, or None, default=None

Logging level.

Returns:

ICanClean

The estimator.

fit_transform(X: Any, y=None, *, callback=None, verbose: bool | str | int | None = None, **fit_params) → Any

Return fit(X).transform(X).

Parameters:

XRaw, Epochs, Evoked, or ndarray

Data to clean.

yNone, default=None

Ignored for scikit-learn compatibility.

callbackcallable or None, default=None

Synchronous callback for completed continuous windows.

verbosebool, str, int, or None, default=None

Logging level.

**fit_paramsdict

Unexpected fit parameters raise TypeError.

Returns:

same type as X

Cleaned data.

transform(X: Any, y=None, *, callback=None, verbose: bool | str | int | None = None) → Any

Apply iCanClean to the input.

Parameters:

XRaw, Epochs, Evoked, or ndarray

Data to clean. NumPy input is channel-first.

yNone, default=None

Ignored for scikit-learn compatibility.

callbackcallable or None, default=None

Synchronous callback for completed continuous windows.

verbosebool, str, int, or None, default=None

Logging level.

Returns:

same type as X

Cleaned data in a copy of the input container or array layout.