yasa.art_detect

yasa.art_detect(data, sf=None, window=5, hypno=None, include=(1, 2, 3, 4), method='covar', threshold=3, n_chan_reject=1, verbose=False)[source]

Automatic artifact rejection.

New in version 0.2.0.

Parameters
dataarray_like

Single or multi-channel EEG data. Unit must be uV and shape (n_chan, n_samples). Can also be a mne.io.BaseRaw, in which case data and sf will be automatically extracted, and data will also be automatically converted from Volts (MNE) to micro-Volts (YASA).

Warning

data must only contains EEG channels. Please make sure to exclude any EOG, EKG or EMG channels.

sffloat

Sampling frequency of the data in Hz. Can be omitted if data is a mne.io.BaseRaw object.

windowfloat

The window length (= resolution) for artifact rejection, in seconds. Default to 5 seconds. Shorter windows (e.g. 1 or 2-seconds) will drastically increase computation time when method='covar'.

hypnoarray_like

Sleep stage (hypnogram). If the hypnogram is passed, the detection will be applied separately for each of the stages defined in include.

The hypnogram must have the same number of samples as data. To upsample your hypnogram, please refer to yasa.hypno_upsample_to_data().

Note

The default hypnogram format in YASA is a 1D integer vector where:

  • -2 = Unscored

  • -1 = Artefact / Movement

  • 0 = Wake

  • 1 = N1 sleep

  • 2 = N2 sleep

  • 3 = N3 sleep

  • 4 = REM sleep

includetuple, list or int

Sleep stages in hypno on which to perform the artifact rejection. The default is hypno=(1, 2, 3, 4), meaning that the artifact rejection is applied separately for all sleep stages, excluding wake. This parameter has no effect when hypno is None.

methodstr

Artifact detection method (see Notes):

  • 'covar' : Covariance-based, default for 4+ channels data

  • 'std' : Standard-deviation-based, default for single-channel data

thresholdfloat

The number of standard deviations above or below which an epoch is considered an artifact. Higher values will result in a more conservative detection, i.e. less rejected epochs.

n_chan_rejectint

The number of channels that must be below or above threshold on any given epochs to consider this epoch as an artefact when method='std'. The default is 1, which means that the epoch will be marked as artifact as soon as one channel is above or below the threshold. This may be too conservative when working with a large number of channels (e.g.hdEEG) in which case users can increase n_chan_reject. Note that this parameter only has an effect when method='std'.

verbosebool or str

Verbose level. Default (False) will only print warning and error messages. The logging levels are ‘debug’, ‘info’, ‘warning’, ‘error’, and ‘critical’. For most users the choice is between ‘info’ (or verbose=True) and warning (verbose=False).

New in version 0.2.0.

Returns
art_epochsarray_like

1-D array of shape (n_epochs) where 1 = Artefact and 0 = Good.

zscoresarray_like

Array of z-scores, shape is (n_epochs) if method='covar' and (n_epochs, n_chan) if method='std'.

Notes

Caution

This function will only detect major body artefacts present on the EEG channel. It will not detect EKG contamination or eye blinks. For more artifact rejection tools, please refer to the MNE Python package.

Tip

For best performance, apply this function on pre-staged data and make sure to pass the hypnogram. Sleep stages have very different EEG signatures and the artifect rejection will be much more accurate when applied separately on each sleep stage.

We provide below a short description of the different methods. For multi-channel data, and if computation time is not an issue, we recommend using method='covar' which uses a clustering approach on variance-covariance matrices, and therefore takes into account not only the variance in each channel and each epoch, but also the inter-relationship (covariance) between channel.

method='covar' is however not supported for single-channel EEG or when less than 4 channels are present in data. In these cases, one can use the much faster method='std' which is simply based on a z-scoring of the log-transformed standard deviation of each channel and each epoch.

1/ Covariance-based multi-channel artefact rejection

method='covar' is essentially a wrapper around the pyriemann.clustering.Potato class implemented in the pyRiemann package.

The main idea of this approach is to estimate a reference covariance matrix \(\bar{C}\) (for each sleep stage separately if hypno is present) and reject every epoch which is too far from this reference matrix. The distance of the covariance matrix of the current epoch \(C\) from the reference matrix is calculated using Riemannian geometry, which is more adapted than Euclidean geometry for symmetric positive definite covariance matrices:

\[d = {\left( \sum_i \log(\lambda_i)^2 \right)}^{-1/2}\]

where \(\lambda_i\) are the joint eigenvalues of \(C\) and \(\bar{C}\). The epoch with covariance matric \(C\) will be marked as an artifact if the distance \(d\) is greater than a threshold \(T\) (typically 2 or 3 standard deviations). \(\bar{C}\) is iteratively estimated using a clustering approach.

2/ Standard-deviation-based single and multi-channel artefact rejection

method='std' is a much faster and straightforward approach which is simply based on the distribution of the standard deviations of each epoch. Specifically, one first calculate the standard deviations of each epoch and each channel. Then, the resulting array of standard deviations is log-transformed and z-scored (for each sleep stage separately if hypno is present). Any epoch with one or more channel exceeding the threshold will be marked as artifact.

Note that this approach is more sensitive to noise and/or the influence of one bad channel (e.g. electrode fell off at some point during the night). We therefore recommend that you visually inspect and remove any bad channels prior to using this function.

References

Examples

For an example of how to run the detection, please refer to https://github.com/raphaelvallat/yasa/blob/master/notebooks/13_artifact_rejection.ipynb