Feature/oncology ngs mappings

[anothernoise]

What's in this PR

This PR implements the new Oncology NGS Biomarker Specialty Pack (packs/specialty/oncology-ngs-biomarker/) to support oncology samples with diagnoses, genomic reporting, specimen preservation methods, and targeted therapy mappings into standard OMOP CDM v5.4 tables.

Problem Statement & Business Case

The Problem

Precision oncology clinical trials and Real-World Evidence (RWE) studies require linking a patient's primary cancer diagnosis with metastatic sites, specific somatic genomic variants (e.g., EGFR, ALK, KRAS mutations), tumor specimen collection/preservation parameters (solid/liquid biopsy, FFPE vs. Frozen), and subsequent targeted therapies (TKIs, Immunotherapies).
Standard FHIR-to-OMOP pipelines lack the specialized relational logic (e.g., fact_relationship parent-child mapping, component extraction, and domain routing) required to represent these oncology-specific linkages, resulting in data loss or fragmented records.

Business Value

This specialty pack standardizes the ingestion and transformation of oncology datasets under OHDSI Oncology conventions, enabling:

• Comparative Effectiveness Research (CER): Comparing targeted therapy vs. immunotherapy outcomes in molecularly-defined cohorts.
• Synthetic Control Arms: Leveraging real-world cohorts as historical/external controls for rare oncology mutations (e.g., ALK fusions) in clinical trials.
• Post-Market Surveillance: Automatically monitoring adverse events (e.g., pneumonitis) after targeted therapy initiation.

Why

Oncology clinical and genomic data require specialty mappings (such as metastatic site linkages via fact_relationship, biomarker routing to measurement/observation domains, and targeted therapy drug exposures) that are not fully captured by core pipelines. This pack standardizes these clinical flows using standard OHDSI conventions.

Sample Cases & Clinical Scenarios

The specialty pack contains 5 distinct golden test cases representing a realistic longitudinal patient journey (modeled around patient Jane Doe, a 50-year-old female):

1. Oncology Diagnosis (condition--condition-occurrence--oncology-diagnosis.json)
   • Scenario: Patient is diagnosed with Lung Adenocarcinoma (primary tumor) and later develops a secondary brain metastasis.
   • Target Mapping: Creates two condition_occurrence rows (concepts 4115276 and 436659) and two bidirectional fact_relationship records ("Primary of" / "Metastasis of") preserving their hierarchy.
2. Tumor Biopsy Specimen (specimen--specimen--oncology-tumor-biopsy.json)
   • Scenario: Collection of a liquid biopsy (blood draw) and solid tissue biopsy (split into FFPE preservation for pathology and Fresh Frozen preservation for genomics).
   • Target Mapping: Mapped to the specimen table with collection anatomy, quantities, and preservation-specific concepts (e.g. concepts 4001225, 4264660, 4264661).
3. Structured Genomics & Staging (observation--measurement--genomics-staging.json)
   • Scenario: Extraction of structured genomics assertions (EGFR p.L858R somatic mutation, KRAS p.G12C mutation, EML4-ALK gene fusion), quantitative biomarkers (TMB = 12.5 mut/Mb, MSI = High), and Pathological Stage IIIA TNM group.
   • Target Mapping: Somatic variants are mapped to observation.value_as_string (LOINC 48018-6); TMB/MSI map to measurement; TNM Stage Group and T, N, M category sub-members map to observation and are linked via fact_relationship ("Has panel member" / "Panel member of").
4. Oncology NGS Report (diagnosticreport--note--oncology-ngs.json)
   • Scenario: Final narrative genomics report conclusion released by the lab.
   • Target Mapping: Ingests the full unstructured summary text verbatim into the note table to support clinical NLP queries.
