Skip to content

feat(viewer): standard-montage topomap fallback - #118

Merged
neuromechanist merged 1 commit into
mainfrom
feat/topo-standard-montage-fallback
Jun 14, 2026
Merged

neuromechanist merged 1 commit into
mainfrom
feat/topo-standard-montage-fallback

Conversation

@neuromechanist

Copy link
Copy Markdown
Contributor

Problem

Most EEG datasets name standard 10-20/10-10 channel labels but ship no electrodes.tsv. Their Zarr store therefore carries no electrode coordinates, so the scalp topomap stayed permanently disabled. Concrete example: on007137 (channels FP1, Fz, F3, FC3, CPz, PO3, ..., no electrodes.tsv) showed no topo. This is the majority case, not a backfill gap.

Fix

Viewer-side fallback. When a recording has no embedded positions, project a vendored standard_1005 montage (from MNE make_standard_montage, head/RAS frame, 343 labels) matched to the EEG channel labels by name, exactly as EEGLAB/MNE do when you apply a named montage. Real electrodes.tsv positions (embedded by the converter) always take precedence; the topo toggle tooltip flags when the layout is estimated rather than measured.

Why viewer-side

  • Covers existing and future datasets with no backfill and no re-conversion.
  • Keeps stores faithful to actual BIDS content (no synthetic coordinates written to S3).
  • Single code path; one place to maintain.

Self-gating (no wrong topomaps)

  • Requires >= 3 locatable channels. Non-standard label sets resolve nothing -> no topo:
    • EGI nets (E1..E128), BioSemi (A1.. -> only ear refs A1/A2 match = 2 < 3), purely numeric.
  • iEEG/EMG/fNIRS unchanged (modality gate); MEG sensor names don't match 10-20 labels.
  • Legacy 10-20 names (T3/T4/T5/T6) alias to modern T7/T8/P7/P8; matching is case-insensitive (FP1 -> Fp1).

Changes

  • standard-montage.ts (new) - vendored montage + lookupStandardPosition / standardMontageFor.
  • viewer.ts - resolveScalpPositions() drives all three topo gates (build, group-switch enable, toolbar button).
  • standard-montage.test.ts (new) - lookup, aliases, case-insensitivity, self-gating, on007137-style labels.

Validation

  • 597 unit tests pass (7 new); astro check 0 errors; biome clean.
  • Montage data generated from real MNE on Hallu (standard_1005, 343 labels, MRI/RAS metres).

Most EEG datasets name standard 10-20/10-10 channel labels but ship no
electrodes.tsv, so their Zarr store carries no coordinates and the scalp
topomap stayed disabled (e.g. on007137). Add a viewer-side fallback: when a
recording has no embedded positions, project a vendored standard_1005 montage
(MNE make_standard_montage, head/RAS frame) matched to the EEG channel labels,
exactly as EEGLAB/MNE do when you apply a named montage. Real electrodes.tsv
positions still take precedence; the toggle tooltip flags an estimated layout.

This covers existing AND future datasets with no backfill or re-conversion, and
self-gates: non-standard label sets (EGI E1.., BioSemi A1.., numeric) resolve
fewer than 3 channels and get no topomap rather than a wrong one. Legacy 10-20
names (T3/T4/T5/T6) alias to their modern 10-10 equivalents; matching is
case-insensitive so FP1 resolves to Fp1.

- standard-montage.ts: vendored 343-label montage + lookup/standardMontageFor
- viewer.ts: resolveScalpPositions() drives all three topo gates
- standard-montage.test.ts: lookup, aliases, case, self-gating
@cloudflare-workers-and-pages

Copy link
Copy Markdown

Deploying nemar-website with  Cloudflare Pages  Cloudflare Pages

Latest commit: dc83001
Status: ✅  Deploy successful!
Preview URL: https://fe01334a.nemar-website.pages.dev
Branch Preview URL: https://feat-topo-standard-montage-f.nemar-website.pages.dev

View logs

@neuromechanist
neuromechanist merged commit caa47e7 into main Jun 14, 2026
1 check passed
@neuromechanist
neuromechanist deleted the feat/topo-standard-montage-fallback branch June 21, 2026 22:50
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.

1 participant