meeg_utils.qc.HeadMovement

class meeg_utils.qc.HeadMovement(*, head_pos=None, warn_mm=None, origin=(0.0, 0.0, 0.04), gof_limit=0.98, dist_limit=0.005, min_good_fraction=0.9, weighted=False)

Head movement during an MEG recording, from continuous head localization.

Head positions are estimated from the cHPI coils with MNE (mne.chpi.compute_chpi_amplitudes(), compute_chpi_locs() and compute_head_pos() for Neuromag; extract_chpi_locs_ctf() for CTF), or read from a head-position file (e.g. MaxFilter’s .pos). Movement is the displacement of origin relative to the sensors, compared with the head position in info["dev_head_t"] (the one source analysis uses).

Parameters:

• head_pos (str | Path | ndarray | None) – Precomputed head positions (.pos file or array of shape (n, 10)); None estimates them from the cHPI signals.

• warn_mm (float | None) – Maximum displacement that is flagged. There is no formal standard and the acceptable movement depends on the participants (children and patients move more) and on whether movement is compensated later; 5 mm is a common exclusion or movement-correction criterion. None (default) reports the displacement without a verdict.

• origin (tuple of float) – Point (head frame, m) whose displacement is measured.

• gof_limit (float) – Coil fits with a goodness of fit below gof_limit or further than dist_limit (m) from their digitized position are not used (MNE defaults 0.98 and 0.005).

• dist_limit (float) – Coil fits with a goodness of fit below gof_limit or further than dist_limit (m) from their digitized position are not used (MNE defaults 0.98 and 0.005).

• min_good_fraction (float) – A coil with good fits in less than this fraction of the time is flagged (loose, off, or not digitized correctly).

• weighted (bool) – Weight coil fits by their goodness of fit (MNE’s current default, False).

metrics_

max_displacement_mm, median_displacement_mm, fraction_above (of time above warn_mm, when set), max_rotation_deg, n_positions and, when estimated from cHPI, coil_good_fraction.

Type:

dict

Notes

Figures: "positions" (mne.viz.plot_head_positions(), relative to dev_head_t) and "displacement" (displacement over time).

__init__(*, head_pos=None, warn_mm=None, origin=(0.0, 0.0, 0.04), gof_limit=0.98, dist_limit=0.005, min_good_fraction=0.9, weighted=False)

Methods

__init__(*[, head_pos, warn_mm, origin, ...])
compute(raw)	Measure the recording.
get_metadata_routing()	Get metadata routing of this object.
get_params([deep])	Get parameters for this estimator.
not_applicable(raw)	Return why the check cannot run on raw, or None if it can.
plot([kind, inst])	Draw quality-control figures.
set_params(**params)	Set the parameters of this estimator.

Attributes

level	The worst verdict of the findings ("ok" if there are none).
modalities	Data types the check needs at least one of ("meg", "eeg").
name	Key of the check in reports.
plot_kinds	kind -> whether it needs data (inst).
systems	Acquisition systems the check applies to; None means all.

name: ClassVar[str] = 'head_movement'

Key of the check in reports.

modalities: ClassVar[frozenset[str]] = frozenset({'meg'})

Data types the check needs at least one of (“meg”, “eeg”).

plot_kinds: ClassVar[dict[str, bool]] = {'displacement': False, 'positions': 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

not_applicable(raw)

Return why the check cannot run on raw, or None if it can.

Parameters:

raw (Raw) – The recording.

Returns:

The reason, or None.

Return type:

str | None