PR 4b: schema refinement — EFO assay term + stored molecular_layer

[mengerj]

Scope (one roadmap item: PR 4b)

Consumes the PR 4 ontology stage to refine the canonical schema. On StudyNode/DatasetNode, the free-text modality string is replaced by a grounded EFO assay term ID plus a derived coarse molecular_layer enum.

What changed

• models/graph_schema.py — drop StudyNode.modality; add assay (EFO term ID, required) + molecular_layer (MolecularLayer, default UNKNOWN) to both StudyNode and DatasetNode. DatasetNode.assay now holds the grounded EFO ID, not a free-text name.
• normalize/cellxgene.py — each dataset's assay ID is taken from Census's already-grounded payload (ontology_summary.assays, matched to the dominant assay name); molecular_layer is derived from it via the resolver's EFO ancestor walk. StudyNode is built from the most-frequent dataset assay + that assay's layer. Layer derivation is memoised per assay; only EFO: IDs are walked (ungrounded → UNKNOWN, no network call).
• ontology/base.py — new OntologyService contract (TermResolver + molecular_layer) the normalizer depends on, so offline fakes inject both methods.
• ontology/layers.py — switched molecular_layer matching from exact EFO labels to ordered case-insensitive substring keywords.

Key decisions (rationale in ARCHITECTURE §5)

• Assay taken from Census payload, not re-resolved via OLS. Census is authoritative for its own data; re-resolving could drift. The resolver is used only for the lineage walk. Free-text sources (GEO/PRIDE) will resolve the assay string first.
• Exact-label → substring-keyword matching. Validating the PR 4 anchors against live EFO confirmed the flagged gotcha: EFO:0009922 (10x 3' v3 — the bulk of CELLxGENE) never reaches RNA assay; it sits under …transcription profiling/library preparation, and ATAC/ChIP/methylation/WGS all collapse to a generic DNA assay ancestor. Exact matching derived UNKNOWN for 10x. Ordered substring keywords classify all observed assays correctly; bare mass-spec and multi-omic terms stay UNKNOWN by design.

Verification

All four CI gates pass, including a hermetic run with no .env:

• ruff check . — clean
• ruff format --check . — 40 files formatted
• mypy src/parce — 24 files, no issues
• pytest -m "not integration" — 133 passed

The marked live-OLS integration suite (tests/test_ontology_integration.py) was also run this session and passed (6 tests), confirming the tightened molecular_layer assertions end-to-end (10x + scRNA → TRANSCRIPTOME, ATAC → EPIGENOME).

No dependency changes; no new mypy exemptions.

▶ Next up after this: PR 5 — GEO extraction agent.

🤖 Generated with Claude Code