mne.preprocessing.maxwell_filter¶

mne.preprocessing.maxwell_filter(raw, origin=’auto’, int_order=8, ext_order=3, calibration=None, cross_talk=None, st_duration=None, st_correlation=0.98, coord_frame=’head’, destination=None, regularize=’in’, ignore_ref=False, bad_condition=’error’, head_pos=None, st_fixed=True, st_only=False, mag_scale=100.0, verbose=None)[source]¶

Apply Maxwell filter to data using multipole moments.

Warning

Automatic bad channel detection is not currently implemented. It is critical to mark bad channels before running Maxwell filtering to prevent artifact spreading.

Warning

Maxwell filtering in MNE is not designed or certified for clinical use.

Parameters:

Parameters:	raw : instance of mne.io.Raw Data to be filtered origin : array-like, shape (3,) \| str Origin of internal and external multipolar moment space in meters. The default is `'auto'`, which means a head-digitization-based origin fit when `coord_frame='head'`, and `(0., 0., 0.)` when `coord_frame='meg'`. int_order : int Order of internal component of spherical expansion. ext_order : int Order of external component of spherical expansion. calibration : str \| None Path to the `'.dat'` file with fine calibration coefficients. File can have 1D or 3D gradiometer imbalance correction. This file is machine/site-specific. cross_talk : str \| None Path to the FIF file with cross-talk correction information. st_duration : float \| None If not None, apply spatiotemporal SSS with specified buffer duration (in seconds). Elekta’s default is 10.0 seconds in MaxFilter™ 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. st_correlation : float Correlation limit between inner and outer subspaces used to reject ovwrlapping intersecting inner/outer signals during spatiotemporal SSS. coord_frame : str The coordinate frame that the `origin` is specified in, either `'meg'` or `'head'`. For empty-room recordings that do not have a head<->meg transform `info['dev_head_t']`, the MEG coordinate frame should be used. destination : str \| array-like, shape (3,) \| None The destination location for the head. Can be `None`, which will not change the head position, or a string path to a FIF file containing a MEG device<->head transformation, or a 3-element array giving the coordinates to translate to (with no rotations). For example, `destination=(0, 0, 0.04)` would translate the bases as `--trans default` would in MaxFilter™ (i.e., to the default head location). regularize : str \| None Basis regularization type, must be “in” or None. “in” is the same algorithm as the “-regularize in” option in MaxFilter™. ignore_ref : bool If True, do not include reference channels in compensation. This option should be True for KIT files, since Maxwell filtering with reference channels is not currently supported. bad_condition : str How to deal with ill-conditioned SSS matrices. Can be “error” (default), “warning”, or “ignore”. head_pos : array \| None If array, movement compensation will be performed. The array should be of shape (N, 10), holding the position parameters as returned by e.g. read_head_pos. New in version 0.12. st_fixed : bool If True (default), do tSSS using the median head position during the `st_duration` window. This is the default behavior of MaxFilter and has been most extensively tested. New in version 0.12. st_only : bool If True, only tSSS (temporal) projection of MEG data will be performed on the output data. The non-tSSS parameters (e.g., `int_order`, `calibration`, `head_pos`, etc.) will still be used to form the SSS bases used to calculate temporal projectors, but the ouptut MEG data will only have temporal projections performed. Noise reduction from SSS basis multiplication, cross-talk cancellation, movement compensation, and so forth will not be applied to the data. This is useful, for example, when evoked movement compensation will be performed with `mne.epochs.average_movements()`. New in version 0.12. mag_scale : float \| str The magenetometer scale-factor used to bring the magnetometers to approximately the same order of magnitude as the gradiometers (default 100.), as they have different units (T vs T/m). Can be `'auto'` to use the reciprocal of the physical distance between the gradiometer pickup loops (e.g., 0.0168 m yields 59.5 for VectorView). New in version 0.13. verbose : bool, str, int, or None If not None, override default verbose level (see `mne.verbose()` and Logging documentation for more).
Returns:	raw_sss : instance of mne.io.Raw The raw data with Maxwell filtering applied.

raw : instance of mne.io.Raw

Data to be filtered

origin : array-like, shape (3,) | str

Origin of internal and external multipolar moment space in meters. The default is 'auto', which means a head-digitization-based origin fit when coord_frame='head', and (0., 0., 0.) when coord_frame='meg'.

int_order : int

Order of internal component of spherical expansion.

ext_order : int

Order of external component of spherical expansion.

calibration : str | None

Path to the '.dat' file with fine calibration coefficients. File can have 1D or 3D gradiometer imbalance correction. This file is machine/site-specific.

cross_talk : str | None

Path to the FIF file with cross-talk correction information.

st_duration : float | None

If not None, apply spatiotemporal SSS with specified buffer duration (in seconds). Elekta’s default is 10.0 seconds in MaxFilter™ 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.

st_correlation : float

Correlation limit between inner and outer subspaces used to reject ovwrlapping intersecting inner/outer signals during spatiotemporal SSS.

coord_frame : str

The coordinate frame that the origin is specified in, either 'meg' or 'head'. For empty-room recordings that do not have a head<->meg transform info['dev_head_t'], the MEG coordinate frame should be used.

