Skip to content

BUG: Accept alternate CTF .hc head-coil descriptors - #14191

Merged
larsoner merged 2 commits into
mne-tools:mainfrom
neuromechanist:ctf-hc-coil-names
Aug 23, 2026
Merged

larsoner merged 2 commits into
mne-tools:mainfrom
neuromechanist:ctf-hc-coil-names

Conversation

@neuromechanist

Copy link
Copy Markdown
Contributor

Reference issue

Fixes #14190.

What does this implement/fix?

read_raw_ctf raises RuntimeError: Some of the mandatory HPI device-coordinate info was not there. on CTF datasets whose .hc spells the head coils Nasion, LPA, RPA rather than nasion, left ear, right ear. The coordinates are present and correct and every other part of the .hc parse succeeds; only the descriptor vocabulary differs, so every point gets kind = -1 and _make_ctf_coord_trans_set finds no LPA/RPA/NAS.

This does two things:

  1. Matches the descriptor line case-insensitively. The descriptor is free text emitted by the acquisition software and its capitalization varies.
  2. Adds lpa and rpa as aliases. These are a different vocabulary rather than a casing difference, so lower-casing alone does not fix them.

CTF's own reference reader is more permissive than this on both counts: readHc inside readCTFds.m reads the coil name positionally and does not check it against a vocabulary at all (MEGCoilLabel = strvcat('nasion','left ear','right ear') is declared at line 528 and never used), and it carries an explicit workaround for a stadard typo emitted by some Acq releases. I have kept the fixed vocabulary here rather than going positional, since that is a much larger behavioural change; this is the minimum that reads the affected files.

One judgement call worth flagging: I applied the lower-casing to the whole descriptor match, so measured, relative to dewar/relative to head and the Unable sentinel are now matched case-insensitively too, not just the coil names. That felt more coherent than leaving one of four lookups case-sensitive, but I am happy to narrow it to _kind_dict if you would rather keep the diff tighter.

Testing

test_hc_coil_name_variants copies the CTF testing dataset, rewrites only the three descriptor words in the .hc, and asserts that the resulting dev_head_t and every digitization point match a read of the untouched original. It is parametrized over Nasion/LPA/RPA and a mixed-case spelling. Both parametrizations fail on main with exactly the error from the issue and pass with this change; the rest of mne/io/ctf/tests/test_ctf.py is unaffected.

The originating data is OpenNeuro ds006502 (CC0). The failure is raised before the .meg4 is opened, so one recording's metadata reproduces it in about 3 MB:

aws s3 cp --no-sign-request --recursive --exclude "*.meg4" \
  s3://openneuro.org/ds006502/sub-01/ses-meg1/meg/sub-01_ses-meg1_task-rest_run-1_meg.ds/ \
  sub-01_ses-meg1_task-rest_run-1_meg.ds/

With this change that recording's .hc parses to [NAS, LPA, RPA, NAS, LPA, RPA] across both coordinate frames and the read proceeds to the data stage.

Match the .hc descriptor line case-insensitively and accept LPA/RPA as
aliases for left ear/right ear, so CTF datasets that spell the coils
Nasion/LPA/RPA are read instead of raising about missing HPI info.

@larsoner larsoner left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Seems like a straightforward fix, thanks @neuromechanist !

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

BUG: read_raw_ctf rejects .hc files whose coil descriptors are Nasion/LPA/RPA

2 participants