Skip to content

Maxwell filter

use_maxwell_filter module-attribute

Python
use_maxwell_filter: bool = False

Whether or not to use Maxwell filtering to preprocess the data.

Warning

If the data were recorded with internal active compensation (MaxShield), they need to be run through Maxwell filter to avoid distortions. Bad channels need to be set through BIDS channels.tsv and / or via the find_flat_channels_meg and find_noisy_channels_meg options above before applying Maxwell filter.

Pipeline steps using this setting

The following steps are directly affected by changes to use_maxwell_filter:

  • preprocessing/_01_data_quality
  • preprocessing/_02_head_pos
  • preprocessing/_03_maxfilter
  • preprocessing/_04_frequency_filter
  • preprocessing/_05_regress_artifact
  • preprocessing/_06b_run_ssp
  • preprocessing/_07_make_epochs
  • preprocessing/_08a_apply_ica
  • preprocessing/_08b_apply_ssp
  • sensor/_05_decoding_csp

mf_st_duration module-attribute

Python
mf_st_duration: float | None = None

There are two kinds of Maxwell filtering: SSS (signal space separation) and tSSS (temporal signal space separation) (see Taulu et al., 2004).

If not None, apply spatiotemporal SSS (tSSS) with specified buffer duration (in seconds). MaxFilter™'s default is 10.0 seconds in v2.2. Spatiotemporal SSS acts as implicitly as a high-pass filter where the cut-off frequency is 1/st_dur Hz. For this (and other) reasons, longer buffers are generally better as long as your system can handle the higher memory usage. To ensure that each window is processed identically, choose a buffer length that divides evenly into your data. Any data at the trailing edge that doesn't fit evenly into a whole buffer window will be lumped into the previous buffer.

Good Practice / Advice

If you are interested in low frequency activity (<0.1Hz), avoid using tSSS and set mf_st_duration to None.

If you are interested in low frequency above 0.1 Hz, you can use the default mf_st_duration to 10 s, meaning it acts like a 0.1 Hz high-pass filter.

Example
Python
mf_st_duration = None
mf_st_duration = 10.  # to apply tSSS with 0.1Hz highpass filter.
Pipeline steps using this setting

The following steps are directly affected by changes to mf_st_duration:

  • preprocessing/_03_maxfilter

mf_st_correlation module-attribute

Python
mf_st_correlation: float = 0.98

The correlation limit for spatio-temporal SSS (tSSS).

Example
Python
st_correlation = 0.98
Pipeline steps using this setting

The following steps are directly affected by changes to mf_st_correlation:

  • preprocessing/_03_maxfilter

mf_head_origin module-attribute

Python
mf_head_origin: Literal['auto'] | FloatArrayLike = 'auto'

mf_head_origin : array-like, shape (3,) | 'auto' Origin of internal and external multipolar moment space in meters. If 'auto', it will be estimated from headshape points. If automatic fitting fails (e.g., due to having too few digitization points), consider separately calling the fitting function with different options or specifying the origin manually.

Example
Python
mf_head_origin = 'auto'
Pipeline steps using this setting

The following steps are directly affected by changes to mf_head_origin:

  • preprocessing/_01_data_quality
  • preprocessing/_03_maxfilter

mf_destination module-attribute

Python
mf_destination: Literal['reference_run'] | FloatArrayLike = 'reference_run'

