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
¶
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
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
¶
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
¶
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
¶
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
¶
sessions: list | Literal['all'] = 'all'
The sessions to process. If 'all'
, will process all sessions found in the
BIDS dataset.
task_is_rest
module-attribute
¶
task_is_rest: bool = False
Whether the task should be treated as resting-state data.
runs
module-attribute
¶
runs: Sequence | Literal['all'] = 'all'
The runs to process. If 'all'
, will process all runs found in the
BIDS dataset.
exclude_runs
module-attribute
¶
exclude_runs: dict[str, list[str]] | None = None
Specify runs to exclude from analysis, for each participant individually.
Example
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
¶
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.
subjects
module-attribute
¶
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
subjects = 'all' # Include all subjects.
subjects = ['05'] # Only include subject 05.
subjects = ['01', '02'] # Only include subjects 01 and 02.
exclude_subjects
module-attribute
¶
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
¶
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
¶
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
¶
ch_types: Annotated[Sequence[Literal['meg', 'mag', 'grad', 'eeg']], Len(1, 4)] = []
The channel types to consider.
Example
# 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
¶
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:
ch_types = ['eeg']
data_type = 'meg'
The dataset contains simultaneous recordings of MEG and EEG, and we only wish to process the gradiometer data:
ch_types = ['grad']
data_type = 'meg' # or data_type = None
The dataset contains only EEG data:
ch_types = ['eeg']
data_type = 'eeg' # or data_type = None
eog_channels
module-attribute
¶
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:
eog_channels = ['Fp1']
Treat Fp1
and Fp2
as virtual EOG channels:
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
¶
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
:
eeg_add_bipolar_channels = {'HEOG': ('HEOG_left', 'HEOG_right')}
Create two bipolar channels, HEOG
and VEOG
:
eeg_add_bipolar_channels = {'HEOG': ('HEOG_left', 'HEOG_right'),
'VEOG': ('VEOG_lower', 'VEOG_upper')}
eeg_reference
module-attribute
¶
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:
eeg_reference = 'average'
Use the P9
channel as reference:
eeg_reference = 'P9'
Use the average of the P9
and P10
channels as reference:
eeg_reference = ['P9', 'P10']
eeg_template_montage
module-attribute
¶
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:
eeg_template_montage = None
Apply 64-channel Biosemi 10/20 template montage:
eeg_template_montage = 'biosemi64'
drop_channels
module-attribute
¶
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:
drop_channels = ['Fp1', 'Cz]
analyze_channels
module-attribute
¶
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:
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
¶
reader_extra_params: dict = {}
Parameters to be passed to read_raw_bids()
calls when importing raw data.
Example
Enforce units for EDF files:
reader_extra_params = {"units": "uV"}
read_raw_bids_verbose
module-attribute
¶
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
¶
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
¶
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