Stage 12: Manual MEG-MRI coregistration

Author: Hadi Zaatiti <hadi.zaatiti@nyu.edu>

What & why

Stage 12 of the KIT general pipeline aligns the MEG head coordinate frame of a subject with the MRI of that subject (or with the fsaverage template) and saves the result as the -trans.fif transform that the forward model of stage 14 needs. Without it, the source space and the BEM built on the FreeSurfer surfaces cannot be placed under the sensors.

The alignment is done by a person in MNE’s coregistration GUI (mne.gui.coregistration), one subject at a time: set the three MRI fiducials (nasion, LPA, RPA) on the scalp surface, fit them to the digitised fiducials, refine the fit with the digitised head-shape points (ICP), inspect, and save. Like stage 2, the pipeline only prepares and records: it opens the GUI preloaded with the right files, verifies what was saved, computes quality assurance distances after each transform, and keeps one row per subject across runs. No decision is taken by the QA.

Stage 12 uses an individual MRI only after stage 11 recorded a pass or pass_with_note verdict for it (coregistration.require_mri_qc, default true). Stage 13 (automatic template coregistration, no GUI) covers the subjects that stage 12 has not served yet; a complete stage-12 transform always takes precedence downstream.

What you need to provide

  • A stage-2 FIF of the subject with its digitisation (fiducials, HPI coils and head-shape points). The first FIF of the subject in the stage-2 folder is the coregistration instance; restrict bids_selection (task, session) to choose another one. One transform per subject is enough: the digitised head shape is the same for every recording of a session.

  • For an individual MRI: the stage-10 reconstruction with the bem/<subject>-head-dense.fif scalp surface written by stage 11, and a stage-11 verdict of pass or pass_with_note.

  • For the template: nothing. fsaverage is taken from the FreeSurfer installation when the GUI can read it, otherwise fetched by MNE into 12-kit_mri_coreg/subjects/fsaverage.

  • A desktop session with OpenGL for the GUI (PySide6, pyvistaqt).

Which MRI is used per subject

  • individual reconstruction when stage 11 recorded pass or pass_with_note on the current files;

  • fsaverage when the subject has no T1w and freesurfer.missing_anat is fsaverage, or when the stage-11 verdict is use_fsaverage;

  • otherwise the subject is skipped with the reason: recon_incomplete (stage 10 not finished), verdict pending or stale (run stage 11), fail_needs_edit (blocked: fix the reconstruction), or no T1w with missing_anat: error.

Configuration file

coregistration:
  require_mri_qc: true   # individual MRIs need a stage-11 verdict of pass or pass_with_note
  save_plots: true       # 3-D QA figure (scalp, head-shape points coloured by distance, sensors)
  automatic: ...         # stage 13, see the source analysis page

freesurfer:
  missing_anat: fsaverage   # template for subjects without a T1w; error = stop

How to run

conda activate neurowaves
python -m pipeline.mne_pipelines.kit_general_pipelines.12-kit_mri_coreg \
    -c pipeline/mne_pipelines/kit_general_pipelines/pipeline_config_files/<project>_config.yml

Options:

  • --redo: open the GUI again for subjects whose transform is verified (otherwise a verified transform is reused without the GUI).

  • --qa-only: do not open any GUI; recompute the QA distances and figures of the existing transforms.

  • --no-plots: skip the QA figures.

The VS Code launch entries are <project> 12 MRI coregistration (MNE GUI) and ... QA figures only.

The GUI in practice

Before each window the stage prints the MRI subject, the numbered steps below and the path the transform must be saved to. The same steps open in a help window beside the GUI, with a Copy transform path button and a live status line (transform and MRI fiducials: not saved / saved earlier / saved in this session). The GUI’s transform Save… dialog is pre-filled with the file name the pipeline reads, so accepting it is enough. In the window:

  1. MRI fiducials (individual MRIs): untick Lock fiducials, place the nasion, LPA and RPA on the scalp surface (the depressions at the preauricular points, the bridge of the nose), tick Lock fiducials again, then press Save MRI Fid.; they are written to bem/<subject>-fiducials.fif and reloaded on the next run. For fsaverage the template fiducials are used; do not overwrite them.

  2. Fit fiducials: aligns the three digitised fiducials with the three MRI fiducials.

  3. Fit ICP: refines the alignment with the digitised head-shape points. Points far from the scalp (hair, a cap) can be omitted with Omit and a distance; refit.

  4. Inspect from several sides: the head-shape points should sit on the scalp surface, the fiducials close to their MRI counterparts, the sensors around the head. Leave Scaling Mode at None: the transform file stores rotation and translation only, and the later stages use the unscaled MRI named in the summary. A scaled template is made by the automatic coregistration (stage 13) instead.

  5. Under HEAD <> MRI Transform press Save… and keep the pre-filled name (<derivatives>/12-kit_mri_coreg/sub-<id>/sub-<id>-trans.fif). Saving the MRI fiducials does not save the transform; both are needed. Closing the window without saving records nothing.

