yasa.SleepStaging¶

class yasa.SleepStaging(raw, eeg_name, *, eog_name=None, emg_name=None, metadata=None)[source]¶

Automatic sleep staging of polysomnography data.

The automatic sleep staging requires the LightGBM and antropy packages.

New in version 0.4.0.

Parameters

rawmne.io.BaseRaw

An MNE Raw instance.

eeg_namestr

The name of the EEG channel in raw. Preferentially a central electrode referenced either to the mastoids (C4-M1, C3-M2) or to the Fpz electrode (C4-Fpz). Data are assumed to be in Volts (MNE default) and will be converted to uV.

eog_namestr or None

The name of the EOG channel in raw. Preferentially, the left LOC channel referenced either to the mastoid (e.g. E1-M2) or Fpz. Can also be None.

emg_namestr or None

The name of the EMG channel in raw. Preferentially a chin electrode. Can also be None.

metadatadict or None

A dictionary of metadata (optional). Currently supported keys are:

'age': age of the participant, in years.
'male': sex of the participant (1 or True = male, 0 or False = female)

Notes

If you use the SleepStaging module in a publication, please cite the following publication:

Vallat, R., & Walker, M. P. (2021). An open-source, high-performance tool for automated sleep staging. Elife, 10. doi: https://doi.org/10.7554/eLife.70092

We provide below some key points on the algorithm and its validation. For more details, we refer the reader to the peer-reviewed publication. If you have any questions, make sure to first check the FAQ section of the documentation. If you did not find the answer to your question, please feel free to open an issue on GitHub.

1. Features extraction

For each 30-seconds epoch and each channel, the following features are calculated:

Standard deviation
Interquartile range
Skewness and kurtosis
Number of zero crossings
Hjorth mobility and complexity
Absolute total power in the 0.4-30 Hz band.
Relative power in the main frequency bands (for EEG and EOG only)
Power ratios (e.g. delta / beta)
Permutation entropy
Higuchi and Petrosian fractal dimension

In addition, the algorithm also calculates a smoothed and normalized version of these features. Specifically, a 7.5 min centered triangular-weighted rolling average and a 2 min past rolling average are applied. The resulting smoothed features are then normalized using a robust z-score.

Important

The PSG data should be in micro-Volts. Do NOT transform (e.g. z-score) or filter the signal before running the sleep staging algorithm.

The data are automatically downsampled to 100 Hz for faster computation.

2. Sleep stages prediction

YASA comes with a default set of pre-trained classifiers, which were trained and validated on ~3000 nights from the National Sleep Research Resource. These nights involved participants from a wide age range, of different ethnicities, gender, and health status. The default classifiers should therefore works reasonably well on most data.

The code that was used to train the classifiers can be found on GitHub at: https://github.com/raphaelvallat/yasa_classifier

In addition with the predicted sleep stages, YASA can also return the predicted probabilities of each sleep stage at each epoch. This can be used to derive a confidence score at each epoch.

Important

The predictions should ALWAYS be double-check by a trained visual scorer, especially for epochs with low confidence. A full inspection should be performed in the following cases:

Nap data, because the classifiers were exclusively trained on full-night recordings.
Participants with sleep disorders.
Sub-optimal PSG system and/or referencing

Warning

N1 sleep is the sleep stage with the lowest detection accuracy. This is expected because N1 is also the stage with the lowest human inter-rater agreement. Be very careful for potential misclassification of N1 sleep (e.g. scored as Wake or N2) when inspecting the predicted sleep stages.

References

If you use YASA’s default classifiers, these are the main references for the National Sleep Research Resource:

Dean, Dennis A., et al. “Scaling up scientific discovery in sleep medicine: the National Sleep Research Resource.” Sleep 39.5 (2016): 1151-1164.
Zhang, Guo-Qiang, et al. “The National Sleep Research Resource: towards a sleep data commons.” Journal of the American Medical Informatics Association 25.10 (2018): 1351-1358.

Examples

For a concrete example, please refer to the example Jupyter notebook: https://github.com/raphaelvallat/yasa/blob/master/notebooks/14_automatic_sleep_staging.ipynb

>>> import mne
>>> import yasa
>>> # Load an EDF file using MNE
>>> raw = mne.io.read_raw_edf("myfile.edf", preload=True)
>>> # Initialize the sleep staging instance
>>> sls = yasa.SleepStaging(raw, eeg_name="C4-M1", eog_name="LOC-M2",
...                         emg_name="EMG1-EMG2",
...                         metadata=dict(age=29, male=True))
>>> # Get the predicted sleep stages
>>> hypno = sls.predict()
>>> # Get the predicted probabilities
>>> proba = sls.predict_proba()
>>> # Get the confidence
>>> confidence = proba.max(axis=1)
>>> # Plot the predicted probabilities
>>> sls.plot_predict_proba()

The sleep scores can then be manually edited in an external graphical user interface (e.g. EDFBrowser), as described in the FAQ.

__init__(raw, eeg_name, *, eog_name=None, emg_name=None, metadata=None)[source]¶

Methods

`__init__`(raw, eeg_name, *[, eog_name, ...])
`fit`()	Extract features from data.
`get_features`()	Extract features from data and return a copy of the dataframe.
`plot_predict_proba`([proba, majority_only, ...])	Plot the predicted probability for each sleep stage for each 30-sec epoch of data.
`predict`([path_to_model])	Return the predicted sleep stage for each 30-sec epoch of data.
`predict_proba`([path_to_model])	Return the predicted probability for each sleep stage for each 30-sec epoch of data.

fit()[source]¶

Extract features from data.

Returns

selfreturns an instance of self.

get_features()[source]¶

Extract features from data and return a copy of the dataframe.

Returns

featurespandas.DataFrame: Feature dataframe.

plot_predict_proba(proba=None, majority_only=False, palette=['#99d7f1', '#009DDC', 'xkcd:twilight blue', 'xkcd:rich purple', 'xkcd:sunflower'])[source]¶

Plot the predicted probability for each sleep stage for each 30-sec epoch of data.

Parameters

probaself or DataFrame: A dataframe with the probability of each sleep stage for each 30-sec epoch of data.
majority_onlyboolean: If True, probabilities of the non-majority classes will be set to 0.

predict(path_to_model='auto')[source]¶

Return the predicted sleep stage for each 30-sec epoch of data.

Currently, only classifiers that were trained using a LGBMClassifier are supported.

Parameters

path_to_modelstr or “auto”: Full path to a trained LGBMClassifier, exported as a joblib file. Can be “auto” to use YASA’s default classifier.

Returns

prednumpy.ndarray: The predicted sleep stages.

predict_proba(path_to_model='auto')[source]¶

Return the predicted probability for each sleep stage for each 30-sec epoch of data.

Currently, only classifiers that were trained using a LGBMClassifier are supported.

Parameters

path_to_modelstr or “auto”: Full path to a trained LGBMClassifier, exported as a joblib file. Can be “auto” to use YASA’s default classifier.

Returns

probapandas.DataFrame: The predicted probability for each sleep stage for each 30-sec epoch of data.