5. Targeted Therapy Mappings (medicationrequest--drug-exposure--targeted-therapy.json)
   • Scenario: Prescription of targeted EGFR TKIs (Osimertinib 80mg) or immune checkpoint inhibitors (Pembrolizumab 25mg/ml).
   • Target Mapping: Standardizes the prescriptions as drug_exposure records using RxNorm concepts (concepts 1716277 and 1547548).

Changes

Added pack management - for enabling safety engine

Specialty Pack (oncology-ngs-biomarker) Directory Tree

packs/specialty/oncology-ngs-biomarker/
├── README.md                        # Main technical mapping guidelines
├── TODO.md                            # Roadmap checklist for advanced oncology
├── GAPS.md                            # Schema gaps & OHDSI resolution rules
├── analysis.md                        # for next RWD/RWE cohort research applications
├── real-world-oncology-protocol.md    # Clinical stage Gantt timeline for the patient
├── samples.md                         # Reference patient test samples
├── pack.json                          # Pack registration metadata
└── _vocab_seed.sql                    # Seeded RxNorm/SNOMED oncology concepts

• mapspec/views/... regenerated (bun script/gen-views.ts)
  • Updated Condition__condition_occurrence.view.json (extracted primary condition references)
  • Updated Observation__measurement.view.json (extracted nested somatic variant and staging components)
  • Updated Specimen__specimen.view.json (extracted preservation processing procedures)
• Narrative docs updated (mapspec/<R>/<t>.md)
  • Created packs/specialty/oncology-ngs-biomarker/README.md
  • Created packs/specialty/oncology-ngs-biomarker/analysis.md (detailed RWD/RWE capabilities)
  • Created packs/specialty/oncology-ngs-biomarker/GAPS.md and TODO.md
  • Created packs/specialty/oncology-ngs-biomarker/real-world-oncology-protocol.md
• Code (src/, script/) changed
  • Created mapspec/etl/Condition__fact_relationship.sql
  • Created mapspec/etl/Observation__fact_relationship.sql
  • Updated mapspec/etl/Observation__observation.sql, Specimen__specimen.sql, _resolve_condition.sql, and _resolve_observation.sql
  • Updated script/run-cases.ts and script/etl-plan.ts to support specialty packs
  • Added new vocabulary concepts to packs/specialty/oncology-ngs-biomarker/_vocab_seed.sql
• Tests added / updated
  • Added cases/condition--condition-occurrence--oncology-diagnosis.json
  • Added cases/diagnosticreport--note--oncology-ngs.json
  • Added cases/medicationrequest--drug-exposure--targeted-therapy.json
  • Added cases/observation--measurement--genomics-staging.json
  • Added cases/specimen--specimen--oncology-tumor-biopsy.json

Validation

How to Run & Validate

1. Run Cases and Load Vocabulary Seed Pack
   To run the specialty pack cases and dynamically load the pack's custom vocabulary seed (_vocab_seed.sql) into the test database vocab schema:
   bun script/run-cases.ts seed oncology-ngs-biomarker

2. Run Pack-Specific Tests (Without Re-seeding)
   If the vocabulary schema is already seeded, you can filter case execution to only run this pack's cases:
   bun script/run-cases.ts oncology-ngs-biomarker

3. Run the Full Test Suite (With Seed Loading)
   To load all specialty pack seeds and run all 173 cases across the entire project:
   bun script/run-cases.ts seed

4. Run Unit and Snapshot Tests
   bun test

Others

• bun script/repl.ts 'await ctx.fns.repl.load(ctx, { name: "profiles" })' succeeds

• Affected /mapspec/... and /profiles/... URLs return 200 and render correctly

• bunx tsc --noEmit clean

• bun test clean (All 19 tests and snapshots updated and passed)

• bun script/run-cases.ts clean (All 173 case tests passed successfully)

• bun script/run-cases.ts --pack oncology-ngs-biomarker

Citations

• OHDSI Oncology WG Genomic Extension
• HL7 FHIR Genomics Reporting Implementation Guide
• OHDSI Oncology WG Disease Progression & Metastasis Conventions