Kit2Fiff and coregistration GUIs: manual walkthrough

This page shows what the two MNE graphical tools used by the KIT general pipeline look like and how to operate them by hand. In the pipeline they are opened for you:

  • the KIT-to-FIFF GUI by 2-kit_con_to_fif.py (stage 2), preloaded with the CON, MRK, head-shape and digitizer-point files of each recording and a pre-filled output path;

  • the coregistration GUI (mne.gui.coregistration) by 12-kit_mri_coreg.py (stage 12), preloaded with the subject’s FreeSurfer reconstruction (stage 10, approved in the stage 11 review) or the fsaverage template.

Use the pipeline scripts for real datasets so that the outputs, summaries and report stay consistent. The manual commands below are useful for a quick look at a single recording or for learning the controls.

Note

Both GUIs come from the neurowaves Conda environment (mne-base, mne-kit-gui 2.x, PySide6, PyVista). Activate it before running any command on this page. The legacy Mayavi/Traits KIT GUI (1.x) is not installed and is not needed.

Files produced before and during a KIT acquisition that are used here:

  • laser head scan, basic surface .txt (acq-head_headshape.txt in BIDS)

  • laser head scan, stylus points .txt (acq-points_headshape.txt)

  • HPI coil marker measurements .mrk (two or more; each holds the position of the 5 coils)

  • the MEG recording .con

Kit2Fiff

kit2fiff converts .con/.sqd recordings to the .fif format used by MNE. The command-line entry point is mne kit2fiff (mne.commands.mne_kit2fiff); the pipeline’s manual stage calls the same GUI class from mne_kit_gui.

  1. Open a terminal and activate the environment: conda activate neurowaves.

  2. Run mne kit2fiff. A window with the following interface opens:

  3. Using the diagram here as a guide, load the files listed above:

KIT-to-FIFF GUI with the source file slots

After the files are loaded, the head scan is plotted in the grey panel in the middle of the GUI. Rotate it and check that the markers sit in their expected positions around the head.

Note

The parameters circled in red below must match the experiment-control software.

KIT-to-FIFF GUI event detection parameters

For experiments run in PsychoPy the events should be indicated as “Trough”, and for experiments run in Presentation as “Peak” (in the pipeline YAML this is kit2fiff.slope: "-" or "+"). Click “Find Events”. If a list of events appears, triggers were recorded. If not, check the parameters in red; if that does not fix it, the triggers were not sent properly.

  1. Save the file with “Save FIFF”. When launched from the pipeline the path is pre-filled and follows the BIDS derivative naming (..._desc-rawkit_raw.fif); accept it. When running the GUI by hand, MNE suggests a filename; a useful convention is sub-<id>_task-<task>_desc-rawkit_raw.fif.

  2. When the .fif has been saved, close the GUI.

Coreg with the subject’s own MRI

Stage 12 (12-kit_mri_coreg.py) opens this GUI with the right SUBJECTS_DIR and digitisation source for each subject. A subject with a T1w uses its own reconstruction once stage 11 recorded pass or pass_with_note; the scalp surface the GUI shows is bem/sub-<id>-head-dense.fif (from mkheadsurf in stage 10 and make_scalp_surfaces in stage 11). The steps are printed in the console and shown in a help window beside the GUI, with the transform path and a live save status.

  1. In the MRI fiducials panel, untick Lock fiducials, check LPA, nasion and RPA on the MRI (MNE estimates them from the Talairach transform until they are saved) and correct them by clicking on the head; tick Lock fiducials and press Save MRI Fid. (bem/sub-<id>-fiducials.fif).

  2. Press Fit fiducials, then Fit ICP (again until stable). Do not scale an individual MRI.

  3. Check the fit by rotating the head; omit points that are far from the surface only when they are clearly digitisation errors.

  4. Under HEAD <> MRI Transform press Save…; the dialog is pre-filled with the path stage 12 reads (derivatives/12-kit_mri_coreg/sub-<id>/ sub-<id>-trans.fif). Keep it, then close the GUI. The fiducials file alone is not the transform.

Stage 12 then reports the distance of every head-shape point to the scalp, the distance between the digitised and MRI fiducials, and a 3-D QA figure.

Coreg without native MRI

Subjects without a T1w (or with a use_fsaverage verdict in stage 11) are coregistered to fsaverage. In stage 12 keep Scaling Mode at None (the saved transform holds no scaling and the later stages use the unscaled template); use stage 13 for a scaled template. The scaling steps below apply only to a hand-run session outside the pipeline. To open it by hand, run mne coreg in the activated environment; the interface looks like this:

MNE coregistration GUI

  1. Navigate to the MRI folder (SUBJECTS_DIR) at the spot indicated by the blue arrow. If this is the first coregistration for the dataset, the fsaverage folder must be present there to serve as the template for subjects without an MRI (stage 12 fetches a copy under derivatives/12-kit_mri_coreg/subjects/fsaverage when needed).

  2. In Digitization Source, load the .fif created earlier for the subject.

Note

This part of the preprocessing takes the most subjective judgement.

You need to align the white net of dots (the digitised head shape stored in the MEG recording) with the fsaverage head surface. Two groups of controls do this: translation/rotation of the digitised points (blue) and scaling of the template head (red). Current versions of MNE fit the translation automatically with “Fit (ICP)” and “Fit Fid.”: Fit (ICP) fits the white dots to the surface, Fit Fid. fits the digitised fiducials to the template fiducials. Alternate with scaling of the template: first set Scaling mode to “3-axis” so the head can be scaled independently along the three axes, then press Fit (ICP) in the red group.

Note

If a subject had a particularly thick hairstyle, add hair thickness (in mm) in the green field. You can also omit white dots that are too far from the surface, which occasionally result from a bad head scan.

  1. Make sure the base is always fsaverage for template-based coregistration: if other processed subjects already live in the MRI folder, the GUI may preselect one of them in the dropdown below the folder selector.

  2. Iterate: Fit (ICP), adjust scaling, Fit (ICP) again, until the net lies flush with the surface.

Coregistration GUI fit controls

  1. Check the fit by rotating the head in the grey panel. The goal is a white net lying on the surface of the head with minimal gaps and minimal embedding of the dots inside the surface. Do not worry about the point marked by the black arrow below: it belongs to the neck brace, not to the head.

Coregistration result with neck brace point

  1. When satisfied with the fit, hit Save. With a scaled template this produces the scaled MRI, BEM and anatomical files and takes some time; in all cases it writes the -trans.fif that maps the MRI to the MEG head coordinates. When launched from stage 12, save one sub-<id>-trans.fif per MEG subject under derivatives/12-kit_mri_coreg/sub-<id>/; never overwrite the shared template fiducials.

  2. Close the GUI. Stage 12 then records the saved transform in coreg_summary.csv.

Quick checks:

  • a recording still needs Kit2Fiff if there is no ..._desc-rawkit_raw.fif for it in the stage-2 derivatives folder (kit2fiff_summary.csv lists the current ones);

  • a subject still needs coregistration if there is no sub-<id>-trans.fif under derivatives/12-kit_mri_coreg/sub-<id>/.

Suggested fit sequence:

  1. Fit (ICP)

  2. Scaling mode = 3-axis

  3. Fit (ICP) with scaling

  4. Alternate the two fits until stable

  5. Screenshot all five views for the coregistration report