bycycle.group.compute_features_2d¶

bycycle.group.compute_features_2d(sigs, fs, f_range, compute_features_kwargs=None, axis=0, return_samples=True, n_jobs=-1, progress=None)[source]¶

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

Parameters:

sigs2d array

Voltage time series, i.e. (n_channels, n_samples) or (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 list of dict

Keyword arguments used in compute_features().

axis{0, None}

Which axes to calculate features across:

axis=0 : Iterates over each row/signal in an array independently (i.e. for each channel in (n_channels, n_timepoints)).
axis=None : Flattens rows/signals prior to computing features (i.e. across flatten epochs in (n_epochs, 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().
When axis=None parallel computation may not be performed due to the requirement of flattening the array into one dimension.
If compute_features_kwargs is a dictionary, the same kwargs are applied applied across the first axis of sigs. Otherwise, a list of dictionaries equal in length to the first axis of sigs is required to apply unique kwargs to each signal.
return_samples is controlled from the kwargs passed in this function. If return_samples is a key in compute_features_kwargs, it’s value will be ignored.

Examples

Compute the features of a 2d array (n_epochs=10, n_samples=5000) containing epoched data:

>>> import numpy as np
>>> from neurodsp.sim import sim_bursty_oscillation
>>> fs = 500
>>> sigs = np.array([sim_bursty_oscillation(10, fs, 10) for i in range(10)])
>>> compute_kwargs = {'burst_method': 'amp', 'threshold_kwargs':{'burst_fraction_threshold': 1}}
>>> dfs_features = compute_features_2d(sigs, fs, f_range=(8, 12), axis=None,
...                                   compute_features_kwargs=compute_kwargs)

Compute the features of a 2d array in parallel using the same compute_features kwargs. Note each signal features are computed separately in this case, recommended for (n_channels, n_samples):

>>> compute_kwargs = {'burst_method': 'amp', 'threshold_kwargs':{'burst_fraction_threshold': 1}}
>>> dfs_features = compute_features_2d(sigs, fs, f_range=(8, 12), n_jobs=2, axis=0,
...                                   compute_features_kwargs=compute_kwargs)

Compute the features of a 2d array in parallel using using individualized settings per signal to examine the effect of various amplitude consistency thresholds:

>>> sigs =  np.array([sim_bursty_oscillation(10, fs, freq=10)] * 10)
>>> compute_kwargs = [{'threshold_kwargs': {'amp_consistency_threshold': thresh*.1}}
...                   for thresh in range(1, 11)]
>>> dfs_features = compute_features_2d(sigs, fs, f_range=(8, 12), return_samples=False,
...                                   n_jobs=2, compute_features_kwargs=compute_kwargs, axis=0)