Skip to content

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

Closed

Description

@neuromechanist

Description of the problem

mne.io.read_raw_ctf raises RuntimeError: Some of the mandatory HPI device-coordinate info was not there. on CTF datasets whose .hc head-coil file spells the coil descriptors Nasion, LPA, RPA rather than nasion, left ear, right ear. The coil coordinates are present and correct; only the labels differ.

_read_one_coil_point in mne/io/ctf/hc.py maps the descriptor through a fixed, case-sensitive substring lookup:

_kind_dict = {
    "nasion": CTF.CTFV_COIL_NAS,
    "left ear": CTF.CTFV_COIL_LPA,
    "right ear": CTF.CTFV_COIL_RPA,
    "spare": CTF.CTFV_COIL_SPARE,
}
...
for key, val in _kind_dict.items():
    if key in one:
        p["kind"] = val
        break
else:
    p["kind"] = -1

Nasion misses on case, and LPA/RPA are a different vocabulary altogether. Every point therefore parses with kind = -1, so _make_ctf_coord_trans_set (mne/io/ctf/trans.py:66) finds no LPA/RPA/NAS and raises. Note that the rest of the parse succeeds: valid is True for all six measured points and both coordinate frames are recognised.

n_points: 6
  kind= -1  coord_frame=1001  valid=True  r=[ 0.0756  0.0764 -0.2428]
  kind= -1  coord_frame=1001  valid=True  r=[-0.0293  0.0604 -0.2678]
  kind= -1  coord_frame=1001  valid=True  r=[ 0.0651 -0.0304 -0.2627]
  kind= -1  coord_frame=1004  valid=True  r=[0.0872 0.     0.    ]
  kind= -1  coord_frame=1004  valid=True  r=[0.0001 0.0655 0.    ]
  kind= -1  coord_frame=1004  valid=True  r=[-0.0001 -0.0655  0.    ]

For what it is worth, CTF's own reference reader is more permissive here. readHc inside readCTFds.m (bundled in FieldTrip as external/ctf/readCTFds.m) does not match coil names against a vocabulary at all: it takes the descriptor text positionally, as whatever sits between the leading standard/measured word and coil position relative to, and stores it verbatim. MEGCoilLabel = strvcat('nasion','left ear','right ear') is declared at line 528 and never used anywhere in the file. That reader also carries an explicit workaround for the stadard typo emitted by some Acq releases, so tolerance for descriptor variation seems to be expected on the CTF side.

Steps to reproduce

# Public CC0 data, OpenNeuro ds006502. Only the small metadata files are needed:
# the error is raised before the .meg4 is opened, so this is a ~3.2 MB download.
#
#   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/

import mne

mne.io.read_raw_ctf("sub-01_ses-meg1_task-rest_run-1_meg.ds", preload=False)

The 834-byte .hc in that recording begins:

standard Nasion coil position relative to dewar (cm):
	x = 5.65685
	y = 5.65685
	z = -21.00000
standard LPA coil position relative to dewar (cm):
...
measured Nasion coil position relative to head (cm):

For contrast, OpenNeuro ds000247 is also CTF and uses the spelling MNE expects (standard nasion ..., standard left ear ...).

Link to data

https://openneuro.org/datasets/ds006502 (CC0). The aws s3 cp above pulls one recording's metadata without the 252 MB .meg4; the 834-byte .hc alone shows the difference. All 380 recordings in the dataset carry the same spelling (sampled across sub-01, sub-03, sub-15, sub-20).

On provenance, in case it helps judge how common this is: these were acquired at the NIMH MEG Core Facility on a DSQ-2010 with Acq 5.2.1-linux-20060809, and the .hist records that each dataset was subsequently Rewritten by writeCTFds. writeCTFds's writeHc writes ds.hc.names verbatim ("ds.hc.names has the exact, complete names of the head coils"), so the rewrite preserves the spelling rather than introducing it. I have not established which step upstream produced it.

Expected results

The recording reads, as it does once the descriptors are renamed.

Actual results

Traceback (most recent call last):
  File "<stdin>", line 5, in <module>
  File ".../mne/io/ctf/ctf.py", line 67, in read_raw_ctf
    return RawCTF(
        directory,
    ...<3 lines>...
        verbose=verbose,
    )
  File "<decorator-gen-207>", line 10, in __init__
  File ".../mne/io/ctf/ctf.py", line 124, in __init__
    coord_trans = _make_ctf_coord_trans_set(res4, coils)
  File ".../mne/io/ctf/trans.py", line 66, in _make_ctf_coord_trans_set
    raise RuntimeError(
        "Some of the mandatory HPI device-coordinate info was not there."
    )
RuntimeError: Some of the mandatory HPI device-coordinate info was not there.

The descriptors are the only blocker. Copying the .ds and rewriting only the three words (Nasion -> nasion, LPA -> left ear, RPA -> right ear), changing nothing else, moves the same call past _make_ctf_coord_trans_set; it then fails only on the .meg4 I deliberately did not download:

  File ".../mne/io/ctf/ctf.py", line 161, in __init__
OSError: Could not find any data, could not find the following file(s): ['sub-01_ses-meg1_task-rest_run-1_meg.meg4'], and the following file(s) had no valid samples: []

With the full .ds present, the labels-only patched copy reads normally and yields the expected MEG, misc and stim channels.

Additional information

Platform             macOS-26.6.1-arm64-arm-64bit-Mach-O
Python               3.14.7 (main, Aug  5 2026, 10:29:49) [Clang 21.0.0 (clang-2100.1.1.101)]
CPU                  Apple M4 Pro (14 cores)
Memory               64.0 GiB

Core
├☑ mne               1.12.1 (latest release)
├☑ numpy             2.5.2
├☑ scipy             1.18.1
└☑ matplotlib        3.11.1 (backend=macosx)

First encountered on Linux inside a batch conversion pipeline; the traceback above is from a clean macOS environment.

Possible fix

Matching the descriptor case-insensitively and accepting lpa/rpa as aliases would cover this without loosening anything else, since the lookup is already a substring test against a short controlled vocabulary:

_kind_dict = {
    "nasion": CTF.CTFV_COIL_NAS,
    "left ear": CTF.CTFV_COIL_LPA,
    "right ear": CTF.CTFV_COIL_RPA,
    "lpa": CTF.CTFV_COIL_LPA,
    "rpa": CTF.CTFV_COIL_RPA,
    "spare": CTF.CTFV_COIL_SPARE,
}

matched against one.lower(). I tried that locally: the unmodified .hc above then parses to [NAS, LPA, RPA, NAS, LPA, RPA] and reading proceeds to the data stage, and a canonically spelled .hc parses identically to before. Happy to send that as a PR with a small test if you agree with the approach, or to defer if you would rather handle the descriptor vocabulary differently. Context for the interest: this blocks all 380 recordings of ds006502 from being served by NEMAR, and we would rather not normalize acquisition metadata on our side.

Activity

  1. welcome commented on Aug 22, 2026

    @welcome

    Hello! 👋 Thanks for opening your first issue here! ❤️ We will try to get back to you soon. 🚴

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions