bycycle.group.compute_features_3d

bycycle.group.compute_features_3d(sigs, fs, f_range, compute_features_kwargs=None, axis=0, return_samples=True, n_jobs=-1, progress=None)

Compute shape and burst features for a 3 dimensional array of signals.

Parameters:

sigs3d array

Voltage time series, with 3d shape, i.e. (n_channels, n_epochs, n_samples).

fsfloat

Sampling rate, in Hz.

f_rangetuple of (float, float)

Frequency range for narrowband signal of interest, in Hz.

compute_features_kwargsdict or 1d list of dict or 2d list of dict

Keyword arguments used in compute_features().

axis{0, 1, (0, 1)}

Which axes to calculate features across:

• axis=0 : Iterates over 2D slices along the zeroth dimension, (i.e. for each channel in (n_channels, n_epochs, n_timepoints)).

• axis=1 : Iterates over 2D slices along the first dimension (i.e. across flatten epochs in (n_epochs, n_channels, n_timepoints)).

• axis=(0, 1) : Iterates over 1D slices along the zeroth and first dimensions (i.e across each signal independently in (n_participants, n_channels, n_timepoints)).

return_samplesbool, optional, default: True

Whether to return a dataframe of cyclepoint sample indices.

n_jobsint, optional, default: -1

The number of jobs to compute features in parallel.

progress{None, ‘tqdm’, ‘tqdm.notebook’}

Specify whether to display a progress bar. Uses ‘tqdm’ if installed.

Returns:

dfs_featureslist of pandas.DataFrame

Dataframes containing shape and burst features for each cycle. Each dataframe is computed using the compute_features() function.

Notes

• The order of dfs_features corresponds to the order of sigs. This list of dataframes may be reorganized into a single dataframe using flatten_dfs().

• If compute_features_kwargs is a dictionary, the same kwargs are applied applied across all signals. A 1d list, equal in length to the first dimensions of sigs, may be applied to each set of signals along the first dimensions. A 2d list, the same shape as the first two dimensions of sigs may also be used to applied unique parameters to each signal.

• return_samples is controlled from the kwargs passed in this function. The return_samples value in compute_features_kwargs will be ignored.

Examples

Compute the features of a 3d array, in parallel, with a shape of (n_channels=2, n_epochs=3, n_signals=5000) using the same compute_features kwargs:

>>> import numpy as np
>>> from neurodsp.sim import sim_bursty_oscillation
>>> fs = 500
>>> sigs = np.array([[sim_bursty_oscillation(10, fs, freq=10) for epoch in range(3)]
...                 for ch in range(2)])
>>> threshold_kwargs = {'amp_consistency_threshold': .5, 'period_consistency_threshold': .5,
...                     'monotonicity_threshold': .8, 'min_n_cycles': 3}
>>> compute_feature_kwargs = {'threshold_kwargs': threshold_kwargs, 'center_extrema': 'trough'}
>>> features = compute_features_3d(sigs, fs, f_range= (8, 12),
...                                compute_features_kwargs=compute_feature_kwargs, axis=0,
...                                n_jobs=2)

Compute the features of a 3d array, in parallel, with a shape of (n_channels=2, n_epochs=3, n_signals=5000) using channel-specific compute_features kwargs:

>>> threshold_kwargs_ch1 = {'amp_consistency_threshold': .25, 'monotonicity_threshold': .25,
...                         'period_consistency_threshold': .25, 'min_n_cycles': 3}
>>> threshold_kwargs_ch2 = {'amp_consistency_threshold': .5, 'monotonicity_threshold': .5,
...                         'period_consistency_threshold': .5, 'min_n_cycles': 3}
>>> compute_kwargs = [{'threshold_kwargs': threshold_kwargs_ch1, 'center_extrema': 'trough'},
...                   {'threshold_kwargs': threshold_kwargs_ch2, 'center_extrema': 'trough'}]
>>> features = compute_features_3d(sigs, fs, f_range= (8, 12),
...                                compute_features_kwargs=compute_kwargs, axis=0, n_jobs=2)