Why dictionary version control is a regulatory deliverable (not just a data-management task)

What “traceable” means for coded data

When reviewers challenge an adverse event count or a concomitant medication pattern, they are really testing whether your coded terms can be traced back to the raw descriptions and forward to the analysis without ambiguity. That requires: naming the dictionary and its version in outputs, proving how re-codes were handled, and showing that every change left a trail the team can open in seconds. If your pipeline cannot demonstrate this, re-cuts will drift, and seemingly small recoding decisions will become submission risks.

Start by declaring your dictionaries, once

State plainly which dictionaries govern safety and medication coding and show them to reviewers where they expect to see them—titles, footnotes, metadata, reviewer guides, and the change log. This is where you anchor your process to MedDRA for adverse events and WHODrug for concomitant medications and therapies; the rest of the system (shells, listings, datasets, and CSR text) should echo those declarations, word for word.

The compliance backbone (one paragraph you can reuse everywhere)

Your coded-data controls align to CDISC conventions, with lineage from SDTM into ADaM and machine-readable definitions in Define.xml supported by ADRG and SDRG. Oversight follows ICH E6(R3), estimand language follows ICH E9(R1), and safety exchange is consistent with ICH E2B(R3). Operational expectations consider FDA BIMO; electronic records/signatures meet 21 CFR Part 11 and map to Annex 11. Public transparency stays consistent with ClinicalTrials.gov and EU postings under EU-CTR via CTIS, and privacy respects HIPAA. Every decision leaves an audit trail, systemic issues route through CAPA, risk is tracked with QTLs and governed by RBM, and artifacts are filed to the TMF/eTMF. Cite authorities inline once—FDA, EMA, MHRA, ICH, WHO, PMDA, TGA—and keep the rest operational.

Regulatory mapping: US-first clarity with EU/UK portability

US (FDA) angle—event → evidence in minutes

For US assessors, the most efficient path begins at an AE/CM listing, continues to the coding policy and dictionary version, and ends in the derivation notes that produce counts in safety tables. Titles and footnotes should declare the dictionary (e.g., “MedDRA 26.1” or “WHODrug Global B3 April-YYYY”), and reviewer guides should narrate any mid-study re-codes, including the reason, scope, and before/after impacts. Inspectors expect re-runs to be deterministic for the same cut and parameters; if counts changed due to a dictionary update, you must show the change record and reconciliation listing that explains why.

EU/UK (EMA/MHRA) angle—same truth, localized wrappers

EU/UK reviewers ask the same traceability questions, but they also probe alignment with public narratives (e.g., AESIs, ECIs), dictionary governance, and accessibility (grayscale legibility, clear abbreviations). Keep one truth—dictionary, version, and change control—then adapt only labels and narrative wrappers. If coded terms feed estimand-sensitive endpoints (e.g., NI analyses of safety outcomes), call the version in the footnote and cross-reference the SAP clause to avoid interpretive drift across submissions.

Process & evidence: a version-control system for coded data that reduces rework by 50%+

Freeze names, state versions, and make updates predictable

Publish a one-page coding convention: which dictionary applies to which domains, how synonyms and misspellings are handled, and how multi-ingredient products are mapped. Freeze the notation for versions (“MedDRA 26.1” / “WHODrug Global B3 April-YYYY”) and require the same token to appear in shells, listings, reviewer guides, and specs. Put all dictionary files, mapping tables, and synonym lists under version control; commits should be atomic and tied to change requests.

Run reconciliation listings at each cut

At every database snapshot, run standard listings that show top deltas: new preferred terms, counts that shifted after a dictionary update, and records that failed or changed mapping. File before/after exhibits for material changes with a short narrative of impact on safety tables. This practice prevents “mystery count” escalations near submission.

Make footnotes carry the story reviewers need

Titles and footnotes should name the dictionary and version, declare how partial dates and multiple records per visit are handled, and specify any special mappings (e.g., custom AESI lists). When versions change, the footnote must note the effective date and cross-reference the change log entry, so the story is visible everywhere the numbers appear.

