spudtr.mneutils module

class spudtr.mneutils.EpochsSpudtr(input_fname, eeg_streams, eeg_locations_f, categories, time_stamp, epoch_id=None, time=None, time_unit=None)[source]

Bases: EpochsArray

spudtr.mneutils.categories2eventid(epochs_df, categories, epoch_id, time, time_stamp)[source]

Build an MNE events array and event_id dict from one or more categorical variables.

This uses patsy formulas and dummy coded (full rank) design matrixes to construct the MNE format event_id dictionary and corresponding events array (events x 3) for tagging and binning single-trial epochs for time-domain aggregation into mne.Evoked, e.g., average event-related potentials (ERPs).

A single category is split into the category levels, a.k.a conditions, bins, like so: ~ 0 + a.

Multiple categories fully crossed like so: ~ 0 +  a:b and ~ 0 + a:b:c

Parameters

  • epochs_df (pandas.DataFrame) – A spudtr format epochs data with epoch_id, time columns.

  • categories (str or iterable of str) – The column name(s) of the categorical variables.

  • epoch_id (str) – The name of the column with the unique epoch ids, e.g., epoch_id, Epoch_idx.

  • time (str) – The name of the column with the regular epoch time stamps, e.g., time, time_ms, time_s.

  • time_stamp (int The time stamp in the epoch to look up the) – categorical variable values, e.g., 0

Returns

  • mne_event_id (dict) – An MNE Python event_id dictionary where each item is label: event_code. The label is the column name from the patsy full-rank design matrix (incidence matrix) for the categories (thank you NJS). The event_code is the 1-based column index in the design matrix.

  • mne_events (np.array, shape=(number_of_epochs, 3) there is one) –

    row for each epoch in epochs_df. Each row is

    [epoch_id, 0, mne_event_code]

    where mne_event_code is the newly constructed event code derived from the patsy design matrix column

Examples

Suppose at the specified time stamp the epochs_df categorical columns a and b have have the following levels: a: a1, a2, b: b1, b2, b3

>>> categories2eventid(epochs_df, categories="a", epoch_id, time, time_stamp)
event_ids = {
    "a[a1]": 1,
    "a[a2]": 2
}

>>> categories2eventid(epochs_df, categories="b", epoch_id, time, time_stamp)
event_ids = {
    "b[b1]": 1,
    "b[b2]": 2,
    "b[b3]": 3
}

>>> categories2eventid(epochs_df, categories=["a", "b"], epoch_id, time, time_stamp)
event_ids = {
    'a[a1]:b[b1]': 1,
    'a[a2]:b[b1]': 2,
    'a[a1]:b[b2]': 3,
    'a[a2]:b[b2]': 4,
    'a[a1]:b[b3]': 5,
    'a[a2]:b[b3]': 6
}
spudtr.mneutils.read_spudtr_epochs(input_fname, eeg_streams, eeg_locations_f, categories, time_stamp, epoch_id=None, time=None, time_unit=None)[source]
Parameters

  • Epochs (convert spudtr format epochs data to MNE) –

  • input_fname (file name of spudtr format epochs data.) –

  • eeg_streams (list of str) – column names of the data streams

  • eeg_locations_f (path and file of mne_32chan_xyz_spherical.yml) –

  • categories (str or iterable of str) – The column name(s) of the categorical variables.

  • time_stamp (int The time stamp in the epoch to look up the) – categorical variable values, e.g., 0

  • epoch_id (str) – name of the epoch index

  • time (str) – name of the time stamp index, e.g., “time_ms”

  • time_unit (float) – time stamp unit in seconds, e.g., 0.001 for milliseconds, 1.0 for seconds

Returns

epochs

Return type

mne.Epochs