Skip to content

[eegprep-lean] Fill chanlocs in to_eeg from a store's electrode positions - #626

Merged
neuromechanist merged 4 commits into
developfrom
agent/20261116-fix-625
Nov 17, 2026
Merged

neuromechanist merged 4 commits into
developfrom
agent/20261116-fix-625

Conversation

@neuromechanist

Copy link
Copy Markdown
Member

Fill chanlocs in eegprep-lean's to_eeg from the electrode positions a NEMAR store declares, so a recording read from a store can run ICLabel. load_recording reads the store root's electrode_positions, electrode_coordinate_system and electrode_coordinate_units into Window.electrodes (one more small request), and to_eeg gives each channel with an entry for exactly its label X, Y and Z in millimeters in EEGLAB's ALS frame plus sph_theta, sph_phi, sph_radius, theta and radius, by the steps of pop_load_frombids. A unit or coordinate system outside the BIDS appendix fills nothing and is recorded as units_unknown or coordinate_system_unknown in EEG["etc"]["nemar"]["locations"], which also holds the store's own words, the located count, and no_matching_labels when no label matched. A store without the attributes gives labels only, as before. etc["nemar"]["reader"] moves to recording-v2.

Route equality: one set of coordinates is written as an electrodes.tsv that pop_load_frombids reads and as store attributes that to_eeg reads, and X, Y, Z, theta, radius and the spherical fields compare exactly equal for 13 system and unit pairs (CapTrak, EEGLAB, EEGLAB-HJ, NeuromagElektaMEGIN, ElektaNeuromag, ChietiItab, MNI305, MNI152NLin2009cAsym, Talairach and fsaverage, in m, cm and mm). ICLabel's topographic features on EEGLAB's sample recording with ICA, located this way, equal those from its own chanlocs; without locations topoplot raises.

Differences from pop_load_frombids, found by running it and left alone here: CTF, 4DBti and KitYokogawa are ALS in the BIDS appendix and kept as they are, while the import turns them as RAS. The import guesses a unit when none is declared (a centimeter cap is read as millimeters, a millimeter cap gets no positions) and assumes a system when there is no coordsystem file; this gives no positions. The import reads Other, individual, study and scanner as RAS; this refuses them. A dataset-level electrodes.tsv is not found by the import and is used here. Neither route recenters template-space positions. The coordinate steps are written again inside eegprep-lean because it cannot import eegprep; sharing them is a follow-up.

Run: pre-commit.py --changed-from origin/develop, ruff check, ruff format --check, ty check on eegprep-lean, the eegprep-lean tests as CI runs them in the root, zarr, plot and both-extras environments (332, 319, 293 and 339 passed), and the same suite with eegprep, pybids and zarr together (378 passed). 34 one-line mutations of the new code are all caught by the new tests. The EEGLAB reference workflow does not apply: no core function changed, and it is red on develop for the submodule pin mismatch in #622. Not run: the full root suite, the macOS and Windows jobs, the Pyodide harness.

Fixes #625

@claude claude Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

⚠️ Code review skipped — your organization has no extra usage available to pay for this review.

If your organization's extra usage balance is empty, an organization admin can add extra usage credits at claude.ai/admin-settings/usage. If its monthly spend limit was reached, an admin can raise it on the same page. If neither applies, contact Anthropic support.

Once extra usage is available, someone with write access to this repository can comment @claude review on this pull request to trigger a review.

@claude

claude Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

Claude finished @neuromechanist's task in 1m 36s —— View job


Code review

  • Overall assessment: Looks good. One documentation-level parity gap, nothing blocking.
  • Highest-risk area: choosing the coordinate frame in chanlocs_from_electrodes (packages/eegprep-lean/src/eegprep_lean/locations.py).
  • Merge recommendation: Safe to merge. Optionally document the parity note below first.

Blocking

None.

Important

None.

Nits

None beyond the parity note below.

Test gaps

None. The tests check the RAS-to-ALS swap by hand-computed angles: nose, vertex and left ear, plus a fixed sph_phi and radius for E1. They do not rebuild the expected values with the code under test. The comparison against pop_load_frombids runs the real import on an electrodes.tsv it writes, so it is not a tautology. I could not run the tests in this job because Bash approval for uv run pytest was denied, so I am relying on the PR's reported runs.

EEGLAB parity notes

  • EEGCoordinateSystemDescription == "EEGLAB" is not handled (locations.py:116, posted inline). pop_load_frombids.py:313-321 treats a coordsystem as ALS whenever its description is EEGLAB, whatever EEGCoordinateSystem says. The store attributes do not carry the description. So a dataset with, say, CapTrak and the description EEGLAB gives ALS through the import and is turned by 90° here.
    • The common case still agrees: EEGPrep's own pop_exportbids writes CTF with the description EEGLAB (pop_exportbids.py:552-554), and CTF is ALS in this PR.
    • Suggested fix: add this case to the documented differences in the locations.py docstring, the README and both changelogs.

What I checked and found correct:

  • RAS to ALS turn: coords[:, [1, 0, 2]] followed by negating Y matches coords_RAS_to_ALS.
  • Angles: the formulas and their order match coords_ALS_to_angular, so the results agree exactly.
  • Units: they are looked up in lower case, which matches the import's .lower() at pop_load_frombids.py:322-324.
  • Unplaced channels: a channel with no entry gets empty arrays, the same as clear_chanloc leaves it.
  • chaninfo.nosedir: it is set to +X only when at least one channel is located.
  • load_recording: the store root is fetched after the memory budget check and before the signal, built on contract_base.
  • Bad position entries: a malformed electrode_positions is refused, and a non-finite or boolean entry is dropped.
  • etc.nemar.reader: moving it to recording-v2 is documented in both changelogs.
  • Repo rules: imports and module placement follow AGENTS.md. Copying the coordinate steps into eegprep-lean is justified, because it cannot import eegprep, and the PR names sharing them as a follow-up.

factor = _MM_PER_UNIT.get(electrodes.coordinate_units.lower())
if factor is None:
return labels_only, {**record, "located": 0, "reason": UNITS_UNKNOWN}
if electrodes.coordinate_system in _ALS_SYSTEMS:

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

Nit (EEGLAB parity, documentation): pop_load_frombids also treats a coordsystem with EEGCoordinateSystemDescription == "EEGLAB" as ALS, whatever EEGCoordinateSystem says (pop_load_frombids.py#L313-L321). The store only has electrode_coordinate_system, so a dataset that says CapTrak (or any RAS system) with the description EEGLAB comes out of the import as ALS and out of this function turned by 90°. Both routes give positions, so nothing records the disagreement.

The common case agrees: EEGPrep/EEGLAB's own export writes CTF with the description EEGLAB, and CTF is ALS here. So this only needs mentioning. Add it to the "Differences from pop_load_frombids" list in this docstring, the README and the changelogs. If the converter ever writes the description, it would be worth reading it here as well.

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.

eegprep-lean: fill chanlocs from a NEMAR store's electrode positions in to_eeg

1 participant