Skip to content

Epoching

rename_events module-attribute

Python
rename_events: dict = dict()

A dictionary specifying which events in the BIDS dataset to rename upon loading, and before processing begins.

Pass an empty dictionary to not perform any renaming.

Example

Rename audio_left in the BIDS dataset to audio/left in the pipeline:

Python
rename_events = {'audio_left': 'audio/left'}

on_rename_missing_events module-attribute

Python
on_rename_missing_events: Literal['ignore', 'warn', 'raise'] = 'raise'

How to handle the situation where you specified an event to be renamed via rename_events, but this particular event is not present in the data. By default, we will raise an exception to avoid accidental mistakes due to typos; however, if you're sure what you're doing, you may change this to 'warn' to only get a warning instead, or 'ignore' to ignore it completely.

event_repeated module-attribute

Python
event_repeated: Literal['error', 'drop', 'merge'] = 'error'

How to handle repeated events. We call events "repeated" if more than one event occurred at the exact same time point. Currently, MNE-Python cannot handle this situation gracefully when trying to create epochs, and will throw an error. To only keep the event of that time point ("first" here referring to the order that events appear in *_events.tsv), pass 'drop'. You can also request to create a new type of event by merging repeated events by setting this to 'merge'.

Warning

The 'merge' option is entirely untested in the MNE BIDS Pipeline as of April 1st, 2021.

Pipeline steps using this setting

The following steps are directly affected by changes to event_repeated:

  • preprocessing/_06a1_fit_ica
  • preprocessing/_06a2_find_ica_artifacts
  • preprocessing/_07_make_epochs

epochs_metadata_tmin module-attribute

Python
epochs_metadata_tmin: float | str | list[str] | None = None

The beginning of the time window used for epochs metadata generation. This setting controls the tmin value passed to mne.epochs.make_metadata.

If a float, the time in seconds relative to the time-locked event of the respective epoch. Negative indicate times before, positive values indicate times after the time-locked event.

If a string or a list of strings, the name(s) of events marking the start of time window.

If None, use the first time point of the epoch.

Info

Note that None here behaves differently than tmin=None in mne.epochs.make_metadata. To achieve the same behavior, pass the name(s) of the time-locked events instead.

Pipeline steps using this setting

The following steps are directly affected by changes to epochs_metadata_tmin:

  • preprocessing/_06a1_fit_ica
  • preprocessing/_06a2_find_ica_artifacts
  • preprocessing/_07_make_epochs

epochs_metadata_tmax module-attribute

Python
epochs_metadata_tmax: float | str | list[str] | None = None

Same as epochs_metadata_tmin, but specifying the end of the time window for metadata generation.

Pipeline steps using this setting

The following steps are directly affected by changes to epochs_metadata_tmax:

  • preprocessing/_06a1_fit_ica
  • preprocessing/_06a2_find_ica_artifacts
  • preprocessing/_07_make_epochs

epochs_metadata_keep_first module-attribute

Python
epochs_metadata_keep_first: Sequence[str] | None = None

Event groupings using hierarchical event descriptors (HEDs) for which to store the time of the first occurrence of any event of this group in a new column with the group name, and the type of that event in a column named after the group, but with a first_ prefix. If None (default), no event aggregation will take place and no new columns will be created.

Example

Assume you have two response events types, response/left and response/right; in some trials, both responses occur, because the participant pressed both buttons. Now, you want to keep the first response only. To achieve this, set

Python
epochs_metadata_keep_first = ['response']
This will add two new columns to the metadata: response, indicating the time relative to the time-locked event; and first_response, depicting the type of event ('left' or 'right').

You may also specify a grouping for multiple event types:

Python
epochs_metadata_keep_first = ['response', 'stimulus']
This will add the columns response, first_response, stimulus, and first_stimulus.

Pipeline steps using this setting

The following steps are directly affected by changes to epochs_metadata_keep_first:

  • preprocessing/_06a1_fit_ica
  • preprocessing/_06a2_find_ica_artifacts
  • preprocessing/_07_make_epochs

epochs_metadata_keep_last module-attribute

Python
epochs_metadata_keep_last: Sequence[str] | None = None

Same as epochs_metadata_keep_first, but for keeping the last occurrence of matching event types. The columns indicating the event types will be named with a last_ instead of a first_ prefix.

Pipeline steps using this setting

The following steps are directly affected by changes to epochs_metadata_keep_last:

  • preprocessing/_06a1_fit_ica
  • preprocessing/_06a2_find_ica_artifacts
  • preprocessing/_07_make_epochs