The manual walkthrough page (Kit2Fiff and coregistration GUIs: manual walkthrough) shows the controls of this GUI.

What the script does

Per selected subject:

  1. Choose the MRI (rules above) and the coregistration instance FIF.

  2. If a transform exists and --redo is not given, compare its provenance with the current files: instance FIF, T1.mgz, recon-all.done, the dense head surface and the stage-11 verdict. All equal: action: reused, no GUI. Anything differs: the GUI opens again (the old transform is kept on disk until a new one is saved).

  3. Open the GUI with the instance FIF, the MRI subject and its SUBJECTS_DIR; wait for it to close; check that the transform was saved (gui_saved) or that the previous one was kept (gui_kept).

  4. QA after every saved or reused transform: distances from each digitised head-shape point to the scalp (mne.dig_mri_distances; MNE documents 2 to 3 mm on average for a good fit), the distances between the digitised fiducials and the saved MRI fiducials, and a 3-D figure of the scalp with the head-shape points coloured by distance and the MEG sensors.

  5. Write the provenance sidecar and the summary row.

Outputs

Under <bids_root>/derivatives/12-kit_mri_coreg/:

coreg_summary.csv
configs/config_<timestamp>.yml
subjects/fsaverage/                   # template copy when the FreeSurfer one is unreadable
sub-<id>/
  sub-<id>-trans.fif                  # saved from the GUI
  sub-<id>-trans.json                 # provenance and QA distances
  figures/sub-<id>_desc-coregqa.png
../10-freesurfer_reconstruction/subjects/sub-<id>/bem/sub-<id>-fiducials.fif   # saved MRI fiducials

coreg_summary.csv has one row per subject, merged across runs: subject, mri_source (individual | fsaverage), mri_subject, mri_qc_status, mri_qc_verdict, inst_fif, trans_fif, status (complete | incomplete | blocked | failed), action (gui_saved | gui_kept | reused | qa_only), message, mri_fiducials (saved | estimated (not saved)), n_headshape_points, dist_mean_mm, dist_median_mm, dist_p95_mm, dist_max_mm, n_points_over_5mm, nasion_err_mm, lpa_err_mm, rpa_err_mm, qa_figure, mne_version, config_snapshot and trans_provenance.

Report

The report’s stage-12 section shows the summary with the QA distances, cohort statistics of the median head-shape distance, and per subject the QA figure. The pipeline console shows per subject the status and the median distance in its stage-12 column.

Edge cases & safeguards

  • Reconstruction changed after the transform (stage 10 rerun, edits): the provenance no longer matches, the GUI opens again; the saved MRI fiducials are reloaded so only the fit has to be redone.

  • Several FIFs for a subject: the first one is used and a warning names it; the head shape is identical across the recordings of a session, so any of them serves, but keep the choice stable across runs (restrict bids_selection).

  • Template subjects: save a distinct sub-<id>-trans.fif per MEG subject; never reuse one subject’s transform for another, and never overwrite the fsaverage fiducials. Do not scale the template in this GUI: a scaled subject saved from it is not used by the later stages (use stage 13 for scaled templates).

  • Large head-shape distances (median well above 3 mm, many points over 5 mm): the fit is poor or the scalp surface is clipped (stage 11 coverage figure). Omit the outlying points and refit; for a child on the template, prefer the scaled automatic coregistration (stage 13). The QA does not block, the reviewer decides.

  • Verdict given after the transform: a transform saved while the stage-11 verdict was pending is marked for redo when the verdict is recorded, since the verdict is part of the provenance.

Troubleshooting

  • ``the stage 11 verdict is still pending``: run stage 11 and record a verdict for the subject.

  • ``<subject>-head-dense.fif is missing``: run stage 11 (it writes the MNE scalp surfaces).

  • GUI opens with no MRI: the FreeSurfer SUBJECTS_DIR is not readable from Windows (WSL path); the stage copies fsaverage but an individual reconstruction must be reachable, for example through \\wsl$\... or a freesurfer.subjects_dir on a Windows drive.

  • No transform after closing: the window was closed without Save… or the file was saved under another name or folder (the status line in the help window shows whether the expected file was written); rerun the stage (action stays gui_kept or incomplete).

  • Fiducials not saved: mri_fiducials: estimated (not saved); open with --redo and press Save MRI Fid. before saving the transform, so the next run reloads them.