yasa.spindles_detect

yasa.spindles_detect(data, sf, hypno=None, include=(1, 2, 3), freq_sp=(12, 15), duration=(0.5, 2), freq_broad=(1, 30), min_distance=500, downsample=True, thresh={'corr': 0.65, 'rel_pow': 0.2, 'rms': 1.5}, remove_outliers=False, coupling=False, freq_so=(0.1, 1.25))[source]

Spindles 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 = N1 + 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 (1, 2, 3), meaning that the detection is applied on N1, N2 and N3 sleep. This has no effect when hypno is None.

freq_sptuple or list

Spindles frequency range. Default is 12 to 15 Hz. Please note that YASA uses a FIR filter (implemented in MNE) with a 1.5Hz transition band, which means that for freq_sp = (12, 15 Hz), the -6 dB points are located at 11.25 and 15.75 Hz.

durationtuple or list

The minimum and maximum duration of the spindles. Default is 0.5 to 2 seconds.

freq_broadtuple or list

Broad band frequency of interest. Default is 1 to 30 Hz.

min_distanceint

If two spindles are closer than min_distance (in ms), they are merged into a single spindles. Default is 500 ms.

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).

threshdict

Detection thresholds:

'rel_pow' : Relative power (= power ratio freq_sp / freq_broad).
'corr' : Pearson correlation coefficient.
'rms' : Mean(RMS) + 1.5 * STD(RMS).

You can disable one or more threshold by putting None instead:

thresh = {'rel_pow': None, 'corr': 0.65, 'rms': 1.5}
thresh = {'rel_pow': None, 'corr': None, 'rms': 3}
remove_outliersboolean

If True, YASA will automatically detect and remove outliers spindles using sklearn.ensemble.IsolationForest. The outliers detection is performed on all the spindles parameters with the exception of the Start, Peak, End, and SOPhase columns. 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 spindles in the first place. Default to False.

couplingboolean

If True, YASA will also calculate the coupling between each detected spindles and the slow-oscillation signal. The coupling is given by the phase (in radians) of the filtered slow-oscillation signal at the most prominent peak of the spindles.

Importantly, since the resulting variable is expressed in radians, one should use a circular mean to calculate the average across all events:

from scipy.stats import circmean
avg_SOPhase = circmean(sp['SOPhase'])

For more details, please refer to the Jupyter notebook

New in version 0.1.9.

freq_sotuple or list

Slow-oscillations frequency of interest. This is only relevant if coupling=True. Default is 0.1 to 1.25 Hz.

New in version 0.1.9.

Returns
sp_paramspandas.DataFrame

Ouput detection dataframe:

'Start' : Start time of each detected spindles (in seconds)
'Peak': Timing of the most prominent spindles peak (in seconds)
'End' : End time (in seconds)
'Duration' : Duration (in seconds)
'Amplitude' : Amplitude (in uV)
'RMS' : Root-mean-square (in uV)
'AbsPower' : Median absolute power (in log10 uV^2)
'RelPower' : Median relative power (ranging from 0 to 1, in % uV^2)
'Frequency' : Median frequency (in Hz)
'Oscillations' : Number of oscillations (peaks)
'Symmetry' : Symmetry index, ranging from 0 to 1
'SOPhase': SO phase (radians) at the most prominent spindle peak
'Stage' : Sleep stage (only if hypno was provided)

Notes

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

For an example on how to run the detection, please refer to https://github.com/raphaelvallat/yasa/blob/master/notebooks/01_spindles_detection.ipynb