cdisc-for-ai

Machine-actionable reference files for CDISC clinical data standards -- designed for both human review and AI consumption.

Reference versions — SDTM CT 2026-03-27 (NCI EVS), COSMoS BC/DSS 2026-05-26, SDTMIG v3.4. Latest release note: docs/Changes_2026-06.md (COSMoS 2026-05-26 refresh + instrument tooling). Previous: docs/Changes_2026-05.md, docs/Changes_2026-04.md.

Why

Behind every TESTCD/TEST pair sits an NCIt concept with its own identity, definition, synonyms, and connections to broader biomedical vocabularies. In specimen-based domains, each Dataset Specialization adds an identifiable measurement specification: specimen, method, units, LOINC. But these linkages are scattered across disconnected sources. The CT file presents test codes as submission strings. Reaching the measurement specification requires navigating across BC and DSS exports. A human must mentally reconstruct the connections.

The move toward structured study definitions (USDM, 360i, OpenStudyBuilder) pushes this specificity upstream, into study design, where it needs to be explicit and machine-readable from the start. A study designer building a lab appendix starts from a medical purpose ("monitor liver function") and needs to arrive at specific, selectable measurement specifications. The CDISC standards already contain the building blocks for this. What is missing is not content but infrastructure: machine-traversable connections between concepts that already exist.

This repository makes those linkages explicit. Each reference file puts related data side by side in rows, with clear keys linking across sheets and tracks, reachable from one place for humans, AI systems, and rule engines alike.

For how the analytical layers fit together, see SDTM_Domain_Overview.md.

Flat files are views, not the architecture

The relationships that make CDISC standards useful -- TESTCD to NCIt concept, concept to LOINC, concept to specimen and method variants, BC to DSS -- already exist. They are scattered across disconnected sources and formats: CT files, COSMoS JSON exports, NCIt OWL files, LOINC tables. No single source lets you traverse from a medical term to a selectable measurement specification.

This project makes those relationships explicit by joining them into flat files. That is useful today -- Excel files reach data managers, statisticians, LLMs, and rule engines. But flat files are projections. They lose the graph structure: the same concept appears in multiple rows, relationships become columns, and traversal requires lookup rather than navigation.

The future is publishing CDISC standards as a graph that tools and AI can traverse directly. Flat files, APIs, SPARQL endpoints, LLM tool access -- these are all views of the same underlying graph. One Graph, Many Views. This project demonstrates what those views look like and what content they need. The graph itself is the goal.

Tracks

The repository is organized into source tracks, a graph track, a reference track, a view track, and consumer tracks. Source tracks extract and enrich from upstream standards. The graph track projects COSMoS into a multi-sheet traversable graph. The reference track provides shared domain metadata. The view track joins the graph into per-DSS views. Consumer tracks add structural-type-specific final shaping for study design and mapping workflows.

Each reference file is self-describing, with a README sheet documenting columns, provenance, and design decisions.

Source tracks

Track	Question	Output	Source
sdtm-test-codes/	What is measured?	SDTM_Test_Identity.xlsx -- domain-level test codes	NCI EVS, NCIt, UMLS
		SDTM_Instrument_Test_Identity.xlsx -- test codes bound to an instrument codelist
	What instruments?	SDTM_Instrument_Identity.xlsx -- one row per instrument codelist, dual NCIt anchors (C20993 + C211913)
cosmos-bc-dss/	What are the behavioural patterns?	COSMoS_Behavioural_Analysis.md, COSMoS_Domain_Pattern_Inventory.xlsx -- behavioural analysis docs and NCIt-comparison reports; also the COSMoS source-ingest landing zone read by cosmos-graph/	COSMoS BC/DSS exports

Graph track

Track	Question	Output	Source
cosmos-graph/	How is it measured? (multi-sheet graph)	COSMoS_Graph.xlsx -- BC, BC_Parents, BC_Categories, DSS, Variables, Codelists, Relationships, ...	LinkML schemas + COSMoS source
	Resolved against SDTM CT	COSMoS_Graph_CT.xlsx -- CT enrichment	NCI EVS SDTM CT