epochs_metadata_query module-attribute

Python
epochs_metadata_query: str | None = None

A [metadata query][https://mne.tools/stable/auto_tutorials/epochs/30_epochs_metadata.html] specifying which epochs to keep. If the query fails because it refers to an unknown metadata column, a warning will be emitted and all epochs will be kept.

Example

Only keep epochs without a response_missing event:

Python
epochs_metadata_query = ['response_missing.isna()']

Pipeline steps using this setting

The following steps are directly affected by changes to epochs_metadata_query:

  • preprocessing/_06a1_fit_ica
  • preprocessing/_06a2_find_ica_artifacts
  • preprocessing/_07_make_epochs

conditions module-attribute

Python
conditions: Sequence[str] | dict[str, str] | None = None

The time-locked events based on which to create evoked responses. This can either be name of the experimental condition as specified in the BIDS *_events.tsv file; or the name of condition groups, if the condition names contain the (MNE-specific) group separator, /. See the Subselecting epochs tutorial for more information.

Passing a dictionary allows to assign a name to map a complex condition name (value) to a more legible one (value).

This is a required parameter in the configuration file, unless you are processing resting-state data. If left as None and task_is_rest is not True, we will raise an error.

Example

Specifying conditions as lists of strings:

Python
conditions = ['auditory/left', 'visual/left']
conditions = ['auditory/left', 'auditory/right']
conditions = ['auditory']  # All "auditory" conditions (left AND right)
conditions = ['auditory', 'visual']
conditions = ['left', 'right']
conditions = None  # for a resting-state analysis
Pass a dictionary to define a mapping: ```python conditions = {'simple_name': 'complex/condition/with_subconditions'} conditions = {'correct': 'response/correct', 'incorrect': 'response/incorrect'}

Pipeline steps using this setting

The following steps are directly affected by changes to conditions:

  • preprocessing/_06a1_fit_ica
  • preprocessing/_06a2_find_ica_artifacts
  • preprocessing/_07_make_epochs
  • sensor/_01_make_evoked
  • sensor/_02_decoding_full_epochs
  • sensor/_03_decoding_time_by_time
  • sensor/_06_make_cov
  • sensor/_99_group_average
  • source/_05_make_inverse
  • source/_99_group_average

epochs_tmin module-attribute

Python
epochs_tmin: float = -0.2

The beginning of an epoch, relative to the respective event, in seconds.

Example
Python
epochs_tmin = -0.2  # 200 ms before event onset
Pipeline steps using this setting

The following steps are directly affected by changes to epochs_tmin:

  • preprocessing/_06a1_fit_ica
  • preprocessing/_06a2_find_ica_artifacts
  • preprocessing/_07_make_epochs
  • sensor/_05_decoding_csp
  • sensor/_99_group_average

epochs_tmax module-attribute

Python
epochs_tmax: float = 0.5

The end of an epoch, relative to the respective event, in seconds.

Example
Python
epochs_tmax = 0.5  # 500 ms after event onset
Pipeline steps using this setting

The following steps are directly affected by changes to epochs_tmax:

  • preprocessing/_06a1_fit_ica
  • preprocessing/_06a2_find_ica_artifacts
  • preprocessing/_07_make_epochs
  • sensor/_05_decoding_csp
  • sensor/_99_group_average

rest_epochs_duration module-attribute

Python
rest_epochs_duration: float | None = None

Duration of epochs in seconds.

Pipeline steps using this setting

The following steps are directly affected by changes to rest_epochs_duration:

  • preprocessing/_06a1_fit_ica
  • preprocessing/_06a2_find_ica_artifacts
  • preprocessing/_07_make_epochs

rest_epochs_overlap module-attribute

Python
rest_epochs_overlap: float | None = None

Overlap between epochs in seconds. This is used if the task is 'rest' and when the annotations do not contain any stimulation or behavior events.

Pipeline steps using this setting

The following steps are directly affected by changes to rest_epochs_overlap:

  • preprocessing/_06a1_fit_ica
  • preprocessing/_06a2_find_ica_artifacts
  • preprocessing/_07_make_epochs

baseline module-attribute

Python
baseline: tuple[float | None, float | None] | None = (None, 0)

Specifies which time interval to use for baseline correction of epochs; if None, no baseline correction is applied.

Example
Python
baseline = (None, 0)  # beginning of epoch until time point zero
Pipeline steps using this setting

The following steps are directly affected by changes to baseline:

  • preprocessing/_08a_apply_ica
  • preprocessing/_09_ptp_reject