Skip to content

General settings

Info

Many settings in this section control the pipeline behavior very early in the pipeline. Therefore, for most of them (e.g., bids_root) we do not list the steps that directly depend on the setting. The options with drop-down step lists (e.g., random_state) have more localized effects.

bids_root module-attribute

Python
bids_root: PathLike | None = None

Specify the BIDS root directory. Pass an empty string or ``None to use the value specified in the BIDS_ROOT environment variable instead. Raises an exception if the BIDS root has not been specified.

Example
Python
bids_root = '/path/to/your/bids_root'  # Use this to specify a path here.
bids_root = None  # Make use of the `BIDS_ROOT` environment variable.

deriv_root module-attribute

Python
deriv_root: PathLike | None = None

The root of the derivatives directory in which the pipeline will store the processing results. If None, this will be derivatives/mne-bids-pipeline inside the BIDS root.

Info

If specified and you wish to run the source analysis steps, you must set subjects_dir as well.

subjects_dir module-attribute

Python
subjects_dir: PathLike | None = None

Path to the directory that contains the FreeSurfer reconstructions of all subjects. Specifically, this defines the SUBJECTS_DIR that is used by FreeSurfer.

  • When running the freesurfer processing step to create the reconstructions from anatomical scans in the BIDS dataset, the output will be stored in this directory.
  • When running the source analysis steps, we will look for the surfaces in this directory and also store the BEM surfaces there.

If None, this will default to bids_root/derivatives/freesurfer/subjects.

Info

This setting is required if you specify deriv_root and want to run the source analysis steps.

interactive module-attribute

Python
interactive: bool = False

If True, the steps will provide some interactive elements, such as figures. If running the steps from a notebook or Spyder, run %matplotlib qt in the command line to open the figures in a separate window.

Info

Enabling interactive mode deactivates parallel processing.

sessions module-attribute

Python
sessions: list | Literal['all'] = 'all'

The sessions to process. If 'all', will process all sessions found in the BIDS dataset.

task module-attribute

Python
task: str = ''

The task to process.

task_is_rest module-attribute

Python
task_is_rest: bool = False

Whether the task should be treated as resting-state data.

runs module-attribute

Python
runs: Sequence | Literal['all'] = 'all'

The runs to process. If 'all', will process all runs found in the BIDS dataset.

exclude_runs module-attribute

Python
exclude_runs: dict[str, list[str]] | None = None

Specify runs to exclude from analysis, for each participant individually.

Example
Python
exclude_runs = None  # Include all runs.
exclude_runs = {'01': ['02']}  # Exclude run 02 of subject 01.
Good Practice / Advice

Keep track of the criteria leading you to exclude a run (e.g. too many movements, missing blocks, aborted experiment, did not understand the instructions, etc.).

crop_runs module-attribute

Python
crop_runs: tuple[float, float] | None = None

Crop the raw data of each run to the specified time interval [tmin, tmax], in seconds. The runs will be cropped before Maxwell or frequency filtering is applied. If None, do not crop the data.

acq module-attribute

Python
acq: str | None = None

The BIDS acquisition entity.

proc module-attribute

Python
proc: str | None = None

The BIDS processing entity.

rec module-attribute

Python
rec: str | None = None

The BIDS recording entity.

space module-attribute

Python
space: str | None = None

The BIDS space entity.

subjects module-attribute

Python
subjects: Sequence[str] | Literal['all'] = 'all'

Subjects to analyze. If 'all', include all subjects. To only include a subset of subjects, pass a list of their identifiers. Even if you plan on analyzing only a single subject, pass their identifier as a list.

Please note that if you intend to EXCLUDE only a few subjects, you should consider setting subjects = 'all' and adding the identifiers of the excluded subjects to exclude_subjects (see next section).

Example
Python
subjects = 'all'  # Include all subjects.
subjects = ['05']  # Only include subject 05.
subjects = ['01', '02']  # Only include subjects 01 and 02.

exclude_subjects module-attribute

Python
exclude_subjects: Sequence[str] = []

Specify subjects to exclude from analysis. The MEG empty-room mock-subject is automatically excluded from regular analysis.

Good Practice / Advice

Keep track of the criteria leading you to exclude a participant (e.g. too many movements, missing blocks, aborted experiment, did not understand the instructions, etc, ...) The emptyroom subject will be excluded automatically.

process_empty_room module-attribute

Python
process_empty_room: bool = True

Whether to apply the same pre-processing steps to the empty-room data as to the experimental data (up until including frequency filtering). This is required if you wish to use the empty-room recording to estimate noise covariance (via noise_cov='emptyroom'). The empty-room recording corresponding to the processed experimental data will be retrieved automatically.