Reference track

Track	Purpose	Output
sdtm-domain-reference/	Domain metadata: structural types, COSMoS coverage flags, specimen/instrument classification	SDTM_Domain_Metadata.xlsx (pipeline input)

View track

Track	Purpose	Output
consumer-bases/	Joined views over the graph for consumer tracks (scope-agnostic)	DSS_View.xlsx -- wide, one row per DSS
		DSS_Variables_View.xlsx -- long, one row per VLM-row
		PR_DSS_Reachability.xlsx -- procedure-forward reachability into Findings DSSs

Consumer tracks

Track	Structural type	Scope	Output
sdtm-findings-graph/	Specimen-based	LB, MB, MI, CP, BS, MS, PC, PP (IS, GF, UR excluded -- see behavioural analysis)	Specimen_Findings.xlsx
	Measurement	VS, MK, CV (EG deferred)	Measurement_Findings.xlsx
	Instrument-based	QS, FT, RS	Instrument_Findings.xlsx -- four-sheet (Test_Identity, Measurement_Specs, BC_Categories, BC_Parents)

Specimen and Measurement consumer files are two-sheet Excel workbooks: Test_Identity (one row per TESTCD, enriched with COSMoS summary) and Measurement_Specs (one row per Dataset Specialization, scoped to the relevant domains). The Instrument consumer is four-sheet — adds BC_Categories (search-tag mechanism) and BC_Parents (parent-chain traversal) because instrument grouping operates outside the BC parent chain (item BCs roll up via wrapper concepts, not via the instrument-level BC). Link between sheets: TESTCD.

Skills

AI skills for working with CDISC standards. The reference files above are designed for skill consumption.

Skill	Purpose	Reference file
sdtm-ct-analysis/	Structural analysis of SDTM Controlled Terminology: category discovery and profiling. Part of the analytical foundation behind the reference files.	NCI EVS SDTM CT file

Data flow

graph TD
    subgraph Sources
        EVS["NCI EVS SDTM CT"]
        COS["COSMoS exports"]
    end

    subgraph sdtm-test-codes
        TI["SDTM_Test_Identity.xlsx"]
        ITI["SDTM_Instrument_Test_Identity.xlsx"]
        II["SDTM_Instrument_Identity.xlsx"]
    end

    subgraph cosmos-bc-dss
        BA["Behavioural_Analysis.md"]
        DPI["Domain_Pattern_Inventory.xlsx"]
    end

    subgraph cosmos-graph
        CG["COSMoS_Graph.xlsx"]
        CGC["COSMoS_Graph_CT.xlsx"]
    end

    subgraph sdtm-domain-reference
        DM["SDTM_Domain_Metadata.xlsx"]
    end

    subgraph consumer-bases
        DV["DSS_View.xlsx"]
    end

    subgraph sdtm-findings-graph
        SF["Specimen_Findings.xlsx"]
        MF["Measurement_Findings.xlsx"]
        IF["Instrument_Findings.xlsx<br/>(four-sheet)"]
    end

    EVS --> TI
    EVS --> ITI
    EVS --> II
    EVS --> DM
    EVS --> CGC
    COS --> CG
    COS --> BA
    COS --> DPI

    CG --> DV
    CGC --> DV
    TI --> DV

    DV --> SF
    DV --> MF
    DV --> IF
    DM --> SF
    DM --> MF
    DM --> IF
    II --> IF
    ITI --> IF

    DO["SDTM_Domain_Overview.md<br/>repo root"]

Loading

Key findings

The analytical work produced insights beyond the reference files themselves. Full detail in COSMoS_Behavioural_Analysis.md and Identity_Needs_by_Behavioural_Group.md.

The BC-to-DSS relationship means different things in different domains. The COSMoS model is intentionally generic: one BC schema and one DSS schema serve all domains. But the same structural relationship carries fundamentally different meaning depending on where you are. The analysis identified ten behavioural groups that cluster into five identity patterns:

