wonambi.detect.spindle module

Module to detect spindles.

class wonambi.detect.spindle.DetectSpindle(method='Moelle2011', frequency=None, duration=None, merge=False)

Bases: object

Design spindle detection on a single channel.

Parameters:

• method (str) – one of the predefined methods

• frequency (tuple of float) – low and high frequency of spindle band

• duration (tuple of float) – min and max duration of spindles

• merge (bool) – if True, then after events are detected on every channel, events on different channels that are separated by less than min_interval will be merged into a single event, with ‘chan’ = the chan of the earlier-onset event.

tolerance

during detection and prior to applying the duration criterion, candidate events separated by less than this time interval are merged. In this way, the detector becomes tolerant to short dips below the eligibility threshold (e.g. if the spindle power drops for a split second).

Type:

float

min_interval

after the duration criterion is applied, events separated by less than this interval are merged into a single event, with ‘chan’ = the chan of the earlier-onset event.

Type:

float

power_peaks

for peak power statistics. ‘peak’ or ‘interval’. If None, values will all be NaN

Type:

str or None

Notes

See individual detect_* functions for other attribute descriptions.

wonambi.detect.spindle.define_threshold(dat, s_freq, method, value, nbins=120)

Return the value of the threshold based on relative values.

Parameters:

• dat (ndarray (dtype='float')) – vector with the data after selection-transformation

• s_freq (float) – sampling frequency

• method (str) – one of ‘mean’, ‘median’, ‘std’, ‘mean+std’, ‘median+std’, ‘histmax’

• value (float) – value to multiply the values for

• nbins (int) – for histmax method only, number of bins in the histogram

Returns:

float – threshold in useful units.

wonambi.detect.spindle.detect_Concordia(dat_orig, s_freq, time, opts)

Spindle detection, experimental Concordia method. Similar to Moelle 2011 and Nir2011.

Parameters:

• dat_orig (ndarray (dtype='float')) – vector with the data for one channel

• s_freq (float) – sampling frequency

• opts (instance of 'DetectSpindle') –

  ‘det_butter’dict

  parameters for ‘butter’,

  ’moving_rms’dict

  parameters for ‘moving_rms’

  ’smooth’dict

  parameters for ‘smooth’

  ’det_thresh’float

  low detection threshold

  ’det_thresh_hi’float

  high detection threshold

  ’sel_thresh’float

  selection threshold

Returns:

• list of dict – list of detected spindles

• dict – ‘det_value_lo’, ‘det_value_hi’ with detection values, ‘sel_value’ with selection value

• float – spindle density, per 30-s epoch

wonambi.detect.spindle.detect_FASST(dat_orig, s_freq, time, opts, submethod='rms')

Spindle detection based on FASST method, itself based on Moelle et al. (2002).

Parameters:

• dat_orig (ndarray (dtype='float')) – vector with the data for one channel

• s_freq (float) – sampling frequency

• time (ndarray (dtype='float')) – vector with the time points for each sample

• opts (instance of 'DetectSpindle') –

  ‘det_butter’dict

  parameters for ‘butter’,

  ’moving_rms’dict

  parameters for ‘moving_rms’

  ’smooth’dict

  parameters for ‘smooth’

  ’det_thresh’float

  detection threshold (percentile)

• submethod (str) – ‘abs’ (rectified) or ‘rms’ (root-mean-square)

Returns:

• list of dict – list of detected spindles

• dict – ‘det_value_lo’ with detection value, ‘det_value_hi’ with nan, ‘sel_value’ with nan

• float – spindle density, per 30-s epoch

References

Leclercq, Y. et al. Compu. Intel. and Neurosci. (2011).

wonambi.detect.spindle.detect_Ferrarelli2007(dat_orig, s_freq, time, opts)

Spindle detection based on Ferrarelli et al. 2007, and scripts obtained from Warby et al. (2014).

Parameters:

• dat_orig (ndarray (dtype='float')) – vector with the data for one channel

• s_freq (float) – sampling frequency

• time (ndarray (dtype='float')) – vector with the time points for each sample

• opts (instance of 'DetectSpindle') –

  ‘det_remez’dict

  parameters for ‘remez’,

  ’det_thresh’float

  detection threshold

  ’sel_thresh’float

  selection threshold

Returns:

• list of dict – list of detected spindles

• dict – ‘det_value_lo’ with detection value, ‘det_value_hi’ with nan, ‘sel_value’ with selection value

