[ENH] BEP032: Move anatomical location to the electrode level

[bendichter]

Implements the decisions we reached in the working group meeting on 2026-07-29 about anatomical location, addressing the threads on Uberon intent and (estimated|proof) rendering, and following up on #2307 (comment). This targets bep032-review, so it merges into #2307 rather than into master. It is independent of #2480 and the two do not touch the same lines.

probes.tsv

associated_brain_region and associated_brain_region_id become anatomical_location and anatomical_location_id. The columns now describe the probe as a whole, so the structure named there must be one that contains every recording site on the probe, and may be as coarse as the brain or a single hemisphere. The renaming also drops the assumption that a probe is in the brain, which does not hold for a probe placed in peripheral tissue, muscle, or spinal cord.

Note that this differs from what I proposed in the comment on #2307. I had suggested reading the probe-level columns as the intended surgical target. The meeting landed somewhere better: the probe-level value is whatever level of anatomical detail actually holds for the whole probe, which is a claim you can make with confidence rather than a statement of intent.

electrodes.tsv

location becomes anatomical_location, and anatomical_location_id and localization_method are added. Per-contact localization belongs here, since a long shank probe passes through several structures and only the electrode table can describe that. Putting the identifier here also means that different electrode tables, distinguished by the space-<label> entity, can carry localizations from different atlases produced by different methods.

Removals

associated_brain_region_quality_type is removed. We could not draw a clear line between its estimated and proof values in practice, and knowing the actual method, for example whether the location was histologically confirmed, is both more useful and easier to record. The free-text localization_method column replaces it. This also resolves the rendering problem @effigies reported, since the (estimated|proof) notation that was truncating the table is gone.

reference_atlas is removed from probes.tsv. The atlas is now named in a ReferenceAtlas field in the electrodes sidecar, which is where the terms it applies to live. A LocalizationMethod field is available in the same sidecar for the case where one method applies to every electrode in the file. Both are optional, and the specification states that the method must not be given in both the column and the sidecar.

Ontology Guidance

The guidance no longer prefers species-independent terms. Terms from a species-specific atlas are acceptable and are often the better choice, and identifiers should be resolvable, either as a URI or as a prefixed identifier whose prefix identifies the source. This is what @effigies' question about whether Uberon was required or merely an example was getting at, and the answer is now stated explicitly rather than implied by an example.

Requirement Levels

The two probe columns keep the requirement level of the columns they replace (RECOMMENDED). On the electrodes table, anatomical_location keeps the RECOMMENDED level that location had, and the two new columns are OPTIONAL, as are both sidecar fields. Happy to adjust if the group would rather set these differently.

Verification

bidsschematools tests pass (81 passed, 1 skipped), as do pre-commit on the changed files and npm run remark. I confirmed that both the probes and electrodes column tables and the new sidecar table render, and that no references to the removed columns remain anywhere in src/.

One thing worth a second pair of eyes: I updated the example tables to use Allen Mouse Brain Atlas identifiers (MBA:315 for isocortex, MBA:985 for MOp, MBA:382 for CA1). I believe those structure identifiers are right, but someone who works with the atlas daily should confirm them before this merges.

@lzehl, this is the second item from the meeting. The first is #2480.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 83.09%. Comparing base (3f661db) to head (b8afb5d).

Additional details and impacted files

@@              Coverage Diff               @@
##           bep032-review    #2481   +/-   ##
==============================================
  Coverage          83.09%   83.09%           
==============================================
  Files                 22       22           
  Lines               1698     1698           
==============================================
  Hits                1411     1411           
  Misses               287      287           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[effigies]

Some notes. Apologies for the hit and run. Will be out-of-office for the next week.

[lzehl]

@bendichter you had two questions for me regarding this PR which I'm going to answer here.

1. Is a free-text method column enough, or should we keep a controlled quality-type field alongside it, given the openMINDS criteria quality types?
The quality type of the localization method is not necessarily inferrable from the provided free-text method (e.g. in particular if the method name is not specific enough). However the question is if we want to encourage/enforce a quick classification according to the quality type (asserted vs processive in openMINDS lingo) or if this is less relevant here/for now. Since this theoretically is a reusable quality assessment across all claimed methods within the BIDS it is maybe worth to not introduce it right now but discuss this in the broader BIDS context (maybe as part of how quality of data, methods, etc is handled in BIDS). @effigies maybe you could provide feedback here ?

2. And are the Allen MBA identifiers in the examples (MBA:315 isocortex, MBA:985 MOp, MBA:382 CA1) correct?
   These are all correct variants of the short versions of the identifiers for the AMBA brain regions as registered by Allen Institute. However MBA_315 etc is also used in some cases. Problem with Allen Institute is that they actually do not define resolvable, globally unique PIDs to their brain regions and ontology registries built their own wrappers for those (several of those also not directly resolvable). So... not sure if we want to go through all the possibilities of best identification of brain regions? For me the example is efficient enough considering the missing resolvable, globally unique PID. Where region IDs properly resolve is for UBERON parcellations (e.g. http://purl.obolibrary.org/obo/UBERON_0001950).

[bendichter]

Thanks @lzehl, this is very helpful.

On the quality type question, I agree with deferring it. A free-text method column captures what most experimenters can readily provide, and a controlled asserted/processive classification seems like something that should be designed once for BIDS as a whole rather than introduced piecemeal here. I'll leave that to the broader discussion and would also welcome @effigies's take.

On the identifiers, thanks for confirming the short forms are correct. One small addendum to the resolvability picture: while I agree that the Allen Institute itself has never minted persistent resolvable identifiers, there is a registered third-party route. The Bioregistry (a community-maintained registry of identifier prefixes for the life sciences, similar in spirit to identifiers.org, that maps compact identifiers like mba:985 to resolvable URLs) registers the mba prefix and points it at the purls minted by the BICAN project (https://purl.brain-bican.org/ontology/mbao/MBA_985), which are in turn configured to resolve to the corresponding EBI OLS4 term pages. At the moment the BICAN purl server is misconfigured and every purl redirects to their config repo instead (I filed brain-bican/purl.brain-bican.org#73 about it), so today the form that reliably resolves is the OLS term page itself. This actually illustrates your point about wrapper fragility fairly well.

Given that, I plan to keep the example as is, with the Allen atlas viewer URLs as the TermURL values, since those resolve and land somewhere genuinely informative. The sidecar mechanism in this PR already covers both situations: per-term TermURL where something resolvable exists, and ReferenceAtlas alone where it does not.