mne_denoise.bss_cca.compute_bss_cca#

Learn and apply reference-free BSS-CCA to a channel-first array.

This is the canonical implementation of the algorithm of [1]. It applies the learned operator to the same data used to estimate it; use BSSCCA to fit and transform separate data.

Exactly one of n_remove or rho_threshold must be supplied. [R45dec616e405-1]_ selects a component count and describes threshold-based selection as unvalidated future work, so no default is assumed on your behalf.

Parameters:

X (ndarray, shape (n_channels, n_times) | (n_epochs, n_channels, n_times)) – Continuous or epoched channel-first data.
lag_samples (int | None, default=None) – Positive lag in samples. None uses the paper’s value of 1 unless lag_seconds is given.
lag_seconds (float | None, default=None) – Positive lag in physical time. Requires sfreq. Mutually exclusive with lag_samples.
sfreq (float | None, default=None) – Sampling frequency, required by lag_seconds and segment_len.
n_remove (int | None, default=None) – Number of lowest-correlation components to remove, the operating knob used in [1].
rho_threshold (float | None, default=None) – Retain components whose canonical correlation is at least this value.
segment_len (float | None, default=None) – Block length in seconds. None learns one operator for all data. A value fits an independent operator per block, as in the contiguous 10 s scheme of [2]. Blocks never span an epoch boundary.
overlap (float, default=0.0) – Fraction of segment_len shared between consecutive blocks. 0 reproduces the paper’s contiguous blocks; a positive value blends neighbouring blocks and is a package extension.
preserve_mean (bool, default=True) – Add the fitted channel mean back after cleaning. Equation (7) of [1] reconstructs mean-free data; restoring the mean keeps the output on the same offset as the input.
verbose (bool | str | int | None, default=None) – MNE-style logging level.

Returns:

X_clean (ndarray) – Cleaned data with the same shape as X.
info (dict) – Fitted operators, component diagnostics, and the resolved operating point. Per-block entries are tuples ordered by block.

Raises:

TypeError – If a scalar parameter has an invalid type.
ValueError – If X, the lag, the selection rule, or the blocking is invalid, or if there are not more lagged pairs than channels.

See also

BSSCCA: Estimator interface with leakage-safe fit/transform.
mne_denoise.icanclean.compute_icanclean: Reference-based CCA cleaning.

Notes

Canonical correlations are non-negative, so a component dominated by near-Nyquist energy is anti-correlated at the lag yet ranks near the top. Band-limit the input as both source papers do, and check info['autocorrelations'] for negative entries.

Examples

>>> import numpy as np
>>> from mne_denoise.bss_cca import compute_bss_cca
>>> rng = np.random.default_rng(0)
>>> t = np.arange(2500) / 250.0
>>> brain = np.sin(2 * np.pi * 10 * t) * rng.standard_normal((8, 1))
>>> observed = brain + 0.5 * rng.standard_normal((8, t.size))
>>> cleaned, info = compute_bss_cca(observed, n_remove=4)
>>> cleaned.shape
(8, 2500)

References

[1] (1,2,3)

De Clercq, W., Vergult, A., Vanrumste, B., Van Paesschen, W., & Van Huffel, S. (2006). Canonical correlation analysis applied to remove muscle artifacts from the electroencephalogram. IEEE Transactions on Biomedical Engineering, 53(12), 2583-2587. https://doi.org/10.1109/TBME.2006.879459

[2]

Vergult, A., De Clercq, W., Palmini, A., Vanrumste, B., Dupont, P., Van Huffel, S., & Van Paesschen, W. (2007). Improving the interpretation of ictal scalp EEG: BSS-CCA algorithm for muscle artifact removal. Epilepsia, 48(5), 950-958. https://doi.org/10.1111/j.1528-1167.2007.01031.x