yasa.sw_detect

yasa.sw_detect(data, sf, hypno=None, include=(2, 3), freq_sw=(0.3, 3.5), dur_neg=(0.3, 1.5), dur_pos=(0.1, 1), amp_neg=(40, 300), amp_pos=(10, 200), amp_ptp=(75, 500), downsample=True, remove_outliers=False)[source]

Slow-waves detection.

Parameters
dataarray_like

Single-channel continuous EEG data. 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 = N2 + N3 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 sleep

includetuple, list or int

Values in hypno that will be included in the mask. The default is (2, 3), meaning that the detection is applied on N2 and N3 sleep. This has no effect when hypno is None.

freq_swtuple or list

Slow wave frequency range. Default is 0.3 to 3.5 Hz. Please note that YASA uses a FIR filter (implemented in MNE) with a 0.2Hz transition band, which means that for freq_sw = (.3, 3.5 Hz), the -6 dB points are located at 0.2 and 3.6 Hz.

dur_negtuple or list

The minimum and maximum duration of the negative deflection of the slow wave. Default is 0.3 to 1.5 second.

dur_postuple or list

The minimum and maximum duration of the positive deflection of the slow wave. Default is 0.1 to 1 second.

amp_negtuple or list

Absolute minimum and maximum negative trough amplitude of the slow-wave. Default is 40 uV to 300 uV.

amp_postuple or list

Absolute minimum and maximum positive peak amplitude of the slow-wave. Default is 10 uV to 200 uV.

amp_ptptuple or list

Minimum and maximum peak-to-peak amplitude of the slow-wave. Default is 75 uV to 500 uV.

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 slow-waves using sklearn.ensemble.IsolationForest. The outliers detection is performed on the frequency, amplitude and duration parameters of the detected slow-waves. 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 slow-waves in the first place. Default to False.

Returns
sw_paramspandas.DataFrame

Ouput detection dataframe:

'Start' : Start of each detected slow-wave (in seconds of data)
'NegPeak' : Location of the negative peak (in seconds of data)
'MidCrossing' : Location of the negative-to-positive zero-crossing
'Pospeak' : Location of the positive peak
'End' : End time (in seconds)
'Duration' : Duration (in seconds)
'ValNegPeak' : Amplitude of the negative peak (in uV - filtered)
'ValPosPeak' : Amplitude of the positive peak (in uV - filtered)
'PTP' : Peak to peak amplitude (ValPosPeak - ValNegPeak)
'Slope' : Slope between ``NegPeak`` and ``MidCrossing`` (in uV/sec)
'Frequency' : Frequency of the slow-wave (1 / ``Duration``)
'Stage' : Sleep stage (only if hypno was provided)

Notes

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

Note that the PTP, Slope, ValNegPeak and ValPosPeak are all computed on the filtered signal.

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