mne_denoise.asr.JugglerASR#

class mne_denoise.asr.JugglerASR(sfreq: float | None = None, cutoff: float = 20.0, strategy: str = 'dbscan', window_length: float = 0.5, window_overlap: float = 0.66, max_dropout_fraction: float = 0.1, min_clean_fraction: float = 0.25, picks: str | list[str] | list[int] | None = 'eeg', 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_dims: float | int = 0.66, reject_by_annotation: bool = True, skip_by_annotation: tuple[str, ...] = ('bad', 'bad_acq_skip'), cov_estimator: str = 'geometric_median', regularization: float = 1e-08, filter_kind: str = 'asr', window_criterion: float | int | str | None = None, window_criterion_tolerances: tuple[float, float] = (-inf, 7.0), lookahead: float | None = None, stepsize: int | None = None, max_mem_mb: int | None = 512, copy: bool = True, store_reconstruction_matrices: bool = False, 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, random_state: int | None = None, n_jobs: int | None = None, verbose: bool | str | int | None = None)[source]#

Juggler Artifact Subspace Reconstruction (JugglerASR).

This estimator replaces standard ASR’s sliding-window calibration logic with a pointwise amplitude procedure to select clean reference samples (Kim et al. 2025). The burst-repair (reconstruction) stage remains identical to mne_denoise.asr.ASR.

Two strategies for reference selection are available: - strategy='dbscan': Density-based spatial clustering (ASRDBSCAN) - strategy='gev': Generalized Extreme Value distribution fitting (ASRGEV)

Parameters:

  • sfreq (float | None, default=None) – Sampling frequency in Hz.

  • cutoff (float, default=20.0) – ASR threshold multiplier.

  • strategy ({'dbscan', 'gev'}, default='dbscan') – The reference sample selection strategy.

  • window_length (float, default=0.5) – Length of the burst-repair reconstruction window in seconds.

  • window_overlap (float, default=0.66) – Overlap fraction of the reconstruction window.

  • max_dropout_fraction (float, default=0.1) – Maximum allowed fraction of dropped out (zeroed) samples per window.

  • min_clean_fraction (float, default=0.25) – Minimum allowed fraction of clean components per window.

  • picks (str | list[str] | list[int] | None, default="eeg") – Channels to process.

  • calibration_window_length (float, default=1.0) – Fallback calibration window parameter (rarely used in Juggler, which selects point-by-point).

  • calibration_window_overlap (float, default=0.66) – Fallback calibration overlap.

  • ref_max_bad_channels (float, default=0.075) – Maximum fraction of bad channels in a window.

  • ref_tolerances (tuple[float, float], default=(-np.inf, 5.5)) – Z-score tolerances for fallback rejection.

  • blocksize (int, default=10) – Processing blocksize for covariance matrix memory.

  • max_dims (float | int, default=0.66) – Maximum retained variance/dimensions for reconstruction.

  • reject_by_annotation (bool, default=True) – Whether to reject bad segments annotated in MNE.

  • skip_by_annotation (tuple[str, ...], default=("bad", "bad_acq_skip")) – Annotation descriptions to skip.

  • cov_estimator (str, default="geometric_median") – Covariance estimator (‘geometric_median’ or ‘euclidean’).

  • regularization (float, default=1e-8) – Covariance regularization.

  • filter_kind (str, default="asr") – Pre-emphasis filter applied during calibration and reconstruction.

  • window_criterion (float | int | str | None, default=None) – Additional criterion for dropping dirty windows.

  • window_criterion_tolerances (tuple[float, float], default=(-np.inf, 7.0)) – Tolerances for window dropping.

  • lookahead (float | None, default=None) – State tracking parameter.

  • stepsize (int | None, default=None) – Step size.

  • max_mem_mb (int | None, default=512) – Maximum memory allowed for block processing.

  • copy (bool, default=True) – Whether to copy data.

  • store_reconstruction_matrices (bool, default=False) – Whether to store all per-window reconstruction matrices.

  • selection_filter_kind (str, default="asr") – Filter applied before DBSCAN/GEV sample selection.

  • dbscan_top_k (int, default=5) – Number of largest per-sample channel amplitudes to keep as DBSCAN features.

  • dbscan_eps (float | str, default="auto") – DBSCAN neighborhood radius.

  • dbscan_min_samples (int | float | str, default="auto") – DBSCAN core-neighborhood count.

  • gev_grid_size (int, default=2048) – Number of grid points for GEV fitting.

  • min_reference_fraction (float, default=0.05) – Minimum fraction of samples that must be retained as clean reference.

  • random_state (int | None, default=None) – Random state for reproducibility.

  • n_jobs (int | None, default=None) – Number of parallel jobs.

  • verbose (bool | str | int | None, default=None) – Logging verbosity.

__init__(sfreq: float | None = None, cutoff: float = 20.0, strategy: str = 'dbscan', window_length: float = 0.5, window_overlap: float = 0.66, max_dropout_fraction: float = 0.1, min_clean_fraction: float = 0.25, picks: str | list[str] | list[int] | None = 'eeg', 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_dims: float | int = 0.66, reject_by_annotation: bool = True, skip_by_annotation: tuple[str, ...] = ('bad', 'bad_acq_skip'), cov_estimator: str = 'geometric_median', regularization: float = 1e-08, filter_kind: str = 'asr', window_criterion: float | int | str | None = None, window_criterion_tolerances: tuple[float, float] = (-inf, 7.0), lookahead: float | None = None, stepsize: int | None = None, max_mem_mb: int | None = 512, copy: bool = True, store_reconstruction_matrices: bool = False, 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, random_state: int | None = None, n_jobs: int | None = None, verbose: bool | str | int | None = None) → None[source]#

Methods

__init__([sfreq, cutoff, strategy, ...])

fit(X[, y, calibration, calibration_mask])

Fit JugglerASR from a contaminated or clean calibration stream.

fit_transform(X[, y, calibration, ...])

Fit ASR and apply it to X.

get_calibration_mask()

Return the sample-wise reference mask chosen during calibration.

get_diagnostics()

Return diagnostics from the last transform.

get_metadata_routing()

Get metadata routing of this object.

get_params([deep])

Get parameters for this estimator.

get_rejection_mask()

Return the retained-sample mask from final clean_windows-style rejection.

set_fit_request(*[, calibration, ...])

Configure whether metadata should be requested to be passed to the fit method.

set_output(*[, transform])

Set output container.

set_params(**params)

Set the parameters of this estimator.

set_transform_request(*[, copy, ...])

Configure whether metadata should be requested to be passed to the transform method.

to_annotations([kind, min_components, ...])

Convert ASR decisions into MNE annotations.

transform(X[, y, copy, return_diagnostics])

Apply the fitted ASR model.