Repository navigation
Description
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"] = -1Nasion 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
welcome commentedon Aug 22, 2026
Hello! 👋 Thanks for opening your first issue here! ❤️ We will try to get back to you soon. 🚴