• float – spindle density, per 30-s epoch

References

Ferrarelli, F. et al. Am. J. Psychiatry 164, 483-92 (2007). Warby, S. C. et al. Nat. Meth. 11(4), 385-92 (2014).

wonambi.detect.spindle.detect_Lacourse2018(dat_orig, s_freq, time, opts)

Spindle detection based on Lacourse et al., 2018

Parameters:

• dat_orig (ndarray (dtype='float')) – vector with the data for one channel

• s_freq (float) – sampling frequency

• time (ndarray (dtype='float')) – vector with the time points for each sample

• opts (instance of 'DetectSpindle') –

  ‘det_butter’dict

  parameters for ‘butter’,

  ’det_butter2’dict

  parameters for ‘butter’,

  ’windowing’ :

  ’step’ for downsampling and ‘dur’ for moving window duration

  ’moving_ms’dict

  parameters for ‘moving_rms’

  ’moving_power_ratio’ :

  parameters for ‘moving_power_ratio’

  ’zscore’ :

  parameters for ‘moving_zscore’

  ’moving_covar’ :

  parameters for ‘moving_covar’

  ’moving_sd’ :

  parameters for ‘moving_sd’

  ’smooth’dict

  parameters for ‘smooth’

  ’abs_pow_thresh’float

  absolute power threshold

  ’rel_pow_thresh’float

  relative power threshold

  ’covar_thresh’float

  covariance threshold

  ’corr_thresh’float

  coorelation threshold

Returns:

• list of dict – list of detected spindles

• dict – ‘det_value_lo’ with detection value, ‘det_value_hi’ is nan, ‘sel_value’ is nan (for consistency with other methods)

• float – spindle density, per 30-s epoch

References

Lacourse, K. et al. J. Neurosci. Meth. (2018).

wonambi.detect.spindle.detect_Martin2013(dat_orig, s_freq, time, opts)

Spindle detection based on Martin et al. 2013

Parameters:

• dat_orig (ndarray (dtype='float')) – vector with the data for one channel

• s_freq (float) – sampling frequency

• time (ndarray (dtype='float')) – vector with the time points for each sample

• opts (instance of 'DetectSpindle') –

  ‘det_remez’dict

  parameters for ‘remez’ filter

  ’moving_rms’dict

  parameters for ‘moving_rms’

  ’det_thresh’float

  percentile for detection threshold

Returns:

• list of dict – list of detected spindles

• dict – ‘det_value_lo’ with detection value, ‘det_value_hi’ is nan, ‘sel_value’ is nan (for consistency with other methods)

• float – spindle density, per 30-s epoch

References

Martin, N. et al. Neurobio Aging 34(2), 468-76 (2013).

wonambi.detect.spindle.detect_Moelle2011(dat_orig, s_freq, time, opts)

Spindle detection based on Moelle et al. 2011

Parameters:

• dat_orig (ndarray (dtype='float')) – vector with the data for one channel

• s_freq (float) – sampling frequency

• time (ndarray (dtype='float')) – vector with the time points for each sample

• opts (instance of 'DetectSpindle') –

  ‘det_remez’dict

  parameters for ‘remez’,

  ’moving_rms’dict

  parameters for ‘moving_rms’

  ’smooth’dict

  parameters for ‘smooth’

  ’det_thresh’float

  detection threshold

Returns:

• list of dict – list of detected spindles

• dict – ‘det_value_lo’ with detection value, ‘det_value_hi’ with nan, ‘sel_value’ with nan

• float – spindle density, per 30-s epoch

References

Moelle, M. et al. J. Neurosci. 22(24), 10941-7 (2002).

wonambi.detect.spindle.detect_Nir2011(dat_orig, s_freq, time, opts)

Spindle detection based on Nir et al. 2011

Parameters:

• dat_orig (ndarray (dtype='float')) – vector with the data for one channel

• s_freq (float) – sampling frequency

• time (ndarray (dtype='float')) – vector with the time points for each sample

• opts (instance of 'DetectSpindle') –

  ‘det_butter’dict

  parameters for ‘butter’,

  ’smooth’dict

  parameters for ‘gaussian’

  ’det_thresh’float

  detection threshold

  ’sel_thresh’float

  selection threshold

Returns:

• list of dict – list of detected spindles

• dict – ‘det_value_lo’ with detection value, ‘det_value_hi’ with nan, ‘sel_value’ with selection value

• float – spindle density, per 30-s epoch

