mne.preprocessing.Xdawn

class mne.preprocessing.Xdawn(n_components=2, signal_cov=None, correct_overlap='auto', reg=None)

Implementation of the Xdawn Algorithm.

Xdawn [1][2] is a spatial filtering method designed to improve the signal to signal + noise ratio (SSNR) of the ERP responses. Xdawn was originally designed for P300 evoked potential by enhancing the target response with respect to the non-target response. This implementation is a generalization to any type of ERP.

Parameters:

n_componentsint, (default 2)

The number of components to decompose the signals.

signal_covNone | Covariance | ndarray, shape (n_channels, n_channels)

(default None). The signal covariance used for whitening of the data. if None, the covariance is estimated from the epochs signal.

correct_overlap‘auto’ or bool (default ‘auto’)

Compute the independent evoked responses per condition, while correcting for event overlaps if any. If ‘auto’, then overlapp_correction = True if the events do overlap.

regfloat | str | None (default None)

If not None (same as 'empirical', default), allow regularization for covariance estimation. If float, shrinkage is used (0 <= shrinkage <= 1). For str options, reg will be passed as method to mne.compute_covariance().

Attributes:

filters_dict of ndarray

If fit, the Xdawn components used to decompose the data for each event type, else empty. For each event type, the filters are in the rows of the corresponding array.

patterns_dict of ndarray

If fit, the Xdawn patterns used to restore the signals for each event type, else empty.

evokeds_dict of Evoked

If fit, the evoked response for each event type.

event_id_dict

The event id.

correct_overlap_bool

Whether overlap correction was applied.

Methods

apply(inst[, event_id, include, exclude])	Remove selected components from the signal.
fit(epochs[, y])	Fit Xdawn from epochs.
fit_transform(X[, y])	Fit to data, then transform it.
get_metadata_routing()	Get metadata routing of this object.
get_params([deep])	Get parameters for this estimator.
inverse_transform()	Not implemented, see Xdawn.apply() instead.
set_fit_request(*[, epochs])	Request metadata passed to the fit method.
set_output(*[, transform])	Set output container.
set_params(**params)	Set the parameters of this estimator.
set_transform_request(*[, inst])	Request metadata passed to the transform method.
transform(inst)	Apply Xdawn dim reduction.

See also

mne.decoding.CSP, mne.decoding.SPoC

Notes

New in v0.10.

References

[1]

Bertrand Rivet, Antoine Souloumiac, Virginie Attina, and Guillaume Gibert. xDAWN algorithm to enhance evoked potentials: application to brain–computer interface. IEEE Transactions on Biomedical Engineering, 56(8):2035–2043, 2009. doi:10.1109/TBME.2009.2012869.

[2]

Bertrand Rivet, Hubert Cecotti, Antoine Souloumiac, Emmanuel Maby, and Jérémie Mattout. Theoretical analysis of xDAWN algorithm: application to an efficient sensor selection in a P300 BCI. In Proceedings of EUSIPCO-2011, 1382–1386. Barcelona, 2011. IEEE. URL: https://ieeexplore.ieee.org/document/7073970.

apply(inst, event_id=None, include=None, exclude=None)

Remove selected components from the signal.

Given the unmixing matrix, transform data, zero out components, and inverse transform the data. This procedure will reconstruct the signals from which the dynamics described by the excluded components is subtracted.

Parameters:

instinstance of Raw | Epochs | Evoked

The data to be processed.

event_iddict | list of str | None (default None)

The kind of event to apply. if None, a dict of inst will be return one for each type of event xdawn has been fitted.

includearray_like of int | None (default None)

The indices referring to columns in the ummixing matrix. The components to be kept. If None, the first n_components (as defined in the Xdawn constructor) will be kept.

excludearray_like of int | None (default None)

The indices referring to columns in the ummixing matrix. The components to be zeroed out. If None, all the components except the first n_components will be exclude.

Returns:

outdict

A dict of instance (from the same type as inst input) for each event type in event_id.

fit(epochs, y=None)

Fit Xdawn from epochs.

Parameters:

epochsinstance of Epochs

An instance of Epoch on which Xdawn filters will be fitted.

yndarray | None (default None)

If None, used epochs.events[:, 2].

