This is a ready-to-use variable-level specification for an ADaM analysis dataset. It is the document an independent programmer works from to write validation code without seeing production code, the document a conformance checker’s warnings get reconciled against, and the source Define-XML is supposed to describe accurately. Replace every <<FILL: ...>> placeholder, version-control it with the SAP and shells, and update it under change control, never by editing a program and letting the spec drift. Filled samples for ADSL and one BDS parameter dataset follow. This is general educational content to adapt to your organization and study, not regulatory advice, and it describes CDISC ADaM concepts in original wording; confirm current standard versions and controlled terminology before issue.
Why this document earns its place
The independent programming SOP and the article on statistical programming validation both describe “the ADaM specification” as the document the independent programmer works from, variable by variable, to reproduce a derivation without ever opening production code. Until it exists as its own controlled artifact, that instruction has nothing concrete behind it, and two programmers given only a SAP paragraph and a dataset name will fill the gaps differently, which defeats the point of independent programming. This specification is that artifact: the bridge between the SAP’s prose and the code, specific enough that two people working from it independently should converge on the same dataset.
Document control
| Field | Entry |
|---|---|
| Dataset | <<FILL: e.g. ADSL, ADLB>> |
| Study / protocol | <<FILL>> |
| Version | <<FILL>> |
| SAP version this spec implements | <<FILL>> |
| Based on ADaM Implementation Guide version | <<FILL>> |
| Author | <<FILL>> |
| Status | Draft / Approved / Superseded |
Purpose and how this is used
This specification states, for one ADaM dataset, every variable’s name, type, length, format, controlled terminology, source, and derivation, so that production programming, independent validation programming, conformance checking, and Define-XML authoring all work from the same stated truth. It is produced after the SAP is approved and before production programming starts, and any change to a derivation goes through a dated revision here before it goes into code, never the reverse.
How this specification is produced and maintained
- Derive each variable’s source and logic from the approved SAP, and for tabulation-sourced variables from the governing SDTM structure, not from a prior study’s dataset reused by habit.
- State every derivation in enough detail that it does not require interpretation. “Baseline is the last non-missing assessment before first dose” is not sufficient if “before first dose” could mean study day or could mean the dose datetime; state which, and why, if the SAP itself is ambiguous, and raise the ambiguity to the statistician rather than resolving it silently.
- Name the controlled terminology or codelist for every categorical variable, and reference its CDISC or sponsor-extended source.
- Version this document under the same control as the SAP and shells. A derivation change after approval is a dated revision here, propagated to the program and to Define-XML, not a direct code edit.
- Reconcile this specification against the delivered dataset and Define-XML before database lock or submission. A spec that describes the dataset as it was intended, rather than as it was built, fails the traceability it exists to support.
The variable-level specification table
| Variable | Label | Type | Length | Format | Significant digits | Codelist / controlled terms | Origin | Derivation | Comment |
|---|---|---|---|---|---|---|---|---|---|
<<FILL>> | <<FILL>> | <<FILL: Char/Num>> | <<FILL>> | <<FILL>> | <<FILL>> | <<FILL>> | <<FILL: Collected/Derived/Assigned>> | <<FILL: exact rule, or "see SAP section X">> | <<FILL>> |
Extend one row per variable. For a BDS (Basic Data Structure) dataset, add the parameter-level fields below.
Additional fields for BDS (parameter-structure) datasets
| Field | Format | Required | Entry |
|---|---|---|---|
Parameter code (PARAMCD) | Controlled short code | Yes | <<FILL>> |
Parameter decode (PARAM) | Text | Yes | <<FILL>> |
| Analysis value source | SDTM variable(s) feeding AVAL/AVALC | Yes | <<FILL>> |
| Baseline derivation for this parameter | Exact rule | Yes | <<FILL>> |
Analysis flag(s) (e.g. ANL01FL) | Condition that sets the flag | Yes | <<FILL>> |
Acceptance criteria
This specification is adequate when every variable in the dataset has a stated type, length, format, and origin; every derived variable’s logic is stated precisely enough that an independent programmer needs no further interpretation; every categorical variable names its controlled terminology source; the document version is tied to the SAP version it implements; and the delivered dataset and its Define-XML both reconcile to this specification without undocumented drift.
References
CDISC ADaM Implementation Guide and ADaM Basic Data Structure (referenced by title; described in original wording). CDISC Define-XML specification. FDA Study Data Technical Conformance Guide.
Confirm the current version of each standard before issue.
Revision history
| Version | Date | Author | Summary of change |
|---|---|---|---|
<<FILL: 1.0>> | <<FILL: date>> | <<FILL: author>> | Initial issue. |
Approvals
| Role | Name | Signature | Date |
|---|---|---|---|
| Author (Statistical Programmer) | <<FILL>> | ||
| Reviewer (Trial Statistician) | <<FILL>> | ||
| Approver (Lead Statistical Programmer) | <<FILL>> |
Filled sample: ADSL (subject-level analysis dataset), excerpt
Header: Study ABC-301; version 2.0; implements SAP v3.0; author J. Okafor.
| Variable | Label | Type | Codelist | Origin | Derivation |
|---|---|---|---|---|---|
| USUBJID | Unique Subject ID | Char | None | Collected | From DM.USUBJID |
| TRT01P | Planned treatment | Char | Sponsor treatment codelist | Assigned | From randomization system, planned arm |
| TRT01A | Actual treatment | Char | Sponsor treatment codelist | Derived | TRT01P unless first dose received differs; if subject never dosed, set to TRT01P per SAP section 3.2 |
| ITTFL | Intent-to-treat flag | Char | Y/N | Derived | ”Y” if randomized, per SAP section 5.1; no exclusions |
| SAFFL | Safety population flag | Char | Y/N | Derived | ”Y” if randomized and received at least one dose, per SAP section 5.3 |
| AGE | Age | Num | None | Collected | From DM.AGE |
Filled sample: ADLB (laboratory BDS dataset), one parameter, excerpt
| Field | Entry |
|---|---|
| Parameter code | GLUC |
| Parameter decode | Glucose (mmol/L) |
| Analysis value source | LB.LBSTRESN where LB.LBTESTCD equals “GLUC” |
| Baseline derivation | Last non-missing GLUC result with a collection datetime on or before the first-dose datetime in ADSL.TRTSDTM, per SAP section 6.4 |
| Analysis flag ANL01FL | ”Y” for the record used in the by-visit summary table (one record per subject per visit per parameter, selected per SAP section 6.5’s visit-windowing rule) |
The baseline row is the one most likely to generate a validation discrepancy in practice: it names “first-dose datetime,” not “study day 1,” precisely because the companion statistical programming validation article shows two independent programs disagreeing on exactly that distinction when the specification left it to interpretation.
Common inspection findings this specification prevents
- Two independent programmers each forced to guess a derivation’s exact rule from the SAP’s prose, converging by coincidence rather than because the control worked.
- A derivation that exists in a production program but nowhere in a written spec, so there is nothing for an independent programmer, a conformance checker, or an auditor to validate against.
- A specification that still describes an early design intention after the derivation changed in practice, with no dated revision showing the change was deliberate.
- Define-XML and the specification describing the same variable two different ways, because one was updated after a late change and the other was not.
How to adapt this specification
- Write one of these per dataset, not one per study; a 20-dataset ADaM package needs 20 specifications, even if several share most of their structure.
- Keep the derivation column specific enough to settle the kind of ambiguity, study day versus dose datetime, inclusive versus exclusive window, that independent programming is designed to catch.
- For BDS datasets, repeat the parameter-level block for every
PARAMCDvalue that carries its own derivation logic. - Route every post-approval change through a dated revision here before it reaches a program, and reconcile this document against Define-XML before lock or submission.