Continuous data preprocessing (spynal.spectra.preprocess)

Preprocessing functions for LFP/EEG/continuous data

cut_trials(data, trial_lims, smp_rate, axis=0)

Cut continuous (eg LFP) data into trials

Parameters:

• data (ndarray, shape=(...,n_timepts,...)) – Continuous data unsegmented into trials. Arbitrary dimensionality, could include multiple channels, etc.

• trial_lims (array-like, shape=(n_trials,2)) – List of [start,end] of each trial (in s) to use to cut data.

• smp_rate (float) – Sampling rate of data (Hz).

• axis (int, default: 0 (1st axis)) – Axis of data array corresponding to time samples

Returns:

cut_data – Continuous data segmented into trials. Trial axis is appended to end of all axes in input data.

Return type:

ndarray, shape=(…,n_trial_timepts,…,n_trials)

realign_data(data, align_times, time_range, timepts, time_axis=0, trial_axis=-1)

Realigns trial-cut continuous (eg LFP) data to new set of within-trial times (eg new trial event) so that t=0 on each trial at given event. For example, data aligned to a start-of-trial event might need to be relaligned to the behavioral response.

Parameters:

• data (ndarray, shape=(...,n_timepts,...,n_trials,...)) – Continuous data segmented into trials. Arbitrary dimensionality, could include multiple channels, etc.

• align_times (array-like, shape=(n_trials,)) – New set of times (in old reference frame) to realign data to (in s)

• time_range (array-like, shape=(2,)) – Time range to extract from each trial around new align time ([start,end] in s relative to align_times). eg, time_range=(-1,1) -> extract 1 s on either side of align event.

• timepts (array-like, shape=(n_timepts)) – Time sampling vector for data (in s)

• time_axis (int, default: 0 (1st axis of array)) – Axis of data corresponding to time samples

• trial_axis (int, default: -1 (last axis of array)) – Axis of data corresponding to distinct trials

Returns:

realigned – Data realigned to given within-trial times. Time axis is reduced to length implied by time_range, but otherwise array has same shape as input data.

Return type:

ndarray, shape=(…,n_timepts_out,…,n_trials,…)

realign_data_on_event(data, event_data, event, time_range, timepts, time_axis=0, trial_axis=-1)

Convenience wrapper around realign_data for relaligning to a given named event within a per-trial dataframe or dict variable.

Only parameters differing from realign_data() are described here.

Parameters:

• event_data (dict, {str : ndarray, shape=(n_trials,)} or DataFrame, shape=(n_trials,n_events)) – Per-trial event timing data to use to realign spike timestamps.

• event (str) – Dict key or DataFrame column name whose associated values are to be used to realign data

remove_dc(data, axis=None)

Remove constant DC component of signals, estimated as across-time mean for each time series (ie trial,channel,etc.)

Parameters:

• data (ndarray, shape=(...,n_timepoints,...)) – Raw data to remove DC component of. Can be any arbitary shape, with time sampling along axis

• axis (int, Default: None (remove DC component computed across full data array)) – Data axis corresponding to time

Returns:

data – Data with DC component removed (same shape as input)

Return type:

ndarray, shape=(…,n_timepoints,…)

remove_evoked(data, axis=0, method='mean', design=None, return_evoked=False)

Remove estimate of evoked potentials phase-locked to trial events, returning data with (in theory) only non-phase-locked induced components

Parameters:

• data (ndarray, shape=(...,n_obs,...)) – Raw data to remove evoked components from. Can be any arbitary shape, with observations (trials) along axis.

• axis (int, default: 0 (1st axis)) – Data axis corresponding to distinct observations/trials

• method ({'mean','groupmean','regress'}, default: 'mean') –

  Method to use for estimating evoked potentials:

  • ’mean’ : Grand mean signal across all observations (trials)

  • ’groupmean’ : Mean signal across observations with each group in design

  • ’regress’ : OLS regresion fit of design matrix design to data

• design (array-like, shape=(n_obs,...), optional) – Design matrix to fit to data (method == ‘regress’) or group/condition labels for each observation (method == ‘groupmean’). Not used for method == ‘mean’.

• return_evoked (bool, default: False) – If True, also returns second output = estimated evoked potential on each trial.

Returns:

• data_induced (ndarray, shape=(…,n_obs,…)) – Data with estimated evoked component removed, leaving only non-phase-locked “induced” component. Same shape as input data.

• evoked (ndarray, shape=(…,n_obs,…), optional) – Evoked potential for each trial, estimated with given method. Same shape as data. Only returned if return_evoked is True.