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

How large studies end up with hundreds of parameters, and the naming, value-level metadata, and controlled terminology discipline that keeps define.xml maintainable.

Abstract

Large clinical trials routinely accumulate hundreds of analysis parameters, and a single Phase III submission can lock its database with close to a thousand distinct PARAMCD values spread across many BDS datasets. Each parameter is a small contract binding a code, a label, value-level metadata, and controlled terminology, so the real cost of scale is not storage but the metadata surface that reviewers must navigate. This article argues that parameter explosion is a governance problem rather than a naming inconvenience. It shows how counts grow, why the eight-character PARAMCD limit forces a documented naming scheme, and how a single generated parameter registry can drive both programming specifications and define.xml. It then covers stratified value-level metadata, the categorization and ordering variables that keep parameters navigable, and the boundary between sponsor-defined and controlled terminology. The takeaway is that disciplined, mechanically enforced metadata, owned by one accountable function from study startup, produces a define.xml that stays reviewable at any parameter count.

1. Introduction

No study team sets out to create a thousand analysis parameters, yet large oncology and multi-instrument trials arrive there almost inevitably. Every laboratory test, patient-reported outcome instrument, pharmacokinetic analyte, and tumor assessment spawns families of derived values, and each one demands a unique code, a unique label, and its own value-level metadata. Left ungoverned, the result is a define.xml that is technically valid but practically unreviewable, and a maintenance surface where each new sensitivity analysis risks a naming collision. Managing this well matters because parameter debt, once accumulated, surfaces at the worst possible moment: the validator-findings sprint just before database lock.

This article treats the problem as one of governance rather than nomenclature. Section 2 shows how parameter counts grow in a realistic study. Section 3 explains why the eight-character PARAMCD limit is a design constraint that forces a documented naming scheme. Section 4 introduces the parameter registry as a single source from which specifications and define.xml are generated. Section 5 covers stratified value-level metadata, and Section 6 addresses the categorization and ordering variables that keep parameters navigable. Section 7 clarifies what controlled terminology does and does not govern, and Section 8 draws the practices together into a governance model with a named owner.

2. How you get to a thousand parameters

No one plans a parameter explosion. The example used throughout this article is a composite drawn from several submissions rather than a single study: a Phase III oncology programme of roughly 640 subjects, two arms, a BICR, sparse PK, and an eight-instrument PRO battery, which locked its database with 967 distinct PARAMCD values across nine BDS datasets. Each one arrived reasonably: every lab test needs conventional and SI representations; every PRO instrument spawns item scores, domain scores, totals, and change-derived parameters, which is why ADQS sits second only to ADLB by volume; the tumor data needs per-timepoint sums, nadirs, and percent changes; PK needs analyte-by-matrix combinations. Multiply by baseline-definition variants and sensitivity versions, and a four-digit parameter count stops looking exotic. The specific total matters less than the shape of the curve, which is the same on every large study: two or three datasets carry most of the count, and none of them are the ones the reviewer cares most about.

Figure 1. Parameter counts by dataset for the example study: 967 parameters across nine BDS datasets. The high-volume findings datasets (blue) account for most of the count, while the efficacy datasets (orange, ADTR among them) account for most of the review attention.

The cost is not storage; it is metadata. Every parameter is a contract: a unique PARAMCD, a unique PARAM, value-level metadata in define.xml describing how AVAL behaves for that parameter, and controlled terminology governing its qualifiers. At this scale, an undisciplined approach produces a define.xml that is technically valid and practically unreviewable, and a maintenance surface where every new sensitivity analysis risks a naming collision.

3. PARAMCD discipline: eight characters is a design constraint

PARAMCD is limited to 8 characters, must start with a letter rather than an underscore, and may contain only letters, underscores, and numerals (A–Z, _, 0–9), the same constraints as SDTM test codes, per ADaMIG v1.3 §3.3.4.1. Underscores are legal; a house style that forbids them is a house style, not a standard, so be explicit about which of the two you are enforcing when you write the checks. Within one dataset PARAMCD must map 1:1 to PARAM (each PARAMCD has exactly one PARAM text and vice versa). Eight characters across 300 lab parameters forces a scheme, and the scheme must be written down before the first spec is drafted, because retrofitting one after 40 datasets exist is a database-lock risk.

