spudtr.epf module

utilities for epoched EEG data in a pandas.DataFrame

spudtr.epf.center_eeg(epochs_df, eeg_streams, start, stop, epoch_id='epoch_id', time='time')

center (a.k.a. “baseline”) EEG amplitude on mean amplitude in [start, stop)

Parameters

• epochs_df (pd.DataFrame) – must have epoch_id and time columns

• eeg_streams (list of str) – column names to apply the transform

• start (int) – basline interval time values, start <= t <= stop

• stop (int) – basline interval time values, start <= t <= stop

• epoch_id (str, optional) – column to use for the epoch index

• time (str, optional) – column to use for the time stamp index

Returns

centered_epochs_df – each epoch and channel time series centered on the [start, stop) interval mean amplitude

Return type

pd.DataFrame

Notes

The start, stop values pick the smallest and largest timestamps in the interval, i.e., [start_stamp, stop_stamp], but since the data are sliced with np.arange, the upper bound is not included, i.e., start_stamp <= timestamps < stop_stamp. So, for instance, start=-200, stop=0, would include timestamps at -200, -199, … -1, but not 0.

spudtr.epf.check_epochs(epochs_df, data_streams, epoch_id='epoch_id', time='time')

check epochs data are in spudtr format

Parameters

• epochs_df (pd.DataFrame) –

• data_streams (list of str) – the columns containing data

• epoch_id (str, optional) – column name for the epoch index

• time (str, optional) – column name for the time stamps

Raises

Exception – diagnostic for what went wrong

spudtr.epf.drop_bad_epochs(epochs_df, bads_column, epoch_id='epoch_id', time='epoch_id')

Quality control data slicer, excludes previously tagged artifact epochs

All epochs tagged with a non-zero quality code on the specified bads_column at the time stamp == 0 are excluded.

Parameters

• epochs_df (pd.DataFrame) – must have epoch_id and time row index names

• bads_column (str) – column name with QC codes: non-zero == drop

• epoch_id (str, optional) – column name for epoch indexes

• time (str, optional) – column name for time stamps

Returns

good_epochs_df – subset of the epochs with code 0 on bads_column at timestamp == 0

Return type

pd.DataFrame

spudtr.epf.fir_filter_epochs(epochs_df, data_columns, ftype=None, cutoff_hz=None, width_hz=None, ripple_db=None, window=None, sfreq=None, trim_edges=False, epoch_id='epoch_id', time='time')

apply FIRLS filtering to spudtr format epoched data

Parameters

• epochs_df (pd.DataFrame) – must be a spudtr format epochs dataframe with epoch_id, time columns

• data_columns (list of str) – column names to apply the transform

• ftype (str {'lowpass' , 'highpass', 'bandpass', 'bandstop'}) – filter type

• cutoff_hz (float or 1D-array-like of floats, length 2) – 1/2 amplitude cutoff frequency in Hz

• width_hz (float) – pass-to-stop transition band width (Hz), symmetric for bandpass, bandstop

• ripple_db (float) – ripple, in dB, e.g., 53.0, 60.0

• window (str {'kaiser','hamming','hann','blackman'}) – window type for firwin

• sfreq (float) – sampling frequency, e.g., 250.0, 500.0

• trim_edges (bool) – True trim edges, False not trim edges

• epoch_id (str {"epoch_id"}, optional) – column name for epoch index

• time (str {"time"}, optional) – column name for timestamps

Returns

a copy of epochs_df, with data in data_columns filtered

Return type

pd.DataFrame

Notes

All the filter parameters are mandatory, consider making a filter_params dictionary and expanding it like so fir_filter_epochs( ..., **filter_params).

By default the filtered epochs have the same length as the original. The trim_edges option returns the center interval of each epoch, free from distortion at the edges but this may result in considerable data loss depending on the filter specifications.

Examples

>>> ftype = "bandpass"
>>> cutoff_hz = [18, 35]
>>> sfreq = 250
>>> window = "kaiser"
>>> width_hz = 5
>>> ripple_db = 60
>>> epoch_id = "epoch_id"
>>> time = "time_ms"
>>> filt_test_df = epochs_filters(
        epochs_df,
        data_columns,
        ftype=ftype,
        cutoff_hz=cutoff_hz,
        width_hz=width_hz,
        ripple_db=ripple_db,
        window=window,
        sfreq=sfreq,
        trim_edges=False
        epoch_id=epoch_id
        time=time
)

spudtr.epf.re_reference(epochs_df, eeg_streams, ref, ref_type, epoch_id='epoch_id', time='time')

Convert EEG data recorded with a common reference to a different reference

Warning

These transforms are intended for use with common reference EEG data. Use with other types of data are at your own risk.

Parameters

• epochs_df (pd.DataFrame) – must have epoch_id and time row index names

• eeg_streams (list-like of str) – the names of colums to transform

• ref (str or list-like of str) – name of the 2nd stream for a linked pair, the new common reference, or the complete list of streams to use for a common average reference

• type (str = {'linked_pair', 'new_common', 'common_average'}) –

• epoch_id (str, optional) –

• time (str, optional) –

Returns

a copy of epochs_df with eeg_streams re-referenced

Return type

pd.DataFrame

Note

linked_pair

Transforms the EEG data to a “linked” pair reference:

\[EEG_{\text{re-referenced}} = EEG - (0.5 \times EEG_{ref})\]

May be used to switch from an A1 left mastoid common reference to a common linked A1, A2 mastoid reference (“bimastoid”).

new_common

Transforms EEG to a different common reference location:

\[EEG_{\text{re-referenced}} = EEG - EEG_{ref}\]

May be used switch from an A1 common reference to a vertex or nose-tip reference.

common_average

Transforms EEG to a common average reference of \(N\) EEG reference streams

\[EEG_{\text{re-referenced}} = EEG - \frac{\sum_{i=0}^{i=N}{EEG_{ref[i]}}}{N}\]

Examples

Switch from A1 reference to linked-mastoids

>>> eeg_streams = ['MiPf', 'MiCe', 'MiPa', 'MiOc']
>>> re_reference(epochs_df, eeg_streams, 'A2', 'linked_pair')

Switch to a vertex reference, MiCe

>>> eeg_streams = ['MiPf', 'MiCe', 'MiPa', 'MiOc']
>>> br_epochs_df = epf.re_reference(epochs_df, eeg_streams, 'MiCe', "new_common")

Switch to a common average reference (typically all available EEG data streams)

>>> eeg_streams = ['MiPf', 'MiCe', 'MiPa', 'MiOc']
>>> ref = eeg_streams
>>> br_epochs_df = epf.re_reference(epochs_df, eeg_streams, ref, "common_average")