spb/cancerindex

1# ADR-005 — NCIt as the anchor ontology23Status: accepted (2026-09-08)45## Context67CancerIndex must cover every recognised malignant disease entity, not a list of common cancers, and8must reconcile labels from registries (ICD-10/ICD-O site groups), clinical sequencing (OncoTree),9curated evidence (CIViC uses DOID), trials (free text), literature (MeSH) and cohorts (GDC10project/disease types). No single vocabulary covers all of these; a canonical spine is needed to11which the others map.1213Candidates: NCI Thesaurus (NCIt), Disease Ontology (DOID), MONDO, OncoTree, ICD-O-3, MeSH.1415## Decision1617The NCI Thesaurus is the anchor: canonical cancer entities are created from NCIt neoplasm concepts18(roots in `packages/ontology/src/top-level.ts`: Neoplasm C3262, Malignant Neoplasm C9305, by-site19C3263, by-morphology C4741, hematopoietic/lymphoid C27134, childhood malignant neoplasm C4005…),20`cancers.primary_ncit_code` is unique, and the `ncit` hierarchy is the default tree for descendant21aggregation. Reasons: NCIt is maintained monthly by the NCI, is the terminology of ClinicalTrials.gov22condition coding and of CTRP/caDSR, carries rich synonyms with their source, includes23cross-references to UMLS/MeSH/ICD-O/DOID (via EVS), is public domain, and its EVS REST API is open.2425Other vocabularies are kept as **additional dimensions and codes**, never discarded:2627- OncoTree provides the tissue-based tree (`hierarchy_type = oncotree`) and `cancer_codes.system =28  oncotree`, mapped to NCIt through OncoTree's own NCI cross-references (`EXACT_IDENTIFIER`).29- DOID (CIViC), MeSH (PubMed), ICD-10 / ICD-O (registries), UMLS CUIs, MONDO, GDC project codes are30  stored in `cancer_codes` with a `match_type`.31- Registry site groups used for burden rankings are a curated overlay (`TOP_LEVEL_CANCERS`, 36 ICD-1032  groups anchored to NCIt concepts), not taxonomy nodes.3334Qualified disease states in NCIt (stage, recurrent, metastatic, laterality, treatment history) are35recognised by deterministic rules (`packages/ontology/src/qualifiers.ts`) and kept as source records36attached to their base disease rather than as canonical entities (spec §217-218).3738## Consequences3940- One concept, one row, one `CI-CAN` id; aliases from every vocabulary hang off it, which is what41  makes deterministic reconciliation (`CancerResolver`) possible.42- NCIt's own updates (retired concepts, merges) flow into `status = deprecated|merged` and43  `entity_merges`, with `classification_version` recorded on entities.44- Where NCIt and another ontology disagree on granularity, the mapping is recorded as45  `CURATED_BROADER` / `CURATED_NARROWER` rather than forced to exact, and the difference is visible46  in the API.47- The choice can be revisited if MONDO's harmonised cross-walks prove more complete for rare48  cancers; the model already stores MONDO codes, so the change would be a re-anchoring migration,49  not a schema change.50