mne_denoise.icanclean.compute_icanclean#

mne_denoise.icanclean.compute_icanclean(X_primary: ndarray, X_ref: ndarray, sfreq: float, 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, verbose: bool = True) → tuple[ndarray, dict[str, Any]][source]#

Compute one iCanClean pass on continuous NumPy arrays.

This implements the core array-based iCanClean algorithm for one continuous primary/reference recording pair. It returns cleaned primary channels together with per-pass quality-control outputs.

The supported single-pass modes differ in where the CCA decomposition is estimated and how that decomposition is reused:

mode='global'

Run CCA once on the full recording.
Threshold the resulting \(R^2\) values.
Build the selected noise basis from U, V, or both.
Regress that basis onto the full primary recording and subtract it.

mode='sliding'

Split the recording into overlapping clean windows.
Run a fresh CCA inside each window, optionally using a broader stats window when stats_segment_len is larger than segment_len.
Threshold the window-local \(R^2\) values.
Regress the selected window-local basis onto that window and combine cleaned windows with overlap-add.

mode='calibrated'

Run CCA once on the full recording to obtain a fixed global decomposition.
Fit one global least-squares map from the selected global canonical basis back to the primary channels.
For each clean window, project the local data through the fixed global decomposition, score components with window-local correlations, and subtract only the window-local active part of the globally calibrated basis.

Sliding-window cleaning is currently executed sequentially. A future optimization could parallelize fixed-threshold sliding windows, but that would need to preserve overlap-add semantics and the current sequential behavior of threshold='auto'.

Parameters:

X_primary (ndarray, shape (n_primary, n_times)) – Primary channels to clean.
X_ref (ndarray, shape (n_ref, n_times)) – Reference channels that capture artifact activity.
sfreq (float) – Sampling frequency in Hz.
mode ({'sliding', 'global', 'calibrated'}, default='sliding') – Cleaning mode for this single pass. 'global' runs one pass over the full recording, 'sliding' uses overlapping windows, and 'calibrated' uses one global CCA calibration followed by per-window scoring and subtraction with the fixed global basis.
clean_with ({'X', 'Y', 'both'}, default='X') – Canonical variates used as the noise basis.
segment_len (float, default=2.0) – Sliding clean-window duration in seconds.
overlap (float, default=0.0) – Fractional overlap between consecutive windows in [0, 1).
threshold (float | 'auto', default=0.7) – \(R^2\) threshold for component rejection.
max_reject_fraction (float, default=0.5) – Maximum fraction of canonical components removed per window.
reref_primary (bool | str, default=False) – Average re-reference mode applied to primary channels for CCA only.
reref_ref (bool | str, default=False) – Average re-reference mode applied to reference channels for CCA only.
stats_segment_len (float | None, default=None) – Broader stats-window duration in seconds for sliding mode.
verbose (bool, default=True) – Whether to log progress information.

Returns:

X_primary_clean (ndarray, shape (n_primary, n_times)) – Cleaned primary channels.
qc (dict) – Per-pass quality-control outputs with the same top-level fields used by ICanClean: correlations_, n_removed_, removed_idx_, filters_, patterns_, and n_windows_.