Despite all possible care to avoid movements in the MEG, the participant will likely slowly drift down from the Dewar or slightly shift the head around in the course of the recording session. Hence, to take this into account, we are realigning all data to a single position. For this, you can:

  1. Choose a reference run. Often one from the middle of the recording session is a good choice. Set mf_destination = "reference_run" and then set [config.mf_reference_run`][mne_bids_pipeline._config.mf_reference_run]. This will result in a device-to-head transformation that differs between subjects.
  2. Choose a standard position in the MEG coordinate frame. For this, pass a 4x4 transformation matrix for the device-to-head transform. This will result in a device-to-head transformation that is the same across all subjects.

???+ example "A Standardized Position"

Python
from mne.transforms import translation
mf_destination = translation(z=0.04)

Pipeline steps using this setting

The following steps are directly affected by changes to mf_destination:

  • preprocessing/_03_maxfilter

mf_int_order module-attribute

Python
mf_int_order: int = 8

Internal order for the Maxwell basis. Can be set to something lower (e.g., 6 or higher for datasets where lower or higher spatial complexity, respectively, is expected.

Pipeline steps using this setting

The following steps are directly affected by changes to mf_int_order:

  • preprocessing/_03_maxfilter

mf_reference_run module-attribute

Python
mf_reference_run: str | None = None

Which run to take as the reference for adjusting the head position of all runs when mf_destination="reference_run". If None, pick the first run.

Example
Python
mf_reference_run = '01'  # Use run "01"

mf_cal_fname module-attribute

Python
mf_cal_fname: str | None = None

Warning

This parameter should only be used for BIDS datasets that don't store the fine-calibration file according to BIDS.

Path to the Maxwell Filter calibration file. If None, the recommended location is used.

Example
Python
mf_cal_fname = '/path/to/your/file/calibration_cal.dat'
Pipeline steps using this setting

The following steps are directly affected by changes to mf_cal_fname:

  • preprocessing/_01_data_quality
  • preprocessing/_03_maxfilter

mf_ctc_fname module-attribute

Python
mf_ctc_fname: str | None = None

Path to the Maxwell Filter cross-talk file. If None, the recommended location is used.

Warning

This parameter should only be used for BIDS datasets that don't store the cross-talk file according to BIDS.

Example
Python
mf_ctc_fname = '/path/to/your/file/crosstalk_ct.fif'
Pipeline steps using this setting

The following steps are directly affected by changes to mf_ctc_fname:

  • preprocessing/_01_data_quality
  • preprocessing/_03_maxfilter

mf_esss module-attribute

Python
mf_esss: int = 0

Number of extended SSS (eSSS) basis projectors to use from empty-room data.

Pipeline steps using this setting

The following steps are directly affected by changes to mf_esss:

  • preprocessing/_03_maxfilter

mf_esss_reject module-attribute

Python
mf_esss_reject: dict[str, float] | None = None

Rejection parameters to use when computing the extended SSS (eSSS) basis.

Pipeline steps using this setting

The following steps are directly affected by changes to mf_esss_reject:

  • preprocessing/_03_maxfilter

mf_mc module-attribute

Python
mf_mc: bool = False

If True, perform movement compensation on the data.

Pipeline steps using this setting

The following steps are directly affected by changes to mf_mc:

  • preprocessing/_02_head_pos
  • preprocessing/_03_maxfilter

mf_mc_t_step_min module-attribute

Python
mf_mc_t_step_min: float = 0.01

Minimum time step to use during cHPI coil amplitude estimation.

Pipeline steps using this setting

The following steps are directly affected by changes to mf_mc_t_step_min:

  • preprocessing/_02_head_pos

mf_mc_t_window module-attribute

Python
mf_mc_t_window: float | Literal['auto'] = 'auto'

The window to use during cHPI coil amplitude estimation and in cHPI filtering. Can be "auto" to autodetect a reasonable value or a float (in seconds).

Pipeline steps using this setting

The following steps are directly affected by changes to mf_mc_t_window:

  • preprocessing/_02_head_pos
  • preprocessing/_03_maxfilter

mf_mc_gof_limit module-attribute

Python
mf_mc_gof_limit: float = 0.98

Minimum goodness of fit to accept for each cHPI coil.

Pipeline steps using this setting

The following steps are directly affected by changes to mf_mc_gof_limit:

  • preprocessing/_02_head_pos

mf_mc_dist_limit module-attribute

Python
mf_mc_dist_limit: float = 0.005

Minimum distance (m) to accept for cHPI position fitting.

Pipeline steps using this setting

The following steps are directly affected by changes to mf_mc_dist_limit:

  • preprocessing/_02_head_pos

mf_mc_rotation_velocity_limit module-attribute

Python
mf_mc_rotation_velocity_limit: float | None = None

The rotation velocity limit (degrees/second) to use when annotating movement-compensated data. If None, no annotations will be added.

Pipeline steps using this setting

The following steps are directly affected by changes to mf_mc_rotation_velocity_limit:

  • preprocessing/_03_maxfilter

mf_mc_translation_velocity_limit module-attribute

Python
mf_mc_translation_velocity_limit: float | None = None

The translation velocity limit (meters/second) to use when annotating movement-compensated data. If None, no annotations will be added.

Pipeline steps using this setting

The following steps are directly affected by changes to mf_mc_translation_velocity_limit:

  • preprocessing/_03_maxfilter

mf_filter_chpi module-attribute

Python
mf_filter_chpi: bool | None = None

Use mne.chpi.filter_chpi after Maxwell filtering. Can be None to use the same value as mf_mc. Only used when use_maxwell_filter=True

Pipeline steps using this setting

The following steps are directly affected by changes to mf_filter_chpi:

  • preprocessing/_03_maxfilter