mne_denoise.asr.calibrate_asr#

mne_denoise.asr.calibrate_asr(X: ndarray, sfreq: float, cutoff: float = 20.0, window_length: float = 0.5, window_overlap: float = 0.66, calibration: str = 'auto', calibration_window_length: float = 1.0, calibration_window_overlap: float = 0.66, ref_max_bad_channels: float = 0.075, ref_tolerances: tuple[float, float] = (-inf, 5.5), blocksize: int = 10, max_dropout_fraction: float = 0.1, min_clean_fraction: float = 0.25, cov_estimator: str = 'geometric_median', regularization: float = 1e-08, filter_kind: str = 'none', method: str = 'standard', max_mem_mb: int | None = 512) → tuple[ASRState, dict[str, Any]][source]#

Calibrate a standard ASR model from continuous data.

Parameters:

  • X (ndarray, shape (n_channels, n_times)) – Continuous calibration data.

  • sfreq (float) – Sampling frequency in Hz.

  • cutoff (float) – ASR threshold multiplier. Lower values clean more aggressively.

  • window_length (float) – Processing/statistics window length in seconds.

  • window_overlap (float) – Overlap fraction for threshold-fitting windows.

  • calibration ({'auto', 'manual'}) – Whether to select clean calibration windows automatically or use all supplied samples.

  • calibration_window_length (float) – Window length in seconds for automatic clean-window selection.

  • calibration_window_overlap (float) – Overlap fraction for automatic clean-window selection.

  • ref_max_bad_channels (float) – Maximum fraction of channels that may exceed ref_tolerances for a calibration window to be retained.

  • ref_tolerances (tuple of float) – Lower and upper robust z-score tolerances for clean-window selection.

  • blocksize (int) – Number of successive samples averaged into each covariance block for robust calibration covariance estimation.

  • max_dropout_fraction (float) – Fraction of the lowest RMS values excluded while fitting thresholds.

  • min_clean_fraction (float) – Minimum central fraction used to estimate clean RMS statistics.

  • cov_estimator ({'geometric_median', 'mean', 'median'}) – Robust aggregation rule for calibration-window covariance matrices.

  • regularization (float) – Relative eigenvalue floor used for SPD regularization.

  • filter_kind ({'none', 'asr', 'highpass'}) – Statistics-only filter. 'asr' applies the original inverse-EEG Yule-Walker pre-emphasis filter, 'highpass' applies a lightweight high-pass filter, and 'none' avoids implicit filtering.

  • max_mem_mb (int | None) – Reserved memory limit for future chunking. Present for API stability.

Returns:

  • state (ASRState) – Fitted ASR state containing the threshold matrix T and mixing matrix M.

  • diagnostics (dict) – Calibration diagnostics, including filter state and geometry info.

Examples

Calibrate an ASR model from a 10-channel, 1000-sample array:

>>> import numpy as np
>>> from mne_denoise.asr import calibrate_asr
>>> rng = np.random.default_rng(42)
>>> data = rng.standard_normal((10, 1000))
>>> state, diagnostics = calibrate_asr(data, sfreq=250.0, cutoff=20.0)
>>> print(f"Threshold matrix shape: {state.T.shape}")
Threshold matrix shape: (10, 10)