ADaM IN PRACTICE · A TECHNICAL SERIES FOR CLINICAL TRIAL STATISTICAL PROGRAMMERS

Designing compliant custom ADaM datasets when the structure taxonomy breaks down, and documenting the rationale so validators and reviewers stay on your side.

Article 1 of 6 · Audience: experienced SAS/CDISC statistical programmers

Abstract

ADaM's named structures, ADSL, BDS, and OCCDS, cover almost every analysis a statistical programmer will support, and that coverage makes them feel mandatory. Some analyses, however, have a unit of analysis that no standard class can represent without distortion. This article argues that the correct response is not to force such analyses into BDS but to use the escape hatch that ADaM v2.1 and ADaMIG v1.3 provide: a custom structure, declared as class ADAM OTHER, that demonstrably satisfies the fundamental principles of traceability, analysis-readiness, metadata clarity, and usability with standard tools. Through a worked example, a pairwise win ratio dataset (ADWR) supporting a hierarchical composite endpoint, the article shows how to exhaust the standard structures first, design a compliant custom dataset, and document the rationale in the ADRG, define.xml, and a conformance disposition. The takeaway is that a custom structure is a documented engineering decision, and thorough documentation is the price of the freedom the standard grants.

1. Introduction

Every statistical programmer eventually meets an analysis that does not fit ADSL, BDS, or OCCDS. Pairwise comparisons and other designs where the record is not a subject, a parameter, or an occurrence strain the taxonomy, and the common reaction is to force the data into BDS anyway. That produces datasets that are technically classed but analytically distorted, and it draws exactly the validator findings and reviewer questions the standard structures were supposed to prevent. The stakes are practical: an undeclared or poorly documented nonstandard dataset can turn a routine review into a cycle of information requests, while a well-documented one passes with explained, expected notes.

This article treats custom structures as disciplined engineering rather than improvisation. Section 2 explains why the taxonomy is a tool rather than a cage and where the standard itself permits additional structures. Section 3 gives the tests for exhausting the standard structures first. Section 4 works through a real example, ADWR, a pairwise win ratio dataset for a hierarchical composite endpoint. Section 5 turns the ADaM fundamental principles into an acceptance test, Section 6 covers the documentation artifacts that win reviews, and Section 7 collects practical guardrails. Section 8 concludes.

2. The taxonomy is a tool, not a cage

The ADaM Implementation Guide v1.3 (CDISC, November 2021) defines three named structures: the subject-level analysis dataset (ADSL), the Basic Data Structure (BDS), and, via its companion document, the Occurrence Data Structure (OCCDS). Between them they cover the overwhelming majority of analyses a statistical programmer will ever support. That coverage is precisely why the structures feel mandatory: most of us can go several submissions without ever needing anything else, and when an analysis finally arrives that does not fit, the instinct is to force it into BDS anyway.

The ADaM model v2.1 is explicit that this instinct is wrong. Section 1.5 of ADaMIG v1.3 recognizes that some analyses cannot be accommodated by ADSL, BDS, or OCCDS, and permits additional structures provided they satisfy the fundamental principles of the ADaM model. The regulatory machinery agrees: the FDA Study Data Technical Conformance Guide asks that analysis datasets follow the ADaM standard as listed in the Data Standards Catalog, and the standard itself includes the escape hatch. What the escape hatch does not include is permission to skip the discipline that comes with it. A custom structure is a documented engineering decision, not an improvisation.

This article walks through when the taxonomy legitimately breaks down, how to design a custom dataset that survives conformance checking, and (the part most teams underinvest in) how to document the rationale in the ADRG and define.xml so a reviewer never has to guess what you did.

3. Exhaust the standard structures first

Every custom structure conversation should start with a serious attempt to disprove the need for one. The failure modes are well known: a dataset that could have been BDS but was built wide 'for convenience' will draw conformance findings, validator questions, and reviewer distrust, the exact opposite of what analysis-ready means. The sequence in Figure 1 is the one we apply on every study.