process_rest module-attribute

Python
process_rest: bool = True

Whether to apply the same pre-processing steps to the resting-state data as to the experimental data (up until including frequency filtering). This is required if you wish to use the resting-state recording to estimate noise covariance (via noise_cov='rest').

ch_types module-attribute

Python
ch_types: Annotated[Sequence[Literal['meg', 'mag', 'grad', 'eeg']], Len(1, 4)] = []

The channel types to consider.

Example
Python
# Use EEG channels:
ch_types = ['eeg']

# Use magnetometer and gradiometer MEG channels:
ch_types = ['mag', 'grad']

# Use MEG and EEG channels:
ch_types = ['meg', 'eeg']

data_type module-attribute

Python
data_type: Literal['meg', 'eeg'] | None = None

The BIDS data type.

For MEG recordings, this will usually be 'meg'; and for EEG, 'eeg'. However, if your dataset contains simultaneous recordings of MEG and EEG, stored in a single file, you will typically need to set this to 'meg'. If None, we will assume that the data type matches the channel type.

Example

The dataset contains simultaneous recordings of MEG and EEG, and we only wish to process the EEG data, which is stored inside the MEG files:

Python
ch_types = ['eeg']
data_type = 'meg'

The dataset contains simultaneous recordings of MEG and EEG, and we only wish to process the gradiometer data:

Python
ch_types = ['grad']
data_type = 'meg'  # or data_type = None

The dataset contains only EEG data:

Python
ch_types = ['eeg']
data_type = 'eeg'  # or data_type = None

eog_channels module-attribute

Python
eog_channels: Sequence[str] | None = None

Specify EOG channels to use, or create virtual EOG channels.

Allows the specification of custom channel names that shall be used as (virtual) EOG channels. For example, say you recorded EEG without dedicated EOG electrodes, but with some EEG electrodes placed close to the eyes, e.g. Fp1 and Fp2. These channels can be expected to have captured large quantities of ocular activity, and you might want to use them as "virtual" EOG channels, while also including them in the EEG analysis. By default, MNE won't know that these channels are suitable for recovering EOG, and hence won't be able to perform tasks like automated blink removal, unless a "true" EOG sensor is present in the data as well. Specifying channel names here allows MNE to find the respective EOG signals based on these channels.

You can specify one or multiple channel names. Each will be treated as if it were a dedicated EOG channel, without excluding it from any other analyses.

If None, only actual EOG channels will be used for EOG recovery.

If there are multiple actual EOG channels in your data, and you only specify a subset of them here, only this subset will be used during processing.

Example

Treat Fp1 as virtual EOG channel:

Python
eog_channels = ['Fp1']

Treat Fp1 and Fp2 as virtual EOG channels:

Python
eog_channels = ['Fp1', 'Fp2']

Pipeline steps using this setting

The following steps are directly affected by changes to eog_channels:

  • preprocessing/_01_data_quality
  • preprocessing/_02_head_pos
  • preprocessing/_03_maxfilter
  • preprocessing/_04_frequency_filter
  • preprocessing/_05_regress_artifact
  • preprocessing/_06a1_fit_ica
  • preprocessing/_06a2_find_ica_artifacts
  • preprocessing/_06b_run_ssp
  • preprocessing/_08a_apply_ica
  • preprocessing/_08b_apply_ssp

eeg_bipolar_channels module-attribute

Python
eeg_bipolar_channels: dict[str, tuple[str, str]] | None = None

Combine two channels into a bipolar channel, whose signal is the difference between the two combined channels, and add it to the data. A typical use case is the combination of two EOG channels – for example, a left and a right horizontal EOG – into a single, bipolar EOG channel. You need to pass a dictionary whose keys are the name of the new bipolar channel you wish to create, and whose values are tuples consisting of two strings: the name of the channel acting as anode and the name of the channel acting as cathode, i.e. {'ch_name': ('anode', 'cathode')}. You can request to construct more than one bipolar channel by specifying multiple key/value pairs. See the examples below.

Can also be None if you do not want to create bipolar channels.

Info

The channels used to create the bipolar channels are not automatically dropped from the data. To drop channels, set drop_channels.

Example

Combine the existing channels HEOG_left and HEOG_right into a new, bipolar channel, HEOG:

Python
eeg_add_bipolar_channels = {'HEOG': ('HEOG_left', 'HEOG_right')}

Create two bipolar channels, HEOG and VEOG:

Python
eeg_add_bipolar_channels = {'HEOG': ('HEOG_left', 'HEOG_right'),
                            'VEOG': ('VEOG_lower', 'VEOG_upper')}

eeg_reference module-attribute

