# Biomarkers — canonical catalogue and derived links

The biomarker database (/biomarkers, /biomarker/<slug>; API GET /v1/biomarkers, GET /v1/biomarkers/:slug) implements SPEC §17 (biomarkers as first-class entities), §52 (biomarker → therapy context) and §121 (tumor-agnostic indications). It follows CLAUDE.md §8: curated metadata is allowed only when every code is verified against the authority, and every scientific link is derived from source records — never typed in.

# 1. What a biomarker entity is

One row of biomarkers (CI-BIO-…) is an identity record, seeded from packages/database/src/seed-data/biomarkers.ts (idempotent by slug; ids are minted once):

The catalogue holds 54 markers: HER2, ER, PR, EGFR (any) + exon 19 deletion / L858R / T790M / exon 20 insertion, ALK, ROS1, KRAS G12C, KRAS (any), NRAS, BRAF V600E, BRAF (any), MET exon 14 / amplification, RET fusion, NTRK fusion, HER2 mutation, PD-L1, MSI-H, dMMR, TMB-H, BRCA1, BRCA2, HRD, PIK3CA, ESR1 mutation, AR, AR-V7, PSMA, SSTR, CD19, CD20, BCMA, CD38, CD30, CD33, FLT3, IDH1, IDH2, NPM1, KIT, PDGFRA, FGFR2 fusion, FGFR3 alteration, BCR-ABL1, JAK2 V617F, TP53, CDKN2A deletion, ctDNA, Ki-67, del(17p).

Relationships stated in the metadata, not inferred: PD-L1 is the protein of gene CD274; HER2 is the protein of ERBB2; MSI-H (DNA phenotype, PCR/NGS) and dMMR (loss of MLH1/MSH2/MSH6/PMS2 protein by IHC) are two measurements of one biological state and are kept as two entries whose notes cross-reference each other; HER2 overexpression and HER2 (ERBB2) mutation are different markers.

# 2. Scope of a biomarker (what the links are computed from)

Formula biomarker-links-v1, identical in apps/web/src/lib/queries/biomarkers.ts and apps/api/src/routes/biomarkers.ts:

• gene_ids = anchor gene_id ∪ measurement.genes resolved by HGNC symbol (NTRK fusion → NTRK1/NTRK2/NTRK3; MSI-H and dMMR → MLH1/MSH2/MSH6/PMS2; BCR-ABL1 → ABL1 + BCR; del(17p) → TP53).
• variant_ids = measurement.variantSlugs resolved against variants (checked to exist in the production copy on 2026-09-11). When present the marker is molecular-level (BRAF V600E, EGFR L858R, KRAS G12C, MET exon 14, JAK2 V617F, HER2 amplification…) and every link is restricted to those variants instead of the whole gene.
• Markers with neither (TMB-H, HRD, ctDNA) have no gene-derived blocks: the pages show "Data not yet available" with the reason recorded in measurement.notes. Only the indication-text rule (§3.4) applies to them.

# 3. Derived links (computed at query time; no biomarker link table is written)

Every derived count carries the Computed claim badge and names its rule; every table of source rows carries the native claim badge of the source (Curated for CIViC, Regulatory for approvals, Published for trials and PubMed).

# 3.1 Evidence and associated cancers

CIViC evidence items with status = 'ACCEPTED' and evidence_type ∈ {PREDICTIVE, PROGNOSTIC, DIAGNOSTIC} whose variant_ids (molecular markers) or gene_ids (gene-level markers) overlap the scope. Levels A–E and directions are shown exactly as curated (never re-scaled, never collapsed). Associated cancers = distinct mapped cancer_id of that evidence, with counts by type and by level. Submitted and rejected items are excluded; PREDISPOSING, ONCOGENIC and FUNCTIONAL items are not part of the biomarker scope (they belong to the gene page).

# 3.2 Drugs with predictive evidence

Union of (a) therapy_ids of the in-scope PREDICTIVE items and (b) targets of active knowledge_edges PREDICTS_RESPONSE_TO whose source variant is in scope. Per drug the page shows the number of items, sensitivity vs resistance counts (CIViC significance), the best native level, the number of knowledge edges with their direction, and the cancer contexts — as separate columns, never merged into a verdict.

# 3.3 Trials

clinical_trials having an intervention mapped (trial_interventions.drug_id) to a scope drug and a condition mapped (trial_conditions.cancer_id) to a scope cancer. Counts: total, active (RECRUITING, NOT_YET_RECRUITING, ENROLLING_BY_INVITATION, ACTIVE_NOT_RECRUITING), recruiting, active phase 3. The table lists active trials, newest update first. A trial listed here tests the drug in the cancer; it does not mean the trial selects patients on the biomarker.

# 3.4 Approvals

drug_approvals rows (a) whose drug_id is a scope drug — matchedBy = drug — and/or (b) whose indication text contains one of the curated indicationTerms phrases (case-insensitive substring, e.g. "microsatellite instability-high", "NTRK", "PD-L1") — matchedBy = indication. Each row keeps its authority, jurisdiction, indication text, status and date. Health Canada DIN rows carry no indication text, so they only ever match by drug.

# 3.5 Tumor-agnostic rule (§121)

measurement.tumorAgnostic = true is a curated statement (MSI-H, dMMR, NTRK fusion, TMB-H, BRAF V600E, RET fusion, HER2). The UI and API never assert it alone: the badge is accompanied by the actual drug_approvals rows with tumor_agnostic = true (the source's flag, set by the openFDA connector from the label text) reached through §3.4. When no such row is ingested yet, the page says so explicitly ("no tumor-agnostic approval row ingested yet") instead of implying one exists.

# 3.6 Literature

publication_entity_edges (status ≠ rejected) on the scope variants for molecular markers, or on the scope genes otherwise. Bibliographic data as recorded by PubMed.

# 4. What is not claimed

• No clinical-utility grading of our own (no "Tier", "Level 1", "actionable" labels): only the source-native CIViC level and direction and the regulator's status are shown.
• No threshold or cut-off is stated as CancerIndex's; scoring conventions are quoted as published and labels/indications are the authority's own text.
• No "approved for biomarker X" statement: approvals are listed per authority and jurisdiction with their indication text, and the match rule (drug set / indication text) is displayed per row.
• No patient-level guidance: biomarker pages describe what a test measures, not what a person should do.
• Absence of a link is not evidence of absence: only ingested sources (CIViC, ClinicalTrials.gov, openFDA, Health Canada DPD, PubMed edges) are covered.

# 5. Maintenance

• Add a marker: append to BIOMARKER_SEED with a verified NCIt code (fetch the concept, record the date/version in the header if the version changed), run pnpm db:seed, run packages/database/test/biomarkers.test.ts.
• Changing the derivation rules = bump BIOMARKER_LINKS_FORMULA in both the web queries and the API route, and update §3 here.