Skip to main content

CDISC Dataset-XML

Category: Clinical-trial dataset exchange

CDISC Dataset-XML is an XML transport for tabular research datasets. Convert-Pheno reads Dataset-XML v1.0 with required Define-XML v2.0 or v2.1 metadata, then groups the resolved SDTM rows by participant. The route is implemented and regression-tested; independent study and generator coverage is still limited.

RoleInput
Accepted inputDataset-XML v1.0 plus Define-XML
Main outputBFF, PXF, OMOP-CDM
ProcessingResolved and grouped in memory
Dataset-XML domains resolved through Define-XML and grouped by USUBJID before conversion
Define-XML supplies domain and column metadata that Dataset-XML deliberately does not repeat

What You Need​

Supply one Dataset-XML file per SDTM domain and the Define-XML file describing those domains:

convert-pheno \
  -idataset-xml dm.xml mh.xml lb.xml \
  --define-xml define.xml \
  -obff individuals.json

The current route requires:

  • exactly one DM dataset with one unique USUBJID per participant
  • matching study and metadata-version references across the files
  • one metadata-defined SDTM domain per Dataset-XML file
  • known and non-duplicated row and item identifiers

See the Dataset-XML recipes for PXF and OMOP-CDM commands.

How It Is Converted​

Define-XML supplies variable names, order, labels, data types, and controlled terminology metadata. After that resolution, Dataset-XML uses the same SDTM mapping as Dataset-JSON:

SDTM domainMain converted content
DMidentifier, sex, ethnicity, geographic origin, birth date, and vital status
MH, AEdiseases and phenotypic features
LB, VSmeasurements, units, ranges, and dates
CM, EX, PRtreatments and procedures
TSdataset and cohort metadata

Other participant-level domains remain available under info.datasetXml.domains. Use --no-source-info to omit that raw copy while retaining mapped BFF fields.

See Dataset-XML to BFF for transport details and Dataset-JSON to BFF for the shared field-level mapping.

Terminology​

When Define-XML provides an nci:ExtCodeID, Convert-Pheno looks up that NCIT identifier exactly and uses its canonical label. An optional Mapping V2 file with source.profile: sdtm can add reviewed direct terms, aliases, or label queries for fields without an authoritative identifier:

convert-pheno \
  -idataset-xml dm.xml ae.xml \
  --define-xml define.xml \
  --mapping-file sdtm-terminology.yaml \
  --term-audit terminology.tsv \
  -obff individuals.json

If neither Define-XML nor the mapping resolves a value, the output uses a source-derived CDISC: identifier. This preserves SDTM field/value identity without claiming an external ontology mapping.

For OMOP output, source-derived CDISC: identifiers are not assumed to be Athena concept codes. The BFF-to-OMOP stage can still resolve a unique active standard concept from a reviewed identifier, an official Maps to relationship, or a label in the expected OMOP domain. Otherwise it emits concept 0. Use a reviewed terminology mapping when the OMOP concepts carry analytical meaning for the study.

The baseline fixture output shows fallback behavior. The terminology fixture output shows both exact NCIT resolution and an intentional fallback. See Mapping Files and Terminology Search before adapting the example to study data.

Memory use

Dataset-XML input is non-streaming. The Define-XML metadata, domain datasets, and grouped participant records must fit in memory.