meeg_utils.steps.HeadAlign#

class meeg_utils.steps.HeadAlign(destination, *, origin='auto', mode='accurate')[source]#

Map MEG data to a common head position (device-to-head transform).

Different runs of a session rarely share the head position, so the same brain source projects onto different sensors. This step computes, from the sensor geometry alone, what the sensors would have measured with the head at destination (minimum-norm field mapping in a spherical harmonic basis; Knösche, 2002, NeuroImage 17:1307), applies it to the good MEG channels and sets info["dev_head_t"] to the destination.

For Neuromag data, Maxwell filtering with a destination (mne.preprocessing.maxwell_filter()) is the usual alternative; this step works for any MEG system with a head transform (CTF, KIT, BTi, Neuromag, …) but not for on-head OPM arrays, whose sensors move with the head.

Parameters:

  • destination (str | path-like | array, shape (4, 4) | Transform | dict) – The head position to map to, as a device-to-head transform, or a FIF file (or any recording MNE can read) whose dev_head_t is used. For several runs, a common choice is the average over runs, see meeg_utils.io.average_dev_head_t().

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

  • mode ({"accurate", "fast"}) – Accuracy of the Legendre expansion used for the field mapping.

mapping_#

The mapping from the measured to the destination sensor positions.

Type:

ndarray, shape (n_good_meg, n_good_meg)

picks_#

Indices of the mapped channels (good MEG channels; reference channels and bad channels are left unchanged).

Type:

ndarray

dev_head_t_#

The destination transform.

Type:

Transform

qc_#

shift_mm (displacement of the head origin relative to the sensors), rotation_deg, n_channels and unmapped_bads.

Type:

dict

Notes

  • Bad channels are not mapped and stay marked bad; interpolating them afterwards (Interpolate) uses the destination geometry.

  • CTF data are mapped in their current compensation grade, as MNE does for bad-channel interpolation; reference sensors are unchanged.

  • SSP projectors are kept; compute new ones after alignment if they depend on the head position.

  • A fitted step only transforms data recorded at the same head position with the same channels (normally the data it was fitted on).

Figures (plot()): "positions" (sensor positions relative to the head before and after, in three views).

__init__(destination, *, origin='auto', mode='accurate')[source]#

Methods

__init__(destination, *[, origin, mode])

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'>, <class 'mne.epochs.BaseEpochs'>, <class 'mne.evoked.Evoked'>)#

Data types the step accepts.

systems: ClassVar[frozenset[str] | None] = frozenset({'artemis123', 'bti', 'ctf', 'kit', 'meg-other', 'neuromag'})#

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

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