yasa.rem_detect

yasa.rem_detect(loc, roc, sf, hypno=None, include=4, amplitude=(50, 325), duration=(0.3, 1.2), relative_prominence=0.8, freq_rem=(0.5, 5), remove_outliers=False, verbose=False)[source]

Rapid eye movements (REMs) detection.

This detection requires both the left EOG (LOC) and right EOG (LOC). The units of the data must be uV. The algorithm is based on an amplitude thresholding of the negative product of the LOC and ROC filtered signal.

New in version 0.1.5.

Parameters
loc, rocarray_like

Continuous EOG data (Left and Right Ocular Canthi, LOC / ROC) channels. Unit must be uV.

Warning

The default unit of mne.io.BaseRaw is Volts. Therefore, if passing data from a mne.io.BaseRaw, make sure to use units=”uV” to get the data in micro-Volts, e.g.:

>>> data = raw.get_data(units="uV")  # Make sure that data is in uV
sffloat

Sampling frequency of the data, in Hz.

hypnoarray_like

Sleep stage (hypnogram). If the hypnogram is loaded, the detection will only be applied to the value defined in include (default = REM sleep).

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

Values in hypno that will be included in the mask. The default is (4), meaning that the detection is applied on REM sleep. This has no effect when hypno is None.

amplitudetuple or list

Minimum and maximum amplitude of the peak of the REM. Default is 50 uV to 325 uV.

durationtuple or list

The minimum and maximum duration of the REMs. Default is 0.3 to 1.2 seconds.

relative_prominencefloat

Relative prominence used to detect the peaks. The actual prominence is computed by multiplying relative prominence by the minimal amplitude. Default is 0.8.

freq_remtuple or list

Frequency range of REMs. Default is 0.5 to 5 Hz.

remove_outliersboolean

If True, YASA will automatically detect and remove outliers REMs using sklearn.ensemble.IsolationForest. YASA uses a random seed (42) to ensure reproducible results. Note that this step will only be applied if there are more than 50 detected REMs in the first place. Default to False.

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
remyasa.REMResults

To get the full detection dataframe, use:

>>> rem = rem_detect(...)
>>> rem.summary()

This will give a pandas.DataFrame where each row is a detected REM and each column is a parameter (= property). To get the average parameters sleep stage:

>>> rem.summary(grp_stage=True)

Notes

The parameters that are calculated for each REM are:

  • 'Start': Start of each detected REM, in seconds from the beginning of data.

  • 'Peak': Location of the peak (in seconds of data)

  • 'End': End time (in seconds)

  • 'Duration': Duration (in seconds)

  • 'LOCAbsValPeak': LOC absolute amplitude at REM peak (in uV)

  • 'ROCAbsValPeak': ROC absolute amplitude at REM peak (in uV)

  • 'LOCAbsRiseSlope': LOC absolute rise slope (in uV/s)

  • 'ROCAbsRiseSlope': ROC absolute rise slope (in uV/s)

  • 'LOCAbsFallSlope': LOC absolute fall slope (in uV/s)

  • 'ROCAbsFallSlope': ROC absolute fall slope (in uV/s)

  • 'Stage': Sleep stage (only if hypno was provided)

Note that all the output parameters are computed on the filtered LOC and ROC signals.

For better results, apply this detection only on artefact-free REM sleep.

References

The rapid eye movements detection algorithm is based on:

Examples

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