1. Publish a coding convention and freeze dictionary naming and version tokens.
2. Place dictionary source files and synonym tables under version control.
3. Require titles/footnotes to cite dictionary and version across all outputs.
4. Run reconciliation listings at each cut; file before/after exhibits for shifts.
5. Cross-link reviewer guides (ADRG/SDRG) to change logs and specs.
6. Parameterize re-code windows and rules; no hard-coded dates in macros.
7. Capture environment hashes and parameters to ensure reproducible re-runs.
8. Escalate recurring deltas to governance; create CAPA with effectiveness checks.
9. Prove drill-through: output → footnote → change log → listing → source text.
10. File all artifacts to TMF with two-click retrieval from CTMS tiles.

Decision Matrix: choose the right option when dictionaries, synonyms, or products change

Document decisions where inspectors will look first

Maintain a “Dictionary Decision Log”: question → option → rationale → artifacts (change log ID, listing diff, spec snippet) → owner → effective date → effectiveness metric (e.g., query reduction). File to Sponsor Quality and cross-link from ADRG/SDRG so the path from a number to a decision is obvious.

QC / Evidence Pack: the minimum, complete set reviewers expect for coded data

• Coding convention and dictionary governance SOP with version history.
• Dictionary source files and synonym tables under version control (hashes).
• Change log entries with scope, rationale, owner, and impact summaries.
• Reconciliation listings (before/after) for material updates with narrative.
• ADRG/SDRG sections that cite dictionary versions and special handling.
• Shells/listings with versioned titles/footnotes and provenance footers.
• Program headers with lineage tokens and parameter file references.
• Unit tests that cover edge cases (multi-ingredient, local language, duplicates).
• Environment locks and rerun instructions producing byte-identical results.
• TMF filing map with two-click retrieval from CTMS portfolio tiles.

Vendor oversight & privacy

Qualify coding vendors to your convention, enforce least-privilege access, and retain interface logs. For EU/UK subject-level listings, document minimization and residency controls; keep sample redactions and privacy review minutes with the evidence pack.

Footnotes that carry the hard truths: version, exceptions, and special lists

Footnote tokens (copy/paste)

Dictionary version: “Adverse events coded to MedDRA [version]; concomitant medications coded to WHODrug Global [release/format].”
Re-code notice: “Counts reflect re-coding from MedDRA [old]→[new] effective [date]; before/after listing in Appendix [id].”
Special lists: “AESIs reviewed per sponsor list v[xx]; ECIs flagged in listing [id].”

Where to put the tokens

Put the version token in every safety table title and in the AE/CM listing titles; put re-code tokens in footnotes at the first output impacted by the change; repeat only where numbers could be misread without the context. Use the same token strings in metadata (Define.xml) and reviewer guides.

Common pitfalls & quick fixes

Pitfall: Version changes without visible notice → Fix: footnote token + change-log ID + reconciliation listing. Pitfall: Shadow synonym lists → Fix: govern additions with approvals and hashes; publish diffs. Pitfall: Multi-ingredient mapping drift → Fix: controlled split-map with tests and a visible policy.

Operational cadence: keep dictionaries, programs, and narratives synchronized

Parameterize what humans forget

Externalize dictionary versions, effective dates, and AESI/ECI lists in parameter files—not in macros. Run logs must echo parameters verbatim, and outputs must include a provenance footer (program path, timestamp, data cut, parameter file) so reviewers can re-run without archaeology.

Dry runs and “coding days”

Schedule cross-functional readouts where clinicians, safety physicians, programmers, and QA review the latest deltas, re-coded terms, and their impact on tables. File minutes and before/after exhibits; convert recurring issues into CAPA with effectiveness checks.

Measure what matters

Track time-to-reconcile after a dictionary update, count of material shifts per cut, percentage of outputs with correct version tokens, and drill-through time (output → change log → listing → source). Set thresholds in portfolio QTLs and escalate exceptions.

FAQs

How prominently should dictionary versions appear?

