yasa.rem_detect

yasa.rem_detect(loc, roc, sf, hypno=None, include=4, amplitude=(50, 325), duration=(0.3, 1.2), freq_rem=(0.5, 5), downsample=True, remove_outliers=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, you need to multiply the data by 1e6 to convert to micro-Volts (1 V = 1,000,000 uV), e.g.:

data = raw.get_data() * 1e6  # Make sure that data is in uV
sffloat

Sampling frequency of the data, in Hz.

hypnoarray_like

Sleep stage vector (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:

  • -1 = Artefact / Movement

  • 0 = Wake

  • 1 = N1 sleep

  • 2 = N2 sleep

  • 3 = N3 sleep

  • 4 = REM

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.

freq_remtuple or list

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

downsampleboolean

If True, the data will be downsampled to 100 Hz or 128 Hz (depending on whether the original sampling frequency is a multiple of 100 or 128, respectively).

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 100 detected REMs in the first place. Default to False.

Returns
df_rempandas.DataFrame

Ouput detection dataframe:

'Start' : Start of each detected REM (in seconds 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)

Notes

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

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

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