Notes

This paper also selects channels carefully: ‘First, the channels with spindle activity in NREM sleep were chosen for further analysis.’

‘Third, those channels, in which an increase in spectral power within the detected events was restricted to the spindle-frequency range (10-16 Hz) rather than broadband.’

References

Nir, Y. et al. Neuron 70, 153-69 (2011).

wonambi.detect.spindle.detect_Ray2015(dat_orig, s_freq, time, opts)

Spindle detection based on Ray et al., 2015

Parameters:

• dat_orig (ndarray (dtype='float')) – vector with the data for one channel

• s_freq (float) – sampling frequency

• time (ndarray (dtype='float')) – vector with the time points for each sample

• opts (instance of 'DetectSpindle') –

  ‘cdemod’dict

  parameters for ‘cdemod’ (complex demodulation)

  ’det_butter’dict

  parameters for ‘butter’,

  ’det_low_butter’dict

  parameters for ‘low_butter’,

  ’smooth’dict

  parameters for ‘smooth’

  ’zscore’dict

  parameters for ‘moving_zscore’

  ’det_thresh’float

  detection threshold

  ’sel_thresh’nan

  selection threshold

Returns:

• list of dict – list of detected spindles

• dict – ‘det_value_lo’ with detection value, ‘det_value_hi’ is nan, ‘sel_value’ is nan (for consistency with other methods)

• float – spindle density, per 30-s epoch

References

Ray, L. B. et al. Front. Hum. Neurosci. 9-16 (2015).

wonambi.detect.spindle.detect_UCSD(dat_orig, s_freq, time, opts)

Spindle detection based on the UCSD method

Parameters:

• dat_orig (ndarray (dtype='float')) – vector with the data for one channel

• s_freq (float) – sampling frequency

• time (ndarray (dtype='float')) – vector with the time points for each sample

• opts (instance of 'DetectSpindle') –

  det_waveletdict

  parameters for ‘wavelet_real’,

  det_thres’float

  detection threshold

  sel_waveletdict

  parameters for ‘wavelet_real’

  sel_threshfloat

  selection threshold

  ratio_threshfloat

  ratio between power inside and outside spindle band to accept them

Returns:

• list of dict – list of detected spindles

• dict – ‘det_value_lo’ with detection value, ‘det_value_hi’ with nan, ‘sel_value’ with selection value

• float – spindle density, per 30-s epoch

wonambi.detect.spindle.detect_Wamsley2012(dat_orig, s_freq, time, opts)

Spindle detection based on Wamsley et al. 2012

Parameters:

• dat_orig (ndarray (dtype='float')) – vector with the data for one channel

• s_freq (float) – sampling frequency

• time (ndarray (dtype='float')) – vector with the time points for each sample

• opts (instance of 'DetectSpindle') –

  ‘det_wavelet’dict

  parameters for ‘morlet’,

  ’smooth’dict

  parameters for ‘smooth’

  ’det_thresh’float

  detection threshold

Returns:

• list of dict – list of detected spindles

• dict – ‘det_value_lo’ with detection value, ‘det_value_hi’ is nan, ‘sel_value’ is nan (for consistency with other methods)

• float – spindle density, per 30-s epoch

References

Wamsley, E. J. et al. Biol. Psychiatry 71, 154-61 (2012).

wonambi.detect.spindle.detect_events(dat, method, value=None)

Detect events using ‘above_thresh’, ‘below_thresh’ or ‘maxima’ method.

Parameters:

• dat (ndarray (dtype='float')) – vector with the data after transformation

• method (str) – ‘above_thresh’, ‘below_thresh’ or ‘maxima’

• value (float or tuple of float) – for ‘above_thresh’ or ‘below_thresh’, it’s the value of threshold for the event detection for ‘between_thresh’, it’s the lower and upper threshold as tuple for ‘maxima’, it’s the distance in s from the peak to find a minimum

Returns:

ndarray (dtype=’int’) – N x 3 matrix with start, peak, end samples

wonambi.detect.spindle.make_spindles(events, power_peaks, powers, dat_det, dat_orig, time, s_freq)

Create dict for each spindle, based on events of time points.

Parameters:

• events (ndarray (dtype='int')) – N x 3 matrix with start, peak, end samples, and peak frequency

• power_peaks (ndarray (dtype='float')) – peak in power spectrum for each event

• powers (ndarray (dtype='float')) – average power in power spectrum for each event