The scheme that has held up best in our experience is positional: a stem inherited from the SDTM test code, followed by qualifier positions with fixed meanings. The exact convention matters less than three properties: it is documented, it is enforced mechanically, and it degrades predictably when a name would exceed 8 characters (documented abbreviation list, no ad-hoc truncation). One caution on stems: check that an inherited abbreviation does not collide with a common term in your therapeutic area. EGFR reads as epidermal growth factor receptor to every oncology reviewer, whatever your lab terminology says it means, so a renal-function parameter is better off with an unambiguous sponsor stem.

Table 1. A positional PARAMCD scheme. The point is not this scheme. It is having one, in writing, with an owner.

Two rules deserve special emphasis. Cross-dataset consistency: the 1:1 PARAM/PARAMCD mapping is formally required within a dataset, but allowing PARAMCD=GLUC to mean fasting glucose in ADLB and any glucose in ADEF is a reviewer trap; maintain the registry globally. No semantic overloading: if the population of records differs (central vs local lab, investigator vs BICR), that is a distinct parameter, or a sponsor-defined qualifier variable you have documented in define.xml, never an undocumented convention that “the ANL01FL records are BICR.”

4. The parameter registry: treat parameters as data

At scale, parameter metadata cannot live in per-dataset spec tabs that drift independently. The teams that stay sane maintain a single parameter registry, one row per PARAMCD per dataset, from which both the programming specs and the define.xml value-level metadata are generated. Whether the registry lives in a metadata repository or a governed workbook matters less than the generation direction: specs and define are outputs of the registry, never independently edited.

/* Mechanical enforcement belongs in the pipeline, not in review meetings. */

proc sql;

/* 1:1 violations, both directions, within each dataset */

select memname, paramcd, count(distinct param) as n_param

from work.all_bds_params

group by memname, paramcd having count(distinct param) > 1;

select memname, param, count(distinct paramcd) as n_paramcd

from work.all_bds_params

group by memname, param having count(distinct paramcd) > 1;

/* Length and character-set violations (letters, digits, underscore) */

select distinct paramcd from work.all_bds_params

where length(paramcd) > 8 /* fires only if the column exceeds $8 */

or notalpha(char(paramcd,1)) > 0 /* first character must be a letter */

or notalnum(compress(paramcd,'_ ')) > 0;

/* Orphans: in data but not in registry, or vice versa */

select coalesce(d.paramcd, r.paramcd) as paramcd,

d.memname, r.memname as reg_memname

from work.all_bds_params d full join meta.param_registry r

on d.paramcd = r.paramcd and d.memname = r.memname

where d.paramcd is null or r.paramcd is null;

quit;

The registry also solves the cross-functional problem that naming schemes alone cannot: parameters are consumed by people who did not create them. The biostatistician writing the SAP references parameters by PARAM text; the TFL programmer filters by PARAMCD; the define.xml developer needs the family assignment; the ISS team, two years later, needs to know whether GFREST in this study used CKD-EPI or MDRD. One governed row per parameter (with columns for derivation family, source test code, unit convention, SAP reference, and first-use deliverable) answers all four audiences from one place. Studies that skip this discover the answers live in six people's inboxes, at least two of whom have rolled off the study.

The orphan check is the one that pays for itself. Parameters that exist in data but not in the registry are usually a spec change that bypassed governance; parameters in the registry but not in data are usually a planned analysis that silently fell out of a derivation. Both are findings you want three months before database lock, not in a validator report three days after.

5. Value-level metadata: where define.xml earns its keep

In a BDS dataset, AVAL means nothing without its parameter; define.xml v2.1 value-level metadata (VLM) is the mechanism that gives each parameter its own description, origin, method, and format, via where-clauses on PARAMCD. The failure mode at scale is symmetrical: too little VLM (one generic entry for AVAL, 300 parameters left undescribed) or too much (300 VLM entries that are 95% identical boilerplate, burying the ones that matter).

The workable middle ground is stratified VLM. Group parameters into derivation families and describe each family once, with parameter-specific entries only where behavior genuinely diverges:

Table 2. Stratified value-level metadata: boilerplate once per family, individual entries reserved for parameters with unique logic.

This is also where the registry pays off again: the family assignment is a registry column, and the define.xml VLM section is generated by iterating families, then overriding with parameter-level entries. Reviewers see a define where every individually-described parameter is individually interesting, a strong signal-to-noise property that experienced assessors notice.

6. PARCAT, PARAMN, and the navigation layer

