mne.preprocessing.compute_maxwell_basis#

mne.preprocessing.compute_maxwell_basis(info, origin='auto', int_order=8, ext_order=3, calibration=None, coord_frame='head', regularize='in', ignore_ref=True, bad_condition='error', mag_scale=100.0, extended_proj=(), verbose=None)[source]#

Compute the SSS basis for a given measurement info structure.

Parameters:

infomne.Info

The mne.Info object with information about the sensors and methods of measurement.

originarray_like, shape (3,) | 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_orderint

Order of internal component of spherical expansion.

ext_orderint

Order of external component of spherical expansion.

calibrationstr | 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.

coord_framestr

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.

regularizestr | None

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

ignore_refbool

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_conditionstr

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

mag_scalefloat | 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).

extended_projlist

The empty-room projection vectors used to extend the external SSS basis (i.e., use eSSS). You can use any SSP projections that contain pure external noise that you expect to be present in your signal. Typically, this should be the case during an empty room recording. Get the projections e.g. by calling:

proj = mne.compute_proj_raw(
    raw_empty_room.pick('meg'), n_grad=3, n_mag=3, meg="combined"
)

New in v0.21.

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:

Sndarray, shape (n_meg, n_moments): The basis that can be used to reconstruct the data.
pSndarray, shape (n_moments, n_good_meg): The (stabilized) pseudoinverse of the S array.
reg_momentsndarray, shape (n_moments,): The moments that were kept after regularization.
n_use_inint: The number of kept moments that were in the internal space.

Notes

This outputs variants of \(\mathbf{S}\) and \(\mathbf{S^\dagger}\) from equations 27 and 37 of [1] with the coil scale for magnetometers already factored in so that the resulting denoising transform of the data to obtain \(\hat{\phi}_{in}\) from equation 38 would be:

phi_in = S[:, :n_use_in] @ pS[:n_use_in] @ data_meg_good

New in v0.23.

References