mne_denoise.asr.select_juggler_reference_samples#

mne_denoise.asr.select_juggler_reference_samples(X: ndarray, sfreq: float, strategy: str = 'dbscan', selection_filter_kind: str = 'asr', dbscan_top_k: int = 5, dbscan_eps: float | str = 'auto', dbscan_min_samples: int | float | str = 'auto', gev_grid_size: int = 2048, min_reference_fraction: float = 0.05) → tuple[ndarray, ndarray, dict[str, Any]][source]#

Select calibration samples using Juggler’s ASR rules.

Parameters:

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

  • sfreq (float) – Sampling frequency in Hz.

  • strategy ({'dbscan', 'gev'}) – Juggler reference-selection strategy.

  • selection_filter_kind ({'asr', 'highpass', 'none'}) – Statistics-only filter applied before amplitude ranking. The paper uses the ASR pre-emphasis filter, so 'asr' is the default.

  • dbscan_top_k (int) – Number of largest per-sample channel amplitudes to keep as the DBSCAN feature vector. The paper uses five channels.

  • dbscan_eps (float | {'auto', 'paper'}) – DBSCAN neighborhood radius. 'auto' and 'paper' use one tenth of the modal maximum amplitude, matching the paper description.

  • dbscan_min_samples (int | float | {'auto', 'paper'}) – DBSCAN core-neighborhood count. 'auto' and 'paper' use ten percent of the mode-derived clean-sample count.

  • gev_grid_size (int) – Number of grid points used when locating the fitted GEV mode.

  • min_reference_fraction (float) – Minimum acceptable retained fraction. Smaller retained sets are treated as calibration failures.

Returns:

  • X_ref (ndarray, shape (n_channels, n_selected_times)) – Selected samples from the causally pre-emphasized data. Juggler applies the ASR IIR filter before pointwise selection and calibrates from the resulting filtered reference samples.

  • sample_mask (ndarray, shape (n_times,)) – Boolean mask of the retained reference samples.

  • diagnostics (dict) – Selection diagnostics including fitted modes, DBSCAN labels, and the retained fraction.

Examples

>>> import numpy as np
>>> from mne_denoise.asr.juggler import select_juggler_reference_samples
>>> rng = np.random.default_rng(42)
>>> sfreq = 100.0
>>> # Generate 10 seconds of 4-channel noise
>>> data = rng.standard_normal((4, 1000))
>>> # Inject a large artifact in the middle
>>> data[:, 450:550] *= 20.0
>>> X_ref, sample_mask, diagnostics = select_juggler_reference_samples(
...     data, sfreq, strategy="dbscan"
... )
>>> # The reference dataset should be smaller than the original
>>> X_ref.shape[1] < data.shape[1]
True