Returns:

selfinstance of Xdawn

The Xdawn instance.

fit_transform(X, y=None, **fit_params)

Fit to data, then transform it.

Fits transformer to X and y with optional parameters fit_params and returns a transformed version of X.

Parameters:

Xarray_like of shape (n_samples, n_features)

Input samples.

yarray_like of shape (n_samples,) or (n_samples, n_outputs), default=None

Target values (None for unsupervised transformations).

**fit_paramsdict

Additional fit parameters.

Returns:

X_newndarray array of shape (n_samples, n_features_new)

Transformed array.

get_metadata_routing()

Get metadata routing of this object.

Please check User Guide on how the routing mechanism works.

Returns:

routingMetadataRequest

A MetadataRequest encapsulating routing information.

get_params(deep=True)

Get parameters for this estimator.

Parameters:

deepbool, default=True

If True, will return the parameters for this estimator and contained subobjects that are estimators.

Returns:

paramsdict

Parameter names mapped to their values.

inverse_transform()

Not implemented, see Xdawn.apply() instead.

set_fit_request(*, epochs: bool | None | str = '$UNCHANGED$') → Xdawn

Request metadata passed to the fit method.

Note that this method is only relevant if enable_metadata_routing=True (see sklearn.set_config()). Please see User Guide on how the routing mechanism works.

The options for each parameter are:

• True: metadata is requested, and passed to fit if provided. The request is ignored if metadata is not provided.

• False: metadata is not requested and the meta-estimator will not pass it to fit.

• None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.

• str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

New in v1.3.

Note

This method is only relevant if this estimator is used as a sub-estimator of a meta-estimator, e.g. used inside a Pipeline. Otherwise it has no effect.

Parameters:

epochsstr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for epochs parameter in fit.

Returns:

selfobject

The updated object.

set_output(*, transform=None)

Set output container.

See Introducing the set_output API for an example on how to use the API.

Parameters:

transform{“default”, “pandas”, “polars”}, default=None

Configure output of transform and fit_transform.

• “default”: Default output format of a transformer

• “pandas”: DataFrame output

• “polars”: Polars output

• None: Transform configuration is unchanged

New in v1.4: “polars” option was added.

Returns:

selfestimator instance

Estimator instance.

set_params(**params)

Set the parameters of this estimator.

The method works on simple estimators as well as on nested objects (such as Pipeline). The latter have parameters of the form <component>__<parameter> so that it’s possible to update each component of a nested object.

Parameters:

**paramsdict

Estimator parameters.

Returns:

selfestimator instance

Estimator instance.

set_transform_request(*, inst: bool | None | str = '$UNCHANGED$') → Xdawn

Request metadata passed to the transform method.

Note that this method is only relevant if enable_metadata_routing=True (see sklearn.set_config()). Please see User Guide on how the routing mechanism works.

The options for each parameter are:

• True: metadata is requested, and passed to transform if provided. The request is ignored if metadata is not provided.

• False: metadata is not requested and the meta-estimator will not pass it to transform.

• None: metadata is not requested, and the meta-estimator will raise an error if the user provides it.

• str: metadata should be passed to the meta-estimator with this given alias instead of the original name.

The default (sklearn.utils.metadata_routing.UNCHANGED) retains the existing request. This allows you to change the request for some parameters and not others.

New in v1.3.

Note

This method is only relevant if this estimator is used as a sub-estimator of a meta-estimator, e.g. used inside a Pipeline. Otherwise it has no effect.

Parameters:

inststr, True, False, or None, default=sklearn.utils.metadata_routing.UNCHANGED

Metadata routing for inst parameter in transform.

Returns:

selfobject

The updated object.

transform(inst)

Apply Xdawn dim reduction.

Parameters:

instEpochs | Evoked | ndarray, shape ([n_epochs, ]n_channels, n_times)

Data on which Xdawn filters will be applied.

Returns:

Xndarray, shape ([n_epochs, ]n_components * n_event_types, n_times)

Spatially filtered signals.

Examples using mne.preprocessing.Xdawn

Decoding (MVPA)

Decoding (MVPA)

XDAWN Denoising

XDAWN Denoising

XDAWN Decoding From EEG data

XDAWN Decoding From EEG data