Naming keeps parameters unique; it does not keep a thousand of them navigable. That is the job of the categorization and ordering variables, and they deserve the same governance as the codes themselves. PARCAT1, PARCAT2, and the rest of the PARCATy family provide a hierarchy above the parameter: panel within ADLB (PARCAT1='CHEMISTRY', PARCAT2='LIVER FUNCTION'), instrument within ADQS, analyte within ADPC. Two rules prevent the common abuses. A PARCATy value must be an attribute of the parameter, not of the record, which is the ADaMIG v1.3 §3.3.4.1 rule that any given PARAM may be associated with at most one level of PARCATy: if some records for PARAMCD=ALT would carry one category and some another, the concept you are encoding is record-level (an ANLzzFL, a documented sponsor qualifier, or a separate parameter) and does not belong in PARCATy. And the hierarchy must be stable across datasets and deliverables, since a liver-panel definition that differs between ADLB and a dedicated hepatotoxicity dataset will eventually contradict itself in front of a reviewer.

PARAMN looks trivial and is the single most common source of silent display-order bugs at scale. Assign it once, in the registry, with gaps (10, 20, 30…) so later insertions do not force renumbering; require uniqueness within dataset with the same mechanical check as the 1:1 rule; and never let two deliverables sort the same dataset by different PARAMN assignments. Teams that generate PARAMN from registry row order (rather than maintaining it as an independent column) get all of this for free.

7. Controlled terminology: what is and is not controlled

A persistent misconception is that PARAMCD values come from CDISC controlled terminology. They do not. PARAM/PARAMCD are sponsor-defined. What is governed: the SDTM test-code terminology you should inherit stems from (deviating from LBTESTCD roots without cause creates gratuitous reviewer friction); ADaM variable-level terminology such as DTYPE and PARAMTYP, and flag values (Y/null), published in the CDISC ADaM CT package and updated quarterly; and your own sponsor extensions, which belong in a documented sponsor codelist in define.xml, not in tribal memory. A word on PARQUAL, which circulates in draft specifications as though it were standard: it appeared in the ADaMIG v1.2 public-review draft, was withdrawn before finalization, and is not a variable in ADaMIG v1.3. It remains under consideration, alongside a qualifier-type variable, for a future release. Until it lands, anything you call PARQUAL is a sponsor extension and needs a sponsor codelist to match. Pin the CT version per study (it is declared in define.xml and the ADRG), and diff parameter-relevant codelists when you uplift versions mid-development, because CT is extended and revised every quarter and an inherited stem that silently diverges from current CT is a conformance finding waiting to fire.

8. Scale is a governance problem wearing a naming costume

Every practice in this article (positional naming schemes, a generated registry, stratified VLM, pinned terminology) is mechanical. None of it requires new tools, and all of it can be retrofit-audited with the PROC SQL above. What it requires is an owner: one person (or one small metadata function) with authority over parameter creation, consulted before any spec adds a PARAMCD, running the checks on every dry run. In our experience, studies that assign that owner at startup arrive at lock with a define.xml a reviewer can navigate, whatever the parameter count. Studies that do not, discover their parameter debt during the address-validator-findings sprint, the most expensive possible time to learn that PARAMCD was never really eight characters of free text.

9. Conclusion

Managing parameters at scale is a governance problem wearing a naming costume. The individual techniques described here, a positional naming scheme, a generated registry, stratified value-level metadata, disciplined categorization and ordering variables, and pinned controlled terminology, are all mechanical and require no new tooling. Their value comes from being enforced automatically and consistently, so that violations surface on every dry run rather than in a validator report after lock.

The practical takeaways are straightforward. Decide the naming scheme and write it down before the first specification exists. Make the registry the single source of truth, generating specs and define.xml from it rather than editing them independently. Run the mechanical checks continuously, and above all assign one accountable owner for parameter creation at study startup. Teams that do this arrive at lock with a define.xml that stays navigable as the parameter count grows; teams that do not pay for it later, at the most expensive possible time.

References

CDISC ADaM Implementation Guide v1.3, Section 3.3.4 (analysis parameter variables for BDS datasets; PARAM/PARAMCD requirements), CDISC, 29 November 2021.

CDISC Define-XML v2.1 Specification: value-level metadata and where-clauses, CDISC, 2019.

CDISC Controlled Terminology, ADaM CT package (quarterly releases), evs.nci.nih.gov / cdisc.org/standards/terminology.

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): define.xml expectations, fda.gov.

PharmaSUG and SESUG proceedings (lexjansen.com): papers on parameter-level metadata management and metadata-driven define.xml generation, 2017–2025.

Minjoe, S. ADaM Discussion Topics: PARQUAL, ADPL, Nadir. PharmaSUG 2024, Paper DS-204 (lexjansen.com): status of PARQUAL relative to ADaMIG v1.3.