Maxwell filter data using multipole moments.
mne.io.Raw
Data to be filtered.
Warning
It is critical to mark bad channels in
raw.info['bads']
prior to processing in order to
prevent artifact spreading. Manual inspection and use
of find_bad_channels_maxwell()
is recommended.
str
Origin of internal and external multipolar moment space in meters.
The default is 'auto'
, which means (0., 0., 0.)
when
coord_frame='meg'
, and a head-digitization-based
origin fit using fit_sphere_to_headshape()
when coord_frame='head'
. 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.
int
Order of internal component of spherical expansion.
int
Order of external component of spherical expansion.
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.
str
| None
Path to the FIF file with cross-talk correction information.
float
| None
If not None, apply spatiotemporal SSS 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_duration 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.
float
Correlation limit between inner and outer subspaces used to reject ovwrlapping intersecting inner/outer signals during spatiotemporal SSS.
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.
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).
str
| None
Basis regularization type, must be “in” or None. “in” is the same algorithm as the “-regularize in” option in MaxFilter™.
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.
str
How to deal with ill-conditioned SSS matrices. Can be “error” (default), “warning”, “info”, or “ignore”.
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.
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.
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 output 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
average_movements()
.
New in version 0.12.
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.
str
| list
of str
If a string (or list of str), any annotation segment that begins
with the given string will not be included in filtering, and
segments on either side of the given excluded annotated segment
will be filtered separately (i.e., as independent signals).
The default ('edge', 'bad_acq_skip')
will separately filter
any segments that were concatenated by mne.concatenate_raws()
or mne.io.Raw.append()
, or separated during acquisition.
To disable, provide an empty list.
New in version 0.17.
list
The empty-room projection vectors used to extend the external SSS basis (i.e., use eSSS).
New in version 0.21.
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.
mne.io.Raw
The raw data with Maxwell filtering applied.
See also
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 [1] and [2]. It will likely use multiple CPU cores, see the FAQ for more information.
Warning
Maxwell filtering in MNE is not designed or certified for clinical use.
Compared to the MEGIN MaxFilter™ software, the MNE Maxwell filtering routines currently provide the following features:
Feature |
MNE |
MaxFilter |
---|---|---|
Maxwell filtering software shielding |
✓ |
✓ |
Bad channel reconstruction |
✓ |
✓ |
Cross-talk cancellation |
✓ |
✓ |
Fine calibration correction (1D) |
✓ |
✓ |
Fine calibration correction (3D) |
✓ |
|
Spatio-temporal SSS (tSSS) |
✓ |
✓ |
Coordinate frame translation |
✓ |
✓ |
Regularization using information theory |
✓ |
✓ |
Movement compensation (raw) |
✓ |
✓ |
Movement compensation ( |
✓ |
|
✓ |
✓ |
|
Double floating point precision |
✓ |
|
Seamless processing of split ( |
✓ |
|
Automatic bad channel detection ( |
✓ |
✓ |
Head position estimation ( |
✓ |
✓ |
Certified for clinical use |
✓ |
|
Extended external basis (eSSS) |
✓ |
Epoch-based movement compensation is described in [1].
Use of Maxwell filtering routines with non-Neuromag systems is currently experimental. Worse results for non-Neuromag 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 MEGIN. 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
mne.preprocessing.maxwell_filter
#Extracting and visualizing subject head movement
Signal-space separation (SSS) and Maxwell filtering
Brainstorm CTF phantom dataset tutorial
Maxwell filter data with movement compensation