destination : str | array-like, shape (3,) | None

The destination location for the head. Can be None, which will not change the head position, or a string path to a FIF file containing a MEG device<->head transformation, or a 3-element array giving the coordinates to translate to (with no rotations). For example, destination=(0, 0, 0.04) would translate the bases as --trans default would in MaxFilter™ (i.e., to the default head location).

regularize : str | None

Basis regularization type, must be “in” or None. “in” is the same algorithm as the “-regularize in” option in MaxFilter™.

ignore_ref : bool

If True, do not include reference channels in compensation. This option should be True for KIT files, since Maxwell filtering with reference channels is not currently supported.

bad_condition : str

How to deal with ill-conditioned SSS matrices. Can be “error” (default), “warning”, or “ignore”.

head_pos : array | None

If array, movement compensation will be performed. The array should be of shape (N, 10), holding the position parameters as returned by e.g. read_head_pos.

New in version 0.12.

st_fixed : bool

If True (default), do tSSS using the median head position during the st_duration window. This is the default behavior of MaxFilter and has been most extensively tested.

New in version 0.12.

st_only : bool

If True, only tSSS (temporal) projection of MEG data will be performed on the output data. The non-tSSS parameters (e.g., int_order, calibration, head_pos, etc.) will still be used to form the SSS bases used to calculate temporal projectors, but the ouptut MEG data will only have temporal projections performed. Noise reduction from SSS basis multiplication, cross-talk cancellation, movement compensation, and so forth will not be applied to the data. This is useful, for example, when evoked movement compensation will be performed with mne.epochs.average_movements().

New in version 0.12.

mag_scale : float | str

The magenetometer scale-factor used to bring the magnetometers to approximately the same order of magnitude as the gradiometers (default 100.), as they have different units (T vs T/m). Can be 'auto' to use the reciprocal of the physical distance between the gradiometer pickup loops (e.g., 0.0168 m yields 59.5 for VectorView).

New in version 0.13.

verbose : bool, str, int, or None

If not None, override default verbose level (see mne.verbose() and Logging documentation for more).

Returns:

raw_sss : instance of mne.io.Raw

The raw data with Maxwell filtering applied.

Notes

New in version 0.11.

Some of this code was adapted and relicensed (with BSD form) with permission from Jussi Nurminen. These algorithms are based on work from [R53] and [R54].

Note

This code may use multiple CPU cores, see the FAQ for more information.

Compared to Elekta’s MaxFilter™ software, the MNE Maxwell filtering routines currently provide the following features:

Feature	MNE	MaxFilter
Maxwell filtering software shielding	X	X
Bad channel reconstruction	X	X
Cross-talk cancellation	X	X
Fine calibration correction (1D)	X	X
Fine calibration correction (3D)	X
Spatio-temporal SSS (tSSS)	X	X
Coordinate frame translation	X	X
Regularization using information theory	X	X
Movement compensation (raw)	X	X
Movement compensation (`epochs`)	X
`cHPI subtraction`	X	X
Double floating point precision	X
Seamless processing of split (`-1.fif`) and concatenated files	X
Certified for clinical use		X
Automatic bad channel detection		X
Head position estimation		X

Epoch-based movement compensation is described in [R53].

Use of Maxwell filtering routines with non-Elekta systems is currently experimental. Worse results for non-Elekta systems are expected due to (at least):

Missing fine-calibration and cross-talk cancellation data for other systems.

Processing with reference sensors has not been vetted.

Regularization of components may not work well for all systems.

Coil integration has not been optimized using Abramowitz/Stegun definitions.

Note

Various Maxwell filtering algorithm components are covered by patents owned by Elekta Oy, Helsinki, Finland. These patents include, but may not be limited to:

US2006031038 (Signal Space Separation)

US6876196 (Head position determination)

WO2005067789 (DC fields)

WO2005078467 (MaxShield)

WO2006114473 (Temporal Signal Space Separation)

These patents likely preclude the use of Maxwell filtering code in commercial applications. Consult a lawyer if necessary.

Currently, in order to perform Maxwell filtering, the raw data must not have any projectors applied. During Maxwell filtering, the spatial structure of the data is modified, so projectors are discarded (unless in st_only=True mode).

References

[R53]

(1, 2, 3)

Taulu S. and Kajola M. “Presentation of electromagnetic multichannel data: The signal space separation method,” Journal of Applied Physics, vol. 97, pp. 124905 1-10, 2005.

http://lib.tkk.fi/Diss/2008/isbn9789512295654/article2.pdf

[R54]

(1, 2)

Taulu S. and Simola J. “Spatiotemporal signal space separation method for rejecting nearby interference in MEG measurements,” Physics in Medicine and Biology, vol. 51, pp. 1759-1768, 2006.

http://lib.tkk.fi/Diss/2008/isbn9789512295654/article3.pdf

Examples using `mne.preprocessing.maxwell_filter`¶

Maxwell filter data with movement compensation

Artifact correction with Maxwell filter

Brainstorm CTF phantom tutorial dataset

Brainstorm Elekta phantom tutorial dataset

mne.preprocessing.maxwell_filter¶

Examples using mne.preprocessing.maxwell_filter¶

Examples using `mne.preprocessing.maxwell_filter`¶