bycycle.features.compute_shape_features

bycycle.features.compute_shape_features(sig, fs, f_range, center_extrema='peak', find_extrema_kwargs=None, n_cycles=3)[source]

Compute shape features for each cycle.

Parameters:
sig1d array

Time series.

fsfloat

Sampling rate, in Hz.

f_rangetuple of (float, float)

Frequency range for narrowband signal of interest (Hz).

center_extrema{‘peak’, ‘trough’}

The center extrema in the cycle.

  • ‘peak’ : cycles are defined trough-to-trough

  • ‘trough’ : cycles are defined peak-to-peak

find_extrema_kwargsdict, optional, default: None

Keyword arguments for function to find peaks and troughs (find_extrema()) to change filter parameters or boundary. By default, the filter length is set to three cycles of the low cutoff frequency (f_range[0]).

n_cyclesint, optional, default: 3

Length of filter, in number of cycles, at the lower cutoff frequency.

Returns:
df_shape_featurespandas.DataFrame

Dataframe containing cycle shape features. Each row is one cycle. Columns:

  • period : period of the cycle

  • time_decay : time between peak and next trough

  • time_rise : time between peak and previous trough

  • time_peak : time between rise and decay zero-crosses

  • time_trough : duration of previous trough estimated by zero-crossings

  • volt_decay : voltage change between peak and next trough

  • volt_rise : voltage change between peak and previous trough

  • volt_amp : average of rise and decay voltage

  • volt_peak : voltage at the peak

  • volt_trough : voltage at the last trough

  • time_rdsym : fraction of cycle in the rise period

  • time_ptsym : fraction of cycle in the peak period

  • band_amp : average analytic amplitude of the oscillation

  • sample_peak : sample at which the peak occurs

  • sample_zerox_decay : sample of the decaying zero-crossing

  • sample_zerox_rise : sample of the rising zero-crossing

  • sample_last_trough : sample of the last trough

  • sample_next_trough : sample of the next trough

Notes

Peak vs trough centering:

  • By default, the first extrema analyzed will be a peak, and the final one a trough.

  • In order to switch the preference, the signal is simply inverted and columns are renamed.

  • Columns are slightly different dependent on center_extrema being ‘peak’ or ‘trough’.

Examples

Compute shape features:

>>> from neurodsp.sim import sim_bursty_oscillation
>>> fs = 500
>>> sig = sim_bursty_oscillation(10, fs, freq=10)
>>> df_shapes = compute_shape_features(sig, fs, f_range=(8, 12))