Unify UMLS semantic-type to Biolink-class mappings into one registry

[gaurav]

What and why

Babel assigns a Biolink Model class to every UMLS concept from its UMLS semantic type, but the logic was scattered: seven hardcoded tree-number maps across createcompendia/*.py, plus a separate Biolink-Model lookup in leftover_umls.py. This PR consolidates all of it into one tree-number-keyed registry, src/datahandlers/umls/semantic_types.py, and adds a mechanism to record (and test) the places where Babel deliberately disagrees with the Biolink Model.

This is the UMLS slice of #735 (consolidate per-vocabulary tree-partition registries so filters don't overlap). Scope here is UMLS only and behavior-preserving — see "Deliberately out of scope" below.

Changes

• Package conversion: src/datahandlers/umls.py -> src/datahandlers/umls/__init__.py (no content change; all imports unchanged). Tracking issue to split the rest of __init__.py into subfiles: Reorganize src/datahandlers/umls into subfiles #802.
• Registry (semantic_types.py):
  • SEMANTIC_NETWORK — full 127-entry UMLS Semantic Network (TUI <-> tree number <-> name), hardcoded for offline use, with translation helpers.
  • UMLS_TYPE_MAP — one UMLSTypeAssignment per tree number: the Biolink class Babel assigns, the owning compendium, an optional proposed_biolink_type + tracking issue for disagreements with the Biolink Model. Validated at import.
  • category_map_for() derives each partition map; umls_tree_number_to_biolink_type() / resolve_biolink_types() power the leftover catch-all (registry-first, Biolink Model fallback).
• Consumers: the six category_map-style write_umls_ids() sites and leftover_umls.py now derive from the registry. Per-compendium blocklists stay local (exclusion logic, not type assignments). gene.py (bespoke MRCONSO path) and the RxNorm path are intentionally left alone.
• Tests: golden-snapshot of the six partition maps, translation, resolver, and validation (unit); a network test that fails/xfails once the Biolink Model adopts a proposed mapping; a pipeline drift test that checks SEMANTIC_NETWORK against the live MRSTY.RRF.
• Docs: docs/UMLSSemanticTypes.md, a CLAUDE.md subsection, and tests/README.md entries.

Behavior impact

The partition maps are byte-identical to the previous hardcoded maps (verified by the golden-snapshot test and a direct before/after diff on the live MRSTY.RRF — same CUI set, same counts). Three disagreements are recorded but not applied (proposed_biolink_type only), so build output is unchanged.

One intended difference in leftover_umls: residual CUIs whose semantic type Babel partitions are now typed from the registry (registry-first) rather than from the Biolink Model — e.g. a protein-tree CUI that was blocklisted into the leftover compendium now resolves to Protein instead of Biolink's Polypeptide. This never moves a CUI between compendia; it only makes leftover typing consistent with the partition decisions.

Deliberately out of scope (follow-ups)

• Applying / quantifying the flips (Reassign neoplastic process from UMLS as a finding rather than a disease #111 Neoplastic Process, STY:T033 "Finding" should not be mapped to biolink:PhenotypicFeature #569 Finding & Lab/Test Result): tracked in Apply and quantify the tracked UMLS -> Biolink semantic-type disagreements #803. Applying Reassign neoplastic process from UMLS as a finding rather than a disease #111 alone retypes ~50k CUIs, so it deserves its own measured PR.
• MeSH tree numbers into the same system, to consolidate all filtering (Centralize per-vocabulary tree-partition registries (MeSH + UMLS) #735).
• UMLS Semantic Type T045 ("Genetic Function") is not mapped to a Biolink Class #257 (T045 "Genetic Function") appears already addressed — B2.2.1.1.4.1 is mapped to BiologicalProcess by the process partition; noted in Apply and quantify the tracked UMLS -> Biolink semantic-type disagreements #803 for confirmation/closure.

Testing

uv run pytest tests/datahandlers/test_umls_semantic_types.py -m unit -q     # offline
uv run pytest tests/datahandlers/test_umls_semantic_types.py --network -v   # vs live Biolink
uv run pytest tests/pipeline/test_umls.py --pipeline --no-cov -v            # drift + partitioning
uv run pytest -m unit -q                                                    # full unit suite (92 pass)

Closes part of #735 (UMLS portion).

🤖 Generated with Claude Code