Python
eeg_reference: Literal['average'] | str | Sequence[str] = 'average'

The EEG reference to use. If average, will use the average reference, i.e. the average across all channels. If a string, must be the name of a single channel. To use multiple channels as reference, set to a list of channel names.

Example

Use the average reference:

Python
eeg_reference = 'average'

Use the P9 channel as reference:

Python
eeg_reference = 'P9'

Use the average of the P9 and P10 channels as reference:

Python
eeg_reference = ['P9', 'P10']

eeg_template_montage module-attribute

Python
eeg_template_montage: str | DigMontageType | None = None

In situations where you wish to process EEG data and no individual digitization points (measured channel locations) are available, you can apply a "template" montage. This means we will assume the EEG cap was placed either according to an international system like 10/20, or as suggested by the cap manufacturers in their respective manual.

Please be aware that the actual cap placement most likely deviated somewhat from the template, and, therefore, source reconstruction may be impaired.

If None, do not apply a template montage. If a string, must be the name of a built-in template montage in MNE-Python. You can find an overview of supported template montages at https://mne.tools/stable/generated/mne.channels.make_standard_montage.html

Warning

If the data contains channel names that are not part of the template montage, the pipeline run will fail with an error message. You must either pick a different montage or remove those channels via drop_channels to continue.

Example

Do not apply template montage:

Python
eeg_template_montage = None

Apply 64-channel Biosemi 10/20 template montage:

Python
eeg_template_montage = 'biosemi64'

drop_channels module-attribute

Python
drop_channels: Sequence[str] = []

Names of channels to remove from the data. This can be useful, for example, if you have added a new bipolar channel via eeg_bipolar_channels and now wish to remove the anode, cathode, or both; or if your selected EEG template montage doesn't contain coordinates for some channels.

Example

Exclude channels Fp1 and Cz from processing:

Python
drop_channels = ['Fp1', 'Cz]

analyze_channels module-attribute

Python
analyze_channels: Literal["all", "ch_types"] | Annotated[Sequence[str], MinLen(1)] = (
    "ch_types"
)

The names of the channels to analyze during ERP/ERF and time-frequency analysis steps. For certain paradigms, e.g. EEG ERP research, it is common to constrain sensor-space analysis to only a few specific sensors. If 'all', do not exclude any channels (except for those selected for removal via the drop_channels setting; use with caution as this can include things like STIM channels during the decoding step). If 'ch_types' (default), restrict to the channels listed in the ch_types parameter. The constraint will be applied to all sensor-level analyses after the preprocessing stage, but not to the preprocessing stage itself, nor to the source analysis stage.

Example

Only use channel Pz for ERP, evoked contrasts, time-by-time decoding, and time-frequency analysis:

Python
analyze_channels = ['Pz']

Pipeline steps using this setting

The following steps are directly affected by changes to analyze_channels:

  • sensor/_01_make_evoked
  • sensor/_02_decoding_full_epochs
  • sensor/_03_decoding_time_by_time
  • sensor/_04_time_frequency
  • sensor/_05_decoding_csp
  • sensor/_06_make_cov
  • sensor/_99_group_average

reader_extra_params module-attribute

Python
reader_extra_params: dict = {}

Parameters to be passed to read_raw_bids() calls when importing raw data.

Example

Enforce units for EDF files:

Python
reader_extra_params = {"units": "uV"}

read_raw_bids_verbose module-attribute

Python
read_raw_bids_verbose: Literal['error'] | None = None

Verbosity level to pass to read_raw_bids(..., verbose=read_raw_bids_verbose). If you know your dataset will contain files that are not perfectly BIDS compliant (e.g., "Did not find any meg.json..."), you can set this to 'error' to suppress warnings emitted by read_raw_bids.

plot_psd_for_runs module-attribute

Python
plot_psd_for_runs: Literal['all'] | Sequence[str] = 'all'

For which runs to add a power spectral density (PSD) plot to the generated report. This can take a considerable amount of time if you have many long runs. In this case, specify the runs, or pass an empty list to disable raw PSD plotting.

random_state module-attribute

Python
random_state: int | None = 42

You can specify the seed of the random number generator (RNG). This setting is passed to the ICA algorithm and to the decoding function, ensuring reproducible results. Set to None to avoid setting the RNG to a defined state.

Pipeline steps using this setting

The following steps are directly affected by changes to random_state:

  • preprocessing/_06a1_fit_ica
  • preprocessing/_06a2_find_ica_artifacts
  • preprocessing/_09_ptp_reject
  • sensor/_02_decoding_full_epochs
  • sensor/_03_decoding_time_by_time
  • sensor/_05_decoding_csp
  • sensor/_99_group_average