Identity pattern	Groups	What a DSS represents
DSS-level identity needed	Specimen, Immunogenicity, Genomics	A clinically distinct measurement specification
BC-level sufficient	Measurement, Domain-specific, Instrument	No meaningful identity difference below BC
Protocol-driven	Events, Interventions	A CRF template variant, not a measurement
Relational	Clinical Assessment	Meaningful only with RELREC context
Not applicable	Trial Design	Study-level metadata

DSSs model collection templates, not medical ontology. COSMoS BCs and DSSs are derived from SDTM, a submission and collection standard. The DSS level models how a row looks in the dataset: a CRF row template. Medical History has 1 BC and 11 DSSs (CRF template variants, not 11 distinct measurements). Substance Use decomposes Alcohol into Beer, Wine, and Spirits (collection form options, not medical taxonomy). The need for DSS-level identifiers arises where the collection template also reflects a real clinical difference, as in specimen-based domains where glucose in serum and glucose in urine are different CRF rows AND different clinical measurements with different LOINC codes. See COSMoS_Collection_vs_Ontology.md.

Specimen-based Findings is not one pattern. The SDTM IG groups 11 domains under this label (Section 6.3.5), but the behavioural analysis shows three distinct decomposition logics: LB/MB/MI by specimen, IS by target antigen (up to 92:1 fan-out), and GF by result scale. UR is behaviourally flat despite its IG classification.

DS_Codes are mnemonics, not identifiers. DS_Codes (COSMoS vlm_group_id) are designed for human readability (GLUCSER = Glucose in Serum), not as persistent machine identifiers. They are not unique across domains. Several approaches could make DSSs machine-addressable: URIs from domain + DS_Code, NCIt C-codes at the DSS level, or other mechanisms. The right approach is an open question for the community.

The standardized identity layer is complete; the measurement specification layer is not. The specimen-based consumer file carries 4,183 TESTCDs with full NCIt identity across 8 domains, but only 104 have COSMoS measurement specifications. For laboratory tests specifically, sponsors who maintain internal lab test catalogues or registries already have much of the missing operational detail (specimen types, methods, units, LOINC codes). The Test_Identity sheet provides the standardized anchor (TESTCD, NCIt_Code) for mapping that internal content to the CDISC identity layer. Where COSMoS has published DSSs, use them. Where it has not, the identity layer is still there. See the graph-fed consumer track README for detail.

Open questions. Does the identity pattern classification match how the BC group thinks about these domains? Is the collection-template framing useful for understanding where DSS-level identifiers add value? And for sponsors implementing USDM-based study definitions: what CDISC content can already serve at the measurement specification level, and where are the gaps? Feedback on any of these is welcome.

Design decisions

Why flat files? Excel files with README sheets reach the broadest audience today: data managers, statisticians, LLMs, rule engines. The underlying relationships are graph-shaped, but flat projections are the most accessible delivery format until the standards are published as a traversable graph.

Why "machine-actionable" not "AI-friendly"? Applies to any automated system, not just LLMs. Aligns with FAIR data principles.

Why interim/? Downloads are external. Interim files are our own pipeline artifacts, visible because they have value as standalone artifacts, even if not the final product.

Why renamed columns? COSMoS source field names are implementation-oriented (vlm_group_id, specimenIdentity, resultScale). The consumer files translate these to more transparent names (DS_Code, Specimen, Result_Scale) while documenting the mapping in the Flatten notebook for traceability.

Why three consumer notebooks? The three Findings structural types (specimen-based, instrument-based, measurement) have fundamentally different data shapes and join logic. Splitting by structural type keeps each notebook focused and its output consumable.

Status

Early and exploratory. Not a finished product. Built iteratively with Claude (Anthropic), will evolve through interaction with the CDISC community.

Author

Kerstin Forsberg, information architect specializing in clinical data standards.