bycycle.features.compute_features

bycycle.features.compute_features(sig, fs, f_range, center_extrema='peak', burst_method='cycles', burst_kwargs=None, threshold_kwargs=None, find_extrema_kwargs=None, return_samples=True)

Compute shape and burst 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

burst_method{‘cycles’, ‘amp’}

Method for detecting bursts.

• ‘cycles’: detect bursts based on the consistency of consecutive periods & amplitudes

• ‘amp’: detect bursts using an amplitude threshold

burst_kwargsdict, optional, default: None

Additional keyword arguments defined in compute_burst_fraction() for dual amplitude threshold burst detection (i.e. when burst_method=’amp’).

threshold_kwargsdict, optional, default: None

Feature thresholds for cycles to be considered bursts, matching keyword arguments for:

• detect_bursts_cycles() for consistency burst detection (i.e. when burst_method=’cycles’)

• detect_bursts_amp() for amplitude threshold burst detection (i.e. when burst_method=’amp’).

find_extrema_kwargsdict, optional, default: None

Keyword arguments for function to find peaks an 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]).

return_samplesbool, optional, default: True

Returns samples indices of cyclepoints used for determining features if True.

Returns:

df_featurespandas.DataFrame

A dataframe containing shape and burst features for each 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

When consistency burst detection is used (i.e. burst_method=’cycles’):

• amp_fraction : normalized amplitude

• amp_consistency : difference in the rise and decay voltage within a cycle

• period_consistency : difference between a cycle’s period and the period of the adjacent cycles

• monotonicity : fraction of monotonic voltage changes in rise and decay phases (positive going in rise and negative going in decay)

When dual threshold burst detection is used (i.e. burst_method=’amp’):

• burst_fraction : fraction of a cycle that is bursting

When cyclepoints are returned (i.e. default, return_samples=True)

• 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

Examples

Compute shape and burst features:

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