• dat_det (ndarray (dtype='float')) – vector with the data after detection-transformation (to compute peak)

• dat_orig (ndarray (dtype='float')) – vector with the raw data on which detection was performed

• time (ndarray (dtype='float')) – vector with time points

• s_freq (float) – sampling frequency

Returns:

list of dict – list of all the spindles, with information about start_time, peak_time, end_time (s), peak_val (signal units), area_under_curve (signal units * s), peak_freq (Hz)

wonambi.detect.spindle.merge_close(events, min_interval, merge_to_longer=False)

Merge events that are separated by a less than a minimum interval.

Parameters:

• events (list of dict) – events with ‘start’ and ‘end’ times, from one or several channels. Events must be sorted by their start time.

• min_interval (float) – minimum delay between consecutive events, in seconds

• merge_to_longer (bool (default: False)) – If True, info (chan, peak, etc.) from the longer of the 2 events is kept. Otherwise, info from the earlier onset spindle is kept.

Returns:

list of dict – original events list with close events merged.

wonambi.detect.spindle.peak_in_power(events, dat, s_freq, method, value=None)

Define peak in power of the signal.

Parameters:

• events (ndarray (dtype='int')) – N x 3 matrix with start, peak, end samples

• dat (ndarray (dtype='float')) – vector with the original data

• s_freq (float) – sampling frequency

• method (str or None) – ‘peak’ or ‘interval’. If None, values will be all NaN

• value (float) – size of the window around peak, or nothing (for ‘interval’)

Returns:

ndarray (dtype=’float’) – vector with peak frequency

wonambi.detect.spindle.peaks_in_time(dat, troughs=False)

Find indices of peaks or troughs in data.

Parameters:

• dat (ndarray (dtype='float')) – vector with the data

• troughs (bool) – if True, will return indices of troughs instead of peaks

Returns:

nadarray of int – indices of peaks (or troughs) in dat

Note

This function does not deal well with flat signal; when the signal is not increasing, it is assumed to be descreasing. As a result, this function finds troughs where the signal begins to increase after either decreasing or remaining constant

wonambi.detect.spindle.power_in_band(events, dat, s_freq, frequency)

Define power of the signal within frequency band.

Parameters:

• events (ndarray (dtype='int')) – N x 3 matrix with start, peak, end samples

• dat (ndarray (dtype='float')) – vector with the original data

• s_freq (float) – sampling frequency

• frequency (tuple of float) – low and high frequency of spindle band, for window

Returns:

ndarray (dtype=’float’) – vector with power

wonambi.detect.spindle.power_ratio(events, dat, s_freq, limits, ratio_thresh)

Estimate the ratio in power between spindle band and lower frequencies.

Parameters:

• events (ndarray (dtype='int')) – N x 3 matrix with start, peak, end samples

• dat (ndarray (dtype='float')) – vector with the original data

• s_freq (float) – sampling frequency

• limits (tuple of float) – high and low frequencies for spindle band

• ratio_thresh (float) – ratio between spindle vs non-spindle amplitude

Returns:

ndarray (dtype=’int’) – N x 3 matrix with start, peak, end samples

Notes

In the original matlab script, it uses amplitude, not power.

wonambi.detect.spindle.remove_straddlers(events, time, s_freq, tolerance=0.1)

Reject an event if it straddles a stitch, by comparing its duration to its timespan.

Parameters:

• events (ndarray (dtype='int')) – N x M matrix with start, …, end samples

• time (ndarray (dtype='float')) – vector with time points

• s_freq (float) – sampling frequency

• tolerance (float, def=0.1) – maximum tolerated difference between event duration and timespan

Returns:

ndarray (dtype=’int’) – N x M matrix with start , …, end samples

wonambi.detect.spindle.select_events(dat, detected, method, value)

Select start sample and end sample of the events.

Parameters:

• dat (ndarray (dtype='float')) – vector with the data after selection-transformation

• detected (ndarray (dtype='int')) – N x 3 matrix with start, peak, end samples

• method (str) – ‘above_thresh’, ‘below_thresh’, ‘below_thresh_positive’

• value (float) – for ‘threshold’, it’s the value of threshold for the spindle selection.

Returns:

ndarray (dtype=’int’) – N x 3 matrix with start, peak, end samples

wonambi.detect.spindle.transform_signal(dat, s_freq, method, method_opt=None, dat2=None)

Transform the data using different methods.

Parameters:

• dat (ndarray (dtype='float')) – vector with all the data for one channel

