meeg_utils.steps.Maxwell#

class meeg_utils.steps.Maxwell(*, st_duration=None, st_correlation=0.98, origin='auto', int_order=8, ext_order=3, cross_talk='auto', calibration='auto', head_pos=None, destination=None, coord_frame='head', regularize='in', remove_chpi=True, bad_condition='error', skip_by_annotation=('edge', 'bad_acq_skip'))[source]#

Signal space separation (SSS) and its temporal extension (tSSS).

Wraps mne.preprocessing.maxwell_filter() (Taulu & Kajola, 2005, J Appl Phys 97:124905; Taulu & Simola, 2006, Phys Med Biol 51:1759) for Neuromag/MEGIN systems:

  • external interference is removed and bad MEG channels are reconstructed, so mark them first (BadChannels with method="maxwell"): an unmarked noisy channel spreads its noise to every channel;

  • with st_duration, tSSS also removes interference from sources close to the sensors (e.g. dental work, stimulators);

  • with head_pos, the data are corrected for head movement;

  • with destination, the data are transformed to another head position, e.g. the average over runs (meeg_utils.io.average_dev_head_t()).

Parameters:

  • st_duration (float | None) – tSSS buffer length in seconds; None (default) applies SSS only. MaxFilter’s default is 10 s. The buffer must hold an even number of samples (MNE’s overlapping windows); the step says which duration to use otherwise.

  • st_correlation (float) – tSSS subspace correlation limit (MaxFilter default 0.98).

  • origin ("auto" | tuple of float) – Expansion origin (m) in coord_frame; "auto" fits a sphere to the head digitization (or uses (0, 0, 0.04) with a warning when there are no head-shape points).

  • int_order (int) – Orders of the internal and external expansions (defaults 8 and 3, as MaxFilter).

  • ext_order (int) – Orders of the internal and external expansions (defaults 8 and 3, as MaxFilter).

  • cross_talk ("auto" | str | path-like | None) – Cross-talk compensation and fine-calibration files. "auto" (default) finds them in the BIDS dataset of the recording and raises if they are missing; None filters without them, which leaves more residual interference.

  • calibration ("auto" | str | path-like | None) – Cross-talk compensation and fine-calibration files. "auto" (default) finds them in the BIDS dataset of the recording and raises if they are missing; None filters without them, which leaves more residual interference.

  • head_pos ("chpi" | str | path-like | ndarray | None) – Head positions for movement compensation: "chpi" estimates them from the cHPI coils (as meeg_utils.qc.HeadMovement does), a string or path reads a head-position file (MaxFilter .pos), an array of shape (n, 10) is used as is; None (default) applies no movement compensation.

  • destination (str | path-like | array, shape (4, 4) | Transform | None) – Head position to transform the data to (a device-to-head transform, or a recording whose dev_head_t is used). None keeps the recording’s dev_head_t (with head_pos: the initial position).

  • coord_frame ({"head", "meg"}) – Frame of the expansion. "meg" is for data without head digitization (e.g. empty-room recordings); head_pos and destination then cannot be used.

  • regularize ("in" | None) – Regularize the internal basis by information content (MaxFilter’s default) or not.

  • remove_chpi (bool) – If cHPI was on, subtract the coil signals (mne.chpi.filter_chpi()) after estimating head positions and before filtering. SSS does not remove them (the coils are inside the sensor array).

  • bad_condition ({"error", "warning", "info", "ignore"}) – What to do when the basis is ill conditioned.

  • skip_by_annotation (list of str) – Annotations whose segments are filtered separately (e.g. acquisition skips).

cross_talk_, calibration_

Files used.

Type:

str | None

head_pos_#

Head positions used for movement compensation in the last transform (MNE’s format, see mne.chpi.read_head_pos(); save them with mne.chpi.write_head_pos()). MNE adds them to the data as CHPI channels; this step drops those, so the channels are unchanged.

Type:

ndarray | None

qc_#

reconstructed (bad MEG channels rebuilt), n_basis (number of internal components kept), tsss, chpi_removed, projs_removed (MEG projectors dropped, as they no longer apply), per channel type power_change_db (broadband power after relative to before; strongly negative values mean much interference was removed), with head_pos the head movement (max_displacement_mm, …) and with destination the destination_shift_mm and destination_rotation_deg.

Type:

dict

psd_#

Per channel type, PSDs of the good channels before and after the last transform.

Type:

dict

Notes

Maxwell filtering lowers the rank of the MEG data to n_basis (typically 60-80); ICA lowers an integer n_components to the rank. Run it before filtering and resampling, as MaxFilter does.

Figures (plot()): "psd" (before and after) and, with head_pos, "head_positions" and "displacement".

__init__(*, st_duration=None, st_correlation=0.98, origin='auto', int_order=8, ext_order=3, cross_talk='auto', calibration='auto', head_pos=None, destination=None, coord_frame='head', regularize='in', remove_chpi=True, bad_condition='error', skip_by_annotation=('edge', 'bad_acq_skip'))[source]#

Methods

__init__(*[, st_duration, st_correlation, ...])

fit(inst[, y, system])

Learn the step's state from the data.

fit_transform(inst[, y, system, copy])

Fit the step on the data and transform the same data.

get_metadata_routing()

Get metadata routing of this object.

get_params([deep])

Get parameters for this estimator.

plot([kind, inst])

Draw quality-control figures.

set_fit_request(*[, inst, system])

Configure whether metadata should be requested to be passed to the fit method.

set_params(**params)

Set the parameters of this estimator.

set_transform_request(*[, copy, inst])

Configure whether metadata should be requested to be passed to the transform method.

transform(inst, *[, copy])

Apply the fitted step to the data.

Attributes

accepts

Data types the step accepts.

adds_annotations

Whether the step may add BAD_ annotations (existing ones are kept).

changes_channels

Whether the step may add, drop or reorder channels.

changes_times

Whether the step may change the time axis (e.g. resampling, cropping).

drops_epochs

Whether the step may drop epochs (e.g. artifact rejection).

plot_kinds

kind -> whether it needs data (inst).

returns

Data type the step returns; None means the same type as its input.

systems

Acquisition systems the step applies to; None means all systems.
accepts: ClassVar[tuple[type, ...]] = (<class 'mne.io.base.BaseRaw'>,)#

Data types the step accepts.

systems: ClassVar[frozenset[str] | None] = frozenset({'neuromag'})#

Acquisition systems the step applies to; None means all systems.

plot_kinds: ClassVar[dict[str, bool]] = {'displacement': False, 'head_positions': False, 'psd': False}#

kind -> whether it needs data (inst). Each kind is drawn by a _plot_<kind>(inst, **kwargs) method.

Type:

Figures the object can draw once fitted