Prominently enough that a reviewer cannot miss them: in safety table titles, AE/CM listing titles, footnotes where the context is critical, and in reviewer guides. The same token must also appear in Define.xml/metadata so machine and human readers see the same truth.

What’s the fastest way to prove a count changed because of a dictionary update?

Open the output footer (program path/parameters), show the footnote with the version token and change-log ID, and then open the reconciliation listing that lists the before/after pairs. Close with the governance minute that approved the update. That three-step path resolves most queries.

How should we handle multi-ingredient products in WHODrug?

Adopt a controlled split-map policy, document it in the convention, and test with synthetic fixtures. Footnote any departures from the default (e.g., product-level mapping when exposure analysis requires aggregates) and file the mapping table with the evidence pack.

Do mid-study MedDRA updates always require re-coding?

No. If timelines are tight and the impact is modest, lock the version for the current cut and schedule re-coding for the next one. Document the decision, the risk, and the plan in governance minutes, and carry a footnote that explains the lock to avoid confusion.

Where should synonym lists live, and how are they governed?

Under version control next to dictionary source files. Additions require change requests, approvals, and hashes. Publish diffs and run a targeted reconciliation listing to show the impact of new synonyms on counts or mappings.

How do we prevent version drift between shells, listings, and reviewer guides?

Centralize tokens in a shared library referenced by shells, programs, and guide templates. When the version changes, update the token once, regenerate outputs, and re-run automated checks that ensure the token appears where required.

Outcome-first ADaM: derivations that survive questions, re-cuts, and inspection sprints

What “defensible” means in practice

Defensible ADaM derivations are those that a new reviewer can trace, reproduce, and explain without calling the programmer. That requires three things: (1) explicit lineage from SDTM to analysis variables; (2) clear and versioned business rules tied to a SAP/estimand reference; and (3) automated unit tests that fail loudly when inputs, algorithms, or thresholds change. If any of these are missing, re-cuts become fragile and inspection time turns into archaeology.

State one compliance backbone—once

Anchor your analysis environment in a single, portable paragraph and reuse it across shells, SAP, standards, and CSR appendices: inspection expectations reference FDA BIMO; electronic records and signatures follow 21 CFR Part 11 and map to Annex 11; GCP oversight and roles align to ICH E6(R3); safety data exchange and narratives acknowledge ICH E2B(R3); public transparency aligns to ClinicalTrials.gov and EU postings under EU-CTR via CTIS; privacy follows HIPAA. Every change leaves a searchable audit trail; systemic issues route through CAPA; risk is tracked with QTLs and managed via RBM. Patient-reported and remote elements feed validated eCOA pipelines, including decentralized workflows (DCT). All artifacts are filed to the TMF/eTMF. Standards use CDISC conventions with lineage from SDTM to ADaM, and statistical claims avoid ambiguity in non-inferiority or superiority contexts. Anchor this stance one time with compact authority links—FDA, EMA, MHRA, ICH, WHO, PMDA, and TGA—and then get back to derivations.

Define the outcomes before you write a single line of code

Set three measurable outcomes for your derivation work: (1) Traceability—every analysis variable includes a one-line provenance token (domains, keys, and algorithms) and a link to a test; (2) Reproducibility—a saved parameter file and environment hash can recreate results byte-identically for the same cut; (3) Retrievability—a reviewer can open the derivation spec, program, and associated unit tests in under two clicks from a portfolio tile. If you can demonstrate all three on a stopwatch drill, you are inspection-ready.

Regulatory mapping: US-first clarity that ports cleanly to EU/UK review styles

US (FDA) angle—event → evidence in minutes

US assessors frequently select an analysis number and drill: where is the rule, what data feed it, what are the intercurrent-event assumptions, and how would the number change if a sensitivity rule applied? Your derivations must surface that story without a scavenger hunt. Titles, footnotes, and derivation notes should name the estimand, identify analysis sets, and point to Define.xml, ADRG, and the unit tests that guard the variable. When a reviewer asks “why is this value here?” you should be able to open the program, show the spec, run the test, and move on in minutes.

