- mne.epochs.make_metadata(events, event_id, tmin, tmax, sfreq, row_events=None, keep_first=None, keep_last=None)[source]#
Generate metadata from events for use with
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.DataFramesuitable for use as
Epochsmetadata: one row per time-locked event, and columns indicating presence/absence and latency of each ancillary event type.
The function will also return a new
event_iddictionary that correspond to the generated metadata.
array, shape (m, 3)
The events array. By default, the returned metadata
DataFramewill have as many rows as the events array. To create rows for only a subset of events, pass the
A mapping from event names (keys) to event IDs (values). The event names will be incorporated as columns of the returned metadata
- tmin, tmax
Start and end of the time interval for metadata generation in seconds, relative to the time-locked event of the respective time window.
If you are planning to attach the generated metadata to
Epochsand intend to include only events that fall inside your epochs time interval, pass the same
tmaxvalues here as you use for your epochs.
The sampling frequency of the data from which the events array was extracted.
Event types around which to create the time windows / for which to create rows in the returned metadata
pandas.DataFrame. If provided, the string(s) must be keys of
None(default), rows are created for all event types present in
Specify subsets of hierarchical event descriptors (HEDs, inspired by ) matching events of which the first occurrence within each time window shall be stored in addition to the original events.
There is currently no way to retain all occurrences of a repeated event. The
keep_firstparameter 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/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 (
'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.
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
responsecolumn 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_firstparameter – unless you need to differentiate between two types of responses, like in the example above.
keep_first, but for keeping only the last occurrence of matching events. The column indicating the type of an event
myeventwill be named
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_lastevent types; floats indicating the latency of the event in seconds, relative to the time-locked event
if applicable, additional columns
keep_lastevent types, respetively; the values will be strings indicating which event types were matched by the provided HED patterns
array, shape (n, 3)
The events corresponding to the generated metadata, i.e. one time-locked event per row.
The event dictionary corresponding to the new events array. This will be identical to the input dictionary unless
row_eventsis supplied, in which case it will only contain the events provided there.
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. The can be useful, for example, to include events that occurred before or after an epoch, e.g. during the inter-trial interval.
New in version 0.23.
Getting started with mne.Report
Auto-generating Epochs metadata