yasa.SleepStaging

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

Automatic sleep staging of polysomnography data.

To run the automatic sleep staging, you must install 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 preprint:

We provide below some key points on the algorithm and its validation. For more details, we refer the reader to the preprint article. 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.

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 in turn 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__(self, raw, eeg_name, *, eog_name=None, emg_name=None, metadata=None)[source]

Initialize self. See help(type(self)) for accurate signature.

Methods

__init__(self, raw, eeg_name, *[, eog_name, …])

Initialize self.

fit(self)

Extract features from data.

get_features(self)

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

plot_predict_proba(self[, proba, …])

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

predict(self[, path_to_model])

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

predict_proba(self[, path_to_model])

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

fit(self)[source]

Extract features from data.

Returns
selfreturns an instance of self.
get_features(self)[source]

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

Returns
featurespandas.DataFrame

Feature dataframe.

plot_predict_proba(self, 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(self, 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(self, 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.