- 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
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
Epochsmetadata: 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
event_iddictionary that correspond to the generated metadata, which together can then be readily fed into
array, shape (m, 3)
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 (the “row events”).
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.
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).
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
Changed in version 1.6.0: Added support for
The sampling frequency of the data from which the events array was extracted.
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
None(default), rows are created for all event types present in
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. 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
tmax, or both are
None, the time window will typically vary, too.
New in v0.23.