mne.preprocessing.maxwell_filter_prepare_emptyroom#

mne.preprocessing.maxwell_filter_prepare_emptyroom(raw_er, *, raw, bads='from_raw', annotations='from_raw', meas_date='keep', emit_warning=False, verbose=None)[source]#

Prepare an empty-room recording for Maxwell filtering.

Empty-room data by default lacks certain properties that are required to ensure running maxwell_filter() will process the empty-room recording the same way as the experimental data. This function preconditions an empty-room raw data instance accordingly so it can be used for Maxwell filtering. Please see the Notes section for details.

Parameters:
raw_erinstance of Raw

The empty-room recording. It will not be modified.

rawinstance of Raw

The experimental recording, typically this will be the reference run used for Maxwell filtering.

bads‘from_raw’ | ‘union’ | ‘keep’

How to populate the list of bad channel names to be injected into the empty-room recording. If 'from_raw' (default) the list of bad channels will be overwritten with that of raw. If 'union', will use the union of bad channels in raw and raw_er. Note that this may lead to additional bad channels in the empty-room in comparison to the experimental recording. If 'keep', don’t alter the existing list of bad channels.

Note

Non-MEG channels are silently dropped from the list of bads.

annotations‘from_raw’ | ‘union’ | ‘keep’

Whether to copy the annotations over from raw (default), use the union of the annotations, or to keep them unchanged.

meas_date‘keep’ | ‘from_raw’

Whether to transfer the measurement date from raw or to keep it as is (default). If you intend to manually transfer annotations from raw after running this function, you should set this to 'from_raw'.

emit_warningbool

Whether to emit warnings when cropping or omitting annotations. Unlike raw.set_annotations, the default here is False, as empty-room recordings are often shorter than raw.

verbosebool | str | int | None

Control verbosity of the logging output. If None, use the default verbosity level. See the logging documentation and mne.verbose() for details. Should only be passed as a keyword argument.

Returns:
raw_er_preparedinstance of Raw

A copy of the passed empty-room recording, ready for Maxwell filtering.

Notes

This function will:

  • Compile the list of bad channels according to the bads parameter.

  • Inject the device-to-head transformation matrix from the experimental recording into the empty-room recording.

  • Set the following properties of the empty-room recording to match the experimental recording:

    • Montage (required for the fiducials defining the head coordinate frame)

    • raw.first_time and raw.first_samp

  • Adjust annotations according to the annotations parameter.

  • Adjust the measurement date according to the meas_date parameter.

Note

Note that in case of dual MEG/EEG acquisition, EEG channels should not be included in the empty room recording. If provided, they will be ignored.

New in v1.1.