• s_freq (float) – sampling frequency

• method (str) – one of ‘abs’, ‘abs_complex’, ‘butter’, ‘cdemod’, ‘cheby2’, ‘double_butter’, ‘double_sosbutter’, ‘gaussian’, ‘hilbert’, ‘high_butter’, ‘low_butter’, ‘morlet’, ‘moving_covar’, ‘moving_ms’, ‘moving_periodogram’, ‘moving_power_ratio’, ‘moving_rms’, ‘moving_sd’, ‘moving_zscore’, ‘remez’, ‘smooth’, ‘sosbutter’, ‘spectrogram’, ‘wavelet_real’.

• method_opt (dict) – depends on methods

• dat2 (ndarray(dtype='float')) – second vector with data

Returns:

ndarray (dtype=’float’) – vector with all the data for one channel

Notes

double_butter implements an effective bandpass by applying a highpass, followed by a lowpass. This method reduces filter instability, due to underlying numerical instability arising from nyquist / freq at low freq.

Wavelets pass only absolute values already, it does not make sense to store the complex values.

butter has parameters:

freqtuple of float

low and high values for bandpass

orderint

filter order (will be effecively doubled by filtfilt)

cdemod has parameters:

freqfloat

carrier frequency for complex demodulation

cheby2 has parameters:

freqtuple of float

low and high values for bandpass

orderint

filter order (will be effecively doubled by filtfilt)

double_butter has parameters:

freqtuple of float

low and high values for highpass, then lowpass

orderint

filter order (will be effecively doubled by filtfilt)

double_sosbutter has parameters:

freqtuple of float

low and high values for highpass, then lowpass

orderint

filter order (will be effecively doubled by filtfilt)

gaussian has parameters:

durfloat

standard deviation of the Gaussian kernel, aka sigma (sec)

high_butter has parameters:

freqfloat

Highpass (lowcut) frequency, in Hz

orderint

filter order (will be effecively doubled by filtfilt)

low_butter has parameters:

freqfloat

Lowpass (highcut) frequency, in Hz

orderint

filter order (will be effecively doubled by filtfilt)

morlet has parameters:

f0float

center frequency in Hz

sdfloat

standard deviation of frequency

durfloat

window length in number of standard deviations

moving_covar has parameters:

durfloat

duration of the window (sec)

step: float

step between consecutive windows (sec)

moving_ms has parameters:

durfloat

duration of the window (sec)

step: float

step between consecutive windows (sec)

moving_periodogram has parameters:

durfloat

duration of the z-score sliding window (sec)

freqtuple of float

frequency range for periodogram (Hz)

step: float

step between consecutive windows (sec)

moving_power_ratio has parameters:

durfloat

duration of the z-score sliding window (sec)

freq_narrowtuple of float

frequency range for the narrowband power (Hz)

freq_broadtuple of float

frequency range for the broadband power (Hz)

fft_durfloat

duration of the FFT window (sec)

step: float

step between consecutive windows (sec)

moving_rms has parameters:

durfloat

duration of the window (sec)

step: float

step between consecutive windows (sec)

moving_sd has parameters:

durfloat

duration of the z-score sliding window (sec)

step: float

step between consecutive windows (sec)

moving_zscore has parameters:

durfloat

duration of the z-score sliding window (sec)

pcl_rangetuple of float, or None

if not None, only data within this percentile range will be used for determining the standard deviation for calculation of the z-score

step: float

step between consecutive windows (sec)

remez has parameters:

freqtuple of float

low and high values for bandpass

rollofffloat

bandwidth, in hertz, between stop and pass frequencies

durfloat

dur * s_freq = N, where N is the filter order, a.k.a number of taps

smooth has parameters:

durfloat

duration of the convolution window (sec). For ‘triangle’, base of isosceles triangle.

wavelet_real has parameters:

freqsndarray

vector of wavelet frequencies for spindle detection

durfloat

duration of the wavelet (sec)

widthfloat

wavelet width

winfloat

moving average window length (sec) of wavelet convolution

wonambi.detect.spindle.within_duration(events, time, limits)

Check whether event is within time limits.

Parameters:

• events (ndarray (dtype='int')) – N x M matrix with start sample first and end samples last on M

• time (ndarray (dtype='float')) – vector with time points

• limits (tuple of float) – low and high limit for spindle duration

Returns:

ndarray (dtype=’int’) – N x M matrix with start sample first and end samples last on M