Three tests do most of the work. First, can the analysis variable be expressed as AVAL/AVALC against a PARAM? If yes, it is BDS, even when that requires normalizing an instrument or transposing a wide collection page. Second, is each record an occurrence of something (an adverse event, a concomitant medication, a protocol deviation) analyzed by counting and categorization? That is OCCDS. Third, is it truly one record per subject? Then it is ADSL or an ADSL-like supplemental subject-level dataset. Only when the record itself (the unit of analysis) is something none of these classes can represent without distortion do you move to a custom structure.

Table 1. Most "custom" candidates are standard structures in disguise. The win ratio example is the rare genuine exception.

4. A worked example: the pairwise comparison dataset

Consider a Phase III chronic heart failure trial, roughly 1,150 subjects randomized 1:1, with a primary endpoint analyzed as a hierarchical composite using the Finkelstein–Schoenfeld method and a win ratio: cardiovascular death, then heart-failure hospitalization frequency, then change from baseline in 6-minute walk distance at Week 24. The statistical analysis operates on pairs of subjects: every active-arm subject compared against every control-arm subject, each pair resolved as a win, loss, or tie at the first hierarchy level that discriminates.

The unit of analysis is the subject pair. No ADaM class has a record key of two USUBJIDs. Stacking pseudo-parameters into BDS produces a dataset where USUBJID no longer identifies the analysis unit, which violates the spirit of the structure far more seriously than declaring a custom class does. So we built ADWR as a custom dataset, class ADAM OTHER in define.xml v2.1, one record per subject pair per hierarchy level evaluated:

Table 2. ADWR key variables. Standard ADaM naming conventions are retained wherever a concept has an ADaM analogue.

Two design decisions mattered more than any other. First, ADWR derives only from other ADaM datasets (ADTTE, an events BDS, and ADSL), never directly from SDTM. That keeps every input value visible in a submitted, analyzable dataset and makes the pairwise logic the only new derivation in the chain. Second, we kept ADaM naming conventions wherever a concept mapped cleanly (TRTP-style variables, SRC* triplets, flag variables ending in FL), so the dataset reads like ADaM even though its class is not.

/* ADWR skeleton: pairwise evaluation from analysis-ready inputs */

proc sql;

create table pairs as

select a.usubjid as usubjid1, b.usubjid as usubjid2,

catx('-', a.usubjid, b.usubjid) as pairid length=42

from adsl(where=(trt01p='ACTIVE' and ittfl='Y')) a,

adsl(where=(trt01p='CONTROL' and ittfl='Y')) b;

quit;

%pair_eval(level=1, source=adtte, paramcd=CVDEATH, rule=tte);

%pair_eval(level=2, source=adhfh, paramcd=HFHRATE, rule=count);

%pair_eval(level=3, source=adeff, paramcd=SMWD, rule=chg, margin=15);

The macro parameters (the level ordering, the tie margin of 15 meters at level 3) are exactly the details a reviewer will want to verify against the SAP. They appear three times, deliberately: in the define.xml method for PAIRRES, in the ADRG Section 5 narrative, and as comment metadata. Redundancy in documentation is cheap; an information request during review is not.

5. The fundamental principles are the acceptance test

A custom structure is compliant when it demonstrably satisfies the ADaM fundamental principles. Treat each principle as a test with named evidence, and write that evidence down before programming starts:

• Traceability. Every analysis value must be traceable to its source. In a custom structure this almost always means data-point traceability (SRCDOM/SRCVAR/SRCSEQ or documented equivalents), because a reviewer cannot lean on structural familiarity to infer where values came from.
• Analysis-readiness. The primary analysis should run against the dataset with minimal manipulation, ideally one procedure call. If your custom dataset still needs a 200-line data step before the model, the structure is wrong.
• Metadata-driven clarity. Define.xml v2.1 must describe the class (ADAM OTHER), every variable, and value-level metadata where a variable’s meaning varies by record type. The dataset should be usable by someone who has read only the metadata.
• Usability with standard tools. Vertical, one-fact-per-record layouts survive; clever nested or wide layouts do not.

6. Documentation: where reviews are won

Validators and reviewers do not object to custom structures; they object to undeclared ones. Three artifacts carry the weight.

