mne_denoise.dss.DSS#

class mne_denoise.dss.DSS(bias: LinearDenoiser | Callable, n_components: int | None = None, n_select: int | str | None = None, selection_threshold: float = 3.0, knee_rel_floor: float = 0.01, knee_min_ratio: float = 3.0, rank: int | dict | None = None, reg: float = 1e-09, normalize_input: bool = True, cov_method: str = 'empirical', cov_kws: dict | None = None, smooth: LinearDenoiser | int | None = None, adaptive: bool = False, segmenter: CovarianceSegmenter | FixedWindowSegmenter | None = None, crossfade: float = 0.0, max_prop_remove: float | None = None, min_select: int = 0, component_action: str = 'extract', whiten: bool = False, noise_cov=None, verbose: bool | str | int | None = None, center: bool = True)[source]#

Denoising Source Separation transformer.

The estimator fits DSS filters from a baseline covariance and a biased covariance produced by bias. It accepts channel-first NumPy arrays and MNE Raw, Epochs, and Evoked objects.

Parameters:

biasLinearDenoiser or callable: Bias transformation applied before the biased covariance is estimated.
n_componentsint or None, default=None: Number of fitted components; None uses the available whitening rank.
n_selectint, {“auto”}, or None, default=None: Number of leading components used by retain or subtract. "auto" uses the package component-selection heuristics.
selection_thresholdfloat, default=3.0: Sigma threshold for automatic outlier selection.
knee_rel_floorfloat, default=0.01: Relative score floor for automatic knee selection.
knee_min_ratiofloat, default=3.0: Minimum score ratio for automatic knee selection.
rankint, dict, or None, default=None: Whitening rank.
regfloat, default=1e-9: Relative covariance-whitening regularization.
normalize_inputbool, default=True: Normalize each fitted channel by its L2 norm before the DSS covariance calculation and undo that scaling on sensor-space output.
cov_methodstr, default=”empirical”: Covariance method passed to the MNE or NumPy covariance path.
cov_kwsdict or None, default=None: Additional covariance-estimator keywords.
smoothLinearDenoiser, int, or None, default=None: Optional smooth branch to subtract before DSS. An integer is a smoothing window in samples.
adaptivebool, default=False: Fit independent segment operators in fit_transform. This mode supports only component_action="subtract".
segmenterCovarianceSegmenter, FixedWindowSegmenter, or None, default=None: Segmenter for adaptive processing. None uses a covariance segmenter.
crossfadefloat, default=0.0: Boundary cross-fade duration in seconds for adaptive processing.
max_prop_removefloat or None, default=None: Maximum fraction of channels selected per adaptive segment.
min_selectint, default=0: Minimum automatic selection count in adaptive processing.
component_action{“extract”, “retain”, “subtract”}, default=”extract”: Operation performed by transform().
whitenbool, default=False: Jointly whiten and decompose all selected MNE channel types.
noise_covmne.Covariance or None, default=None: Noise covariance for joint MNE whitening; ignored when whiten=False.
verbosebool, str, int, or None, default=None: Logging level.
centerbool, default=True: Fit one global channel mean and reuse it during transforms. False uses uncentered second moments.

Attributes:

filters_ndarray, shape (n_components, n_channels): Fitted spatial filters.
patterns_ndarray, shape (n_channels, n_components): Fitted spatial patterns.
eigenvalues_ndarray, shape (n_components,): Fitted DSS scores.
mean_ndarray, shape (n_channels, 1): Fitted channel mean, or zeros when center=False.
n_selected_int or None: Selected component count when automatic or explicit selection is active.
segment_results_list of dict or None: Per-segment results from adaptive fit_transform.

See also

compute_dss: Low-level covariance-based DSS decomposition.
IterativeDSS: Nonlinear iterative DSS.
TimeShiftDSS: Lag-augmented DSS for repeated trials.
mne_denoise.zapline.ZapLine: DSS-based line-noise removal.

Notes

NumPy input uses (n_channels, n_times) or (n_channels, n_times, n_epochs). MNE Epochs uses its native (n_epochs, n_channels, n_times) layout. extract returns source data; retain and subtract return the input layout or a copied MNE container [1].

References

Examples

>>> import numpy as np
>>> from mne_denoise.dss import BandpassBias, DSS
>>> rng = np.random.default_rng(0)
>>> data = rng.standard_normal((8, 2000))
>>> bias = BandpassBias(freq_band=(8.0, 12.0), sfreq=250.0)
>>> dss = DSS(bias=bias, n_components=3, component_action="extract")
>>> sources = dss.fit_transform(data)

auto_select(threshold: float | None = None) → int[source]#

Return the number of leading DSS components selected by the package heuristics.

Parameters:

thresholdfloat or None, default=None: Override the outlier sigma threshold.

Returns:

int: Selected component count.

Fit the DSS filters and fitted metadata.

Parameters:

Xmne.io.BaseRaw, mne.BaseEpochs, mne.Evoked, or ndarray: Training data. NumPy input is channel-first and may be 2D or 3D.
yNone, default=None: Ignored for scikit-learn compatibility.
weightsndarray or None, default=None: Non-negative observation weights for NumPy input.
verbosebool, str, int, or None, default=None: Logging level for this call.

Returns:

DSS: The fitted estimator.

fit_transform(X, y=None, *, callback=None, verbose: bool | str | int | None = None, **fit_params)[source]#

Fit DSS and apply the configured component operation.

In standard mode this composes fit() and transform(). In adaptive mode it performs transductive per-segment fitting and subtraction; adaptive mode requires component_action="subtract".

Parameters:

Xndarray or MNE object: Data used for fitting and transformation.
yNone, default=None: Ignored for scikit-learn compatibility.
callbackcallable or None, default=None: Synchronous progress callback for adaptive processing.
verbosebool, str, int, or None, default=None: Logging level for this call.
**fit_params: Additional keyword arguments passed to fit() in standard mode.

Returns:

ndarray or MNE object: Transformed data with the configured component-action semantics.

get_normalized_patterns() → ndarray[source]#

Get L2-normalized spatial patterns for visualization.

Returns:

patterns_normndarray, shape (n_channels, n_components): L2-normalized spatial patterns.

inverse_transform(sources: ndarray, component_indices: ndarray | None = None, *, verbose: bool | str | int | None = None) → ndarray[source]#

Reconstruct sensor-space data from DSS sources.

Parameters:

sourcesndarray, shape (n_components, n_times) or 3D: Sources returned by component_action="extract". NumPy epochs use channel-first layout; MNE Epochs source arrays use epoch-first layout.
component_indicesarray-like of int or bool, default=None: Components to include. None includes all supplied sources.
verbosebool, str, int, or None, default=None: Logging level for this call.

Returns:

ndarray: Reconstructed sensor-space data. The fitted global mean is not added.

Apply the configured DSS component operation.

Parameters:

Xmne.io.BaseRaw, mne.BaseEpochs, mne.Evoked, or ndarray: Data compatible with the fitted channel layout.
verbosebool, str, int, or None, default=None: Logging level for this call.

Returns:

ndarray or MNE object: extract returns source data. retain and subtract return a copy with the input array layout or MNE container type.