mne_denoise.icanclean.null_r2_threshold#

mne_denoise.icanclean.null_r2_threshold(X_cca: ndarray, Y_cca: ndarray, *, alpha: float = 0.05, n_surrogate: int = 100, random_state: int | Generator | None = None) → float[source]#

Estimate a circular-shift null threshold for squared CCA correlations.

Parameters:

X_ccandarray, shape (n_times, n_primary): Primary CCA block.
Y_ccandarray, shape (n_times, n_reference): Reference CCA block.
alphafloat, default=0.05: Upper-tail probability used for the null quantile.
n_surrogateint, default=100: Number of circular-shift surrogates.
random_stateint, numpy.random.Generator, or None, default=None: Random state for shift offsets.

Returns:

float: Quantile of the maximum surrogate squared canonical correlation.

See also

ICanClean: Estimator that applies the threshold within its cleaning workflow.

Notes

Circular shifts preserve within-channel temporal structure while disrupting alignment between the two blocks. The threshold addresses finite-sample shared correlation; it does not identify whether shared variance is artifact. This is package functionality around the published iCanClean workflow, not a claim about its original core method.

Examples

>>> import numpy as np
>>> from mne_denoise.icanclean import null_r2_threshold
>>> rng = np.random.default_rng(0)
>>> X_cca = rng.standard_normal((1000, 4))
>>> Y_cca = rng.standard_normal((1000, 2))
>>> threshold = null_r2_threshold(X_cca, Y_cca, n_surrogate=20, random_state=0)