ADRG. Section 4 lists the dataset with class ADAM OTHER and, critically, a rationale paragraph: which standard structures were considered, why each fails for this analysis, and what conventions were retained. Auditors consistently report that a two-paragraph rationale eliminates most structure-related questions before they are asked. Section 5 then carries the derivation narrative with a data dependency diagram showing the dataset’s position in the flow.

Define.xml v2.1. Set the dataset class to ADAM OTHER honestly: do not label a non-BDS dataset as BDS to appease a checker. Document derivation methods at the variable level, and use def:CommentDef links for logic too long for a method. A structure that is honest in its metadata converts conformance findings from 'errors' into explained, expected notes.

Conformance disposition. Run CDISC CORE (the open-source rules engine, github.com/cdisc-org/cdisc-rules-engine) and your commercial validator against the dataset knowing that many ADaM conformance rules (v5.0) are conditioned on class. Rules keyed to BDS or OCCDS will simply not fire against ADAM OTHER; rules on general principles (ADSL linkage, USUBJID presence, controlled terminology on flag variables) still will. Every remaining message gets a written disposition in the reviewer’s guide conformance section. An unexplained validator message on a nonstandard dataset reads as negligence; the same message with a disposition reads as engineering.

Table 3. The documentation contract that accompanies any ADAM OTHER dataset.

7. Practical guardrails

A few habits keep custom structures rare and safe. Prototype the primary analysis code before finalizing the structure: analysis-readiness is testable, so test it. Derive custom datasets from ADaM inputs rather than SDTM wherever possible, concentrating novelty in one place. Reuse ADaM naming conventions aggressively; familiarity is a traceability feature. Bring the biostatistician into the structure decision, since the SAP language ('all pairwise comparisons', 'per imputation') usually settles the unit-of-analysis question. And socialize the design with whoever owns your conformance process before database lock, not after the validator report lands.

The taxonomy exists because standard structures are cheaper for everyone: programmer, validator, reviewer. When an analysis genuinely will not fit, the standard gives you room to engineer something better, and the price of that room is documentation. Pay it in full, and custom structures stop being a review risk and become what they should be: the correct representation of the analysis.

8. Conclusion

The structure taxonomy earns its authority from coverage, not from completeness. When the unit of analysis is genuinely something no standard class can represent, ADaM itself directs you to build a custom structure rather than distort BDS, and the compliance question shifts from which class to which evidence. The ADWR example shows the pattern: prove that the standard structures fail, design the custom dataset from ADaM inputs with familiar naming conventions, and verify each fundamental principle with named evidence before programming starts.

The practical takeaways are short. Exhaust ADSL, BDS, and OCCDS with real tests, not preferences. Prototype the primary analysis to confirm analysis-readiness. Declare the class as ADAM OTHER honestly, write the rationale in the ADRG, and give every residual validator message a written disposition. Documentation is the price of the freedom the standard grants; pay it in full and a custom structure stops being a review risk and becomes the correct representation of the analysis.

References

CDISC Analysis Data Model (ADaM) v2.1 and ADaM Implementation Guide v1.3, CDISC, November 2021. Available at cdisc.org/standards/foundational/adam.

CDISC ADaM Structure for Occurrence Data (OCCDS) v1.1, CDISC.

CDISC Define-XML v2.1 Specification, CDISC, 2019.

CDISC ADaM Conformance Rules v5.0; CDISC Open Rules Engine (CORE), github.com/cdisc-org/cdisc-rules-engine.

FDA Study Data Technical Conformance Guide (current edition) and FDA Data Standards Catalog, fda.gov/industry/study-data-standards-resources.

Finkelstein, D.M. and Schoenfeld, D.A. “Combining mortality and longitudinal measures in clinical trials.” Statistics in Medicine, 1999; and Pocock, S.J. et al. “The win ratio.” European Heart Journal, 2012.

PharmaSUG and PHUSE Data Standards track proceedings (lexjansen.com): multiple papers on nonstandard ADaM structures and ADAM OTHER documentation practice, 2019–2025.