EU/UK (EMA/MHRA) angle—identical truths, different wrappers

EMA/MHRA reviewers ask the same questions but often emphasize estimand clarity, protocol deviation handling, and consistency with registry narratives. If US-first derivation notes use literal labels and your lineage is explicit, the same package translates with minimal edits. Keep a label cheat (“IRB → REC/HRA; IND safety alignment → regional CTA safety language”) in your programming standards so everyone speaks the same truth with local words.

Process & evidence: a derivation spec that actually prevents rework

The eight-line derivation template that scales

Use a compact, mandatory block for each analysis variable: (1) Name/Label; (2) Purpose (link to SAP/estimand); (3) Source lineage (SDTM domains, keys); (4) Algorithm (pseudo-code with thresholds and tie-breakers); (5) Missingness (imputation, censoring); (6) Time windows (visits, allowable drift); (7) Sensitivity (alternative rules); (8) Unit tests (inputs/expected outputs). This short form makes rules readable and testable and keeps writers, statisticians, and programmers synchronized.

Make lineage explicit and mechanical

List SDTM domains and keys explicitly—e.g., AE (USUBJID, AESTDTC/AETERM) → ADAE (ADY, AESER, AESDTH). If derived across domains, depict the join logic (join keys, timing rules). Ambiguity here is the #1 cause of late-stage rework because different programmers resolve gaps differently. A one-line lineage token in the program header prevents drift.

1. Enforce the eight-line derivation template in specs and program headers.
2. Require lineage tokens for every analysis variable (domains, keys, algorithm ID).
3. Map each rule to a SAP clause and estimand label (E9(R1) language).
4. Declare windowing/visit rules and how partial dates are handled.
5. Predefine sensitivity variants; don’t bolt them on later.
6. Create unit tests per variable with named edge cases and expected values.
7. Save parameters and environment hashes for reproducible reruns.
8. Drill from portfolio tiles → shell/spec → code/tests → artifacts in two clicks.
9. Version everything; tie changes to governance minutes and change summaries.
10. File derivation specs, tests, and run logs to the TMF with cross-references.

Decision Matrix: choose derivation strategies that won’t unravel during review

Document the “why” where reviewers will actually look

Maintain a Derivation Decision Log: question → option → rationale → artifacts (SAP clause, spec snippet, unit test ID) → owner → date → effectiveness (e.g., query reduction). File in Sponsor Quality and cross-link from the spec and code so the path from a number to a decision is obvious.

QC / Evidence Pack: the minimum, complete set that proves your derivations are under control

• Derivation specs (versioned) with lineage, rules, sensitivity, and unit tests referenced.
• Define.xml pointers and reviewer guides (ADRG/SDRG) aligned to variable metadata.
• Program headers with lineage tokens, change summaries, and run parameters.
• Automated unit test suite with coverage report and named edge cases.
• Environment lock files/hashes; rerun instructions that reproduce byte-identical results.
• Change-control minutes linking rule edits to SAP amendments and shells.
• Visual diffs of outputs pre/post change; threshold rules for acceptable drift.
• Portfolio drill-through maps (tiles → spec → code/tests → artifact locations).
• Governance minutes tying recurring defects to CAPA with effectiveness checks.
• TMF cross-references so inspectors can open everything without helpdesk tickets.

Vendor oversight & privacy

Qualify external programming teams against your standards; enforce least-privilege access; store interface logs and incident reports near the codebase. Where subject-level listings are tested, apply data minimization and de-identification consistent with privacy and jurisdictional rules.

Versioning discipline: prevent drift with simple, humane rules

Semantic versions plus change summaries

Use semantic versioning for specs and code (MAJOR.MINOR.PATCH). Every change must carry a top-of-file summary that states what changed, why (SAP clause/governance), and how to retest. Small cost now, huge savings later when a reviewer asks why Week 24 changed on a re-cut.

Freeze tokens and naming

Freeze dataset and variable names early. Late renames create invisible fractures across shells, CSR text, and validation macros. If you must rename, deprecate with an alias period and unit tests that fail if both appear simultaneously to avoid shadow variables.

Parameterize time and windows

Put time windows, censoring rules, and reference dates in a parameters file checked into version control. It prevents “magic numbers” in code and lets re-cuts use the right windows without manual edits. Unit tests should load parameters so a changed window forces test updates, not silent drift.

Unit tests that matter: what to test and how to keep tests ahead of change

Test the rules you argue about

Focus tests on edge cases that trigger debate: partial dates, overlapping visits, duplicate ids, ties in “first” events, and censoring at lock. Encode one or two examples per edge and assert exact expected values. When an algorithm changes, tests should fail where your conversation would have started anyway.

Golden records and minimal fixtures

Create tiny, named fixtures that cover each derivation pattern. Avoid giant “real” datasets that hide signal; use synthetic rows with clear intent. Keep golden outputs in version control; diffs show exactly what changed and why, and reviewers can read them like a storyboard.

Coverage that means something

Report code coverage but don’t chase 100%—chase rule coverage. Every business rule in your spec should have at least one test. Include failure-path tests that assert correct error messages when assumptions break (e.g., missing keys, illegal window values).

Templates reviewers appreciate: paste-ready tokens, footnotes, and rationale language

Spec tokens for fast comprehension

Purpose: “Supports estimand E1 (treatment policy) for primary endpoint.”
Lineage: “SDTM LB (USUBJID, LBDTC, LBTESTCD) → ADLB (ADT, AVISIT, AVAL).”
Algorithm: “Baseline = last non-missing pre-dose AVAL within [−7,0]; change = AVAL – baseline; if missing baseline, impute per SAP §[ref].”
Sensitivity: “Per-protocol window [−3,0]; tipping point ±[X] sensitivity.”

CSR-ready footnotes

“Baseline defined as the last non-missing, pre-dose value within the pre-specified window; if multiple candidate records exist, the earliest value within the window is used. Censoring rules are applied per SAP §[ref], with administrative censoring at database lock. Intercurrent events follow the treatment-policy strategy; a hypothetical sensitivity is provided in Table S[ref].”

Rationale sentences that quell queries

“The tie-breaker chain (chronology → quality flag → mean of remaining) minimizes bias when multiple records exist and reflects clinical practice where earlier, higher-quality measurements dominate. Sensitivity analyses demonstrate effect stability across window definitions.”

FAQs

How detailed should an ADaM derivation spec be?

Short and specific. Use an eight-line template covering purpose, lineage, algorithm, missingness, windows, sensitivity, and unit tests. The goal is that a reviewer can forecast the output’s behavior without reading code, and a programmer can implement without guessing.

Where should we store derivation rationale so inspectors can find it?

In three places: the spec (short form), the program header (summary and links), and the decision log (why this rule). Cross-link all three and file to the TMF. During inspection, open the decision log first to show intent, then the spec and code to show execution.

What makes a good unit test for ADaM variables?

Named edge cases with minimal fixtures and explicit expected values. Tests should assert both numeric results and the presence of required flags (e.g., imputation indicators). Include failure-path tests that prove the program rejects illegal inputs with clear messages.

How do we handle multiple registry or public narrative wordings?

Keep derivation text literal and map public wording via a label cheat sheet in your standards. If you change a public narrative, open a change control ticket and verify no estimand or analysis definitions drifted as a side effect.

How do we prevent variable name drift across deliverables?

Freeze names early, use aliases temporarily when renaming, and add tests that fail on simultaneous presence of old/new names. Update shells, CSR templates, and macros from a single dictionary to keep words and numbers synchronized.

What evidence convinces reviewers that our derivations are stable across re-cuts?

Byte-identical rebuilds for the same data cut, environment hashes, parameter files, and visual diffs of outputs pre/post change with thresholds. File stopwatch drills showing you can open spec, code, and tests in under two clicks and reproduce results on demand.