mne.epochs.make_metadata

mne.epochs.make_metadata(events, event_id, tmin, tmax, sfreq, row_events=None, keep_first=None, keep_last=None)

Automatically generate metadata for use with mne.Epochs from events.

This function mimics the epoching process (it constructs time windows around time-locked “events of interest”) and collates information about any other events that occurred within those time windows. The information is returned as a pandas.DataFrame, suitable for use as Epochs metadata: one row per time-locked event, and columns indicating presence or absence and latency of each ancillary event type.

The function will also return a new events array and event_id dictionary that correspond to the generated metadata, which together can then be readily fed into Epochs.

Parameters:

eventsarray, shape (m, 3)

The events array. By default, the returned metadata DataFrame will have as many rows as the events array. To create rows for only a subset of events, pass the row_events parameter.

event_iddict

A mapping from event names (keys) to event IDs (values). The event names will be incorporated as columns of the returned metadata DataFrame.

tmin, tmaxfloat | str | list of str | None

If float, start and end of the time interval for metadata generation in seconds, relative to the time-locked event of the respective time window (the “row events”).

Note

If you are planning to attach the generated metadata to Epochs and intend to include only events that fall inside your epoch’s time interval, pass the same tmin and tmax values here as you use for your epochs.

If None, the time window used for metadata generation is bounded by the row_events. This is can be particularly practical if trial duration varies greatly, but each trial starts with a known event (e.g., a visual cue or fixation).

Note

If tmin=None, the first time window for metadata generation starts with the first row event. If tmax=None, the last time window for metadata generation ends with the last event in events.

If a string or a list of strings, the events bounding the metadata around each “row event”. For tmin, the events are assumed to occur before the row event, and for tmax, the events are assumed to occur after – unless tmin or tmax are equal to a row event, in which case the row event serves as the bound.

Changed in version 1.6.0: Added support for None.

New in v1.7.0: Added support for strings.

sfreqfloat

The sampling frequency of the data from which the events array was extracted.

row_eventslist of str | str | None

Event types around which to create the time windows. For each of these time-locked events, we will create a row in the returned metadata pandas.DataFrame. If provided, the string(s) must be keys of event_id. If None (default), rows are created for all event types present in event_id.

keep_firststr | list of str | None

Specify subsets of hierarchical event descriptors (HEDs, inspired by [1]) matching events of which the first occurrence within each time window shall be stored in addition to the original events.

Note

There is currently no way to retain all occurrences of a repeated event. The keep_first parameter can be used to specify subsets of HEDs, effectively creating a new event type that is the union of all events types described by the matching HED pattern. Only the very first event of this set will be kept.

For example, you might have two response events types, response/left and response/right; and in trials with both responses occurring, you want to keep only the first response. In this case, you can pass keep_first='response'. This will add two new columns to the metadata: response, indicating at what time the event occurred, relative to the time-locked event; and first_response, stating which type ('left' or 'right') of event occurred. To match specific subsets of HEDs describing different sets of events, pass a list of these subsets, e.g. keep_first=['response', 'stimulus']. If None (default), no event aggregation will take place and no new columns will be created.

Note

By default, this function will always retain the first instance of any event in each time window. For example, if a time window contains two 'response' events, the generated response column will automatically refer to the first of the two events. In this specific case, it is therefore not necessary to make use of the keep_first parameter – unless you need to differentiate between two types of responses, like in the example above.

keep_lastlist of str | None

Same as keep_first, but for keeping only the last occurrence of matching events. The column indicating the type of an event myevent will be named last_myevent.

Returns:

metadatapandas.DataFrame

Metadata for each row event, with the following columns:

• event_name, with strings indicating the name of the time-locked event (“row event”) for that specific time window

• one column per event type in event_id, with the same name; floats indicating the latency of the event in seconds, relative to the time-locked event

• if applicable, additional columns named after the keep_first and keep_last event types; floats indicating the latency of the event in seconds, relative to the time-locked event

• if applicable, additional columns first_{event_type} and last_{event_type} for keep_first and keep_last event types, respetively; the values will be strings indicating which event types were matched by the provided HED patterns

eventsarray, shape (n, 3)

The events corresponding to the generated metadata, i.e. one time-locked event per row.

event_iddict

The event dictionary corresponding to the new events array. This will be identical to the input dictionary unless row_events is supplied, in which case it will only contain the events provided there.

Notes

The time window used for metadata generation need not correspond to the time window used to create the Epochs, to which the metadata will be attached; it may well be much shorter or longer, or not overlap at all, if desired. This can be useful, for example, to include events that occurred before or after an epoch, e.g. during the inter-trial interval. If either tmin, tmax, or both are None, or a string referring e.g. to a response event, the time window will typically vary, too.

New in v0.23.

References

[1]

Nima Bigdely-Shamlo, Kenneth Kreutz-Delgado, Kay Robbins, Makoto Miyakoshi, Marissa Westerfield, Tarik Bel-Bahar, Christian Kothe, Jessica Hsi, and Scott Makeig. Hierarchical event descriptor (HED) tags for analysis of event-related EEG studies. In 2013 IEEE Global Conference on Signal and Information Processing, 1–4. IEEE, 2013. doi:10.1109/GlobalSIP.2013.6736796.

Examples using mne.epochs.make_metadata

Getting started with mne.Report

Getting started with mne.Report

Auto-generating Epochs metadata

Auto-generating Epochs metadata

Automated epochs metadata generation with variable time windows

Automated epochs metadata generation with variable time windows