Algorithms & Dictionaries — Change Control & Release Notes

Why this matters

If your algorithms (the rules that calculate derived variables) or your medical dictionaries change without control, you cannot reproduce past results or pool data across studies with confidence. A simple example: adverse events (AEs) coded with one MedDRA version in Study A and another version in Study B can roll up to different Preferred Terms or System Organ Classes, shifting incidence rates.

Change control, versioning, and clear release notes protect:

• Regulatory defensibility (audit trail, 21 CFR Part 11–aligned practices).
• Scientific integrity (same inputs → same outputs).
• Operational efficiency (teams know what changed and why).
• Cross‑study comparability (dictionary parity for pooled analyses, such as an integrated summary of safety).

Core concepts & definitions

• Derivation Any logic that computes a variable from other data (e.g., average blood pressure from two readings, imputation rules, unit conversions). Treat each derivation like software: it has a name and version.

• Derivation catalog A maintained list (or table) of all derived variables with: derivation_name, derivation_version, plain‑language description, inputs, edge‑case handling, and links to tests.

• Medical dictionaries

  • MedDRA = Medical Dictionary for Regulatory Activities (used for AEs and medical history).
  • WHODrug Global (used for concomitant medications and drug coding). Each dictionary has versions. MedDRA releases twice a year (x.0 in March, x.1 in September); terms are coded to a Lowest Level Term (LLT) that links to one Preferred Term (PT), and each PT has one primary System Organ Class (SOC). A new version can re‑link an LLT to another PT, make it non‑current or move a PT’s primary SOC. WHODrug Global also releases twice a year (March, September), changing drug names and ATC (Anatomical Therapeutic Chemical) classes.

• Dictionary parity Ensuring all datasets that will be compared or pooled use the same dictionary version. When versions differ, plan a recode.

• Release note A concise, plain‑English document for each change. It states what changed, why, when, versions involved, testing performed, and measurable data impact (e.g., rows affected, % change).

• Freeze window A period (e.g., pre‑lock) when changes are avoided. If a change is unavoidable, perform an impact assessment, obtain approvals, and document thoroughly. (Unlike an EDC data freeze, which blocks edits to clean data.)

• Database lock The point where data are considered final for analysis. Lock removes edit rights; any change to locked data needs a documented, approved unlock (per SOP).

• Data deltas The specific, countable differences introduced by a change (e.g., “1.4% of visits’ mean BP changed”).

• Blinding considerations Some changes could unblind treatment (e.g., logic that reads randomization or treatment‑arm codes, or deltas split by arm; treatment‑emergent flags use dosing dates, not the arm). Assess and gate such changes; blinded teams see only all‑arm deltas.

Change control, step‑by‑step

1. Propose Submit a change request describing:

   • Scope (derivation, MedDRA, WHODrug, mapping, or configuration).
   • Rationale (bug fix, new requirement, dictionary upgrade, standards alignment).
   • Timing (is there a freeze window? proximity to database lock?).

2. Impact assess Identify:

   • Affected variables/domains, tables, and listings.
   • Risk to blinding and interim analyses.
   • Recode needs for dictionaries; effect on pooling/meta‑analysis.
   • Downstream impacts (programs, visualizations, mapping to CDISC SDTM (tabulation) and ADaM (analysis) datasets, safety review).
   • Plan to quantify deltas (counts and percentages).

3. Validate

   • Write and run tests, including negative tests (prove incorrect inputs are handled safely), with review or independent re‑programming by someone other than the author.
   • Regression tests (prove unchanged areas remain stable).
   • Capture failed tests, fixes, and re‑tests in the record.

4. Decide Obtain sign‑offs from the appropriate roles (the RACI names one accountable approver; the others sign for their area):

   • Clinical Data Management (CDM) Lead.
   • Biostatistician/Statistical Programming Lead.
   • Pharmacovigilance/Medical Safety (for dictionary or AE logic).
   • Quality Assurance (as required by your SOPs).

5. Release note Publish with:

   • What changed and why (plain language).
   • Old → new versions (derivation and/or dictionary).
   • Data deltas (rows/subjects affected, % change, before/after tallies).
   • Validation summary and approvals.
   • Effective date and environment (test, user acceptance testing [UAT], production) and rollback plan.

6. Deploy

   • Bump the derivation_version (and dictionary version if applicable).
   • Update the freeze manifest (the list of locked logic, programs, dictionaries).
   • Notify stakeholders (CDM, Biostatistics, PV, Medical Monitor, study team).
   • Archive prior logic and release notes in a traceable location.

7. Pool For cross‑study analyses:

   • Choose a target dictionary version (usually a recent version, e.g., the one the safety database or the newest study uses; among recent versions, one that feeder studies already use keeps the recode small).
   • For trials intended for pooling, plan this up front: a program‑level version policy and shared coding conventions in each study’s Data Management Plan (e.g., common planned upgrade points).
   • Recode feeder studies to the target version or document justified exceptions. Only coded terms change; the site’s verbatim term stays as entered. In an ongoing study, unclear verbatims are queried to the site; for a locked study, recode in the pooled datasets (its locked database and report keep their original version) and document coding decisions.
   • Track changes in Preferred Terms and System Organ Classes (MedDRA) or drug names/ATCs (WHODrug).

What good looks like

• Every dataset with derived variables contains fields like: derivation_name, derivation_version, derivation_source (where the logic lives), and dictionary_version where relevant.
• Safety and medical history domains visibly carry the MedDRA version used; concomitant medications carry WHODrug version. In submission datasets (CDISC SDTM/ADaM), this traceability usually sits in define.xml metadata (dictionary versions, derivation methods) rather than extra columns.
• Each change has a release note with a delta listing and sign‑offs.
• Pooling plans explicitly state the target dictionary version and the recode strategy (tools, checks, and acceptance criteria).
• The Data Management Plan (DMP) recognizes that it is living and provides budget/time for well‑controlled updates.

Worked examples (CV trial)

Example 1 — Derivation fix: mean blood pressure (self‑contained)

Context

A cardiovascular (CV) study captures two replicate systolic blood pressure (SBP) readings per visit: SBP1 and SBP2. The derived variable SBP_MEAN is used in endpoints.

Problem

Current logic (v1.2) averages both values even when one is missing, incorrectly treating a missing value as zero.

Change

Update derivation (v1.3), in line with the statistical analysis plan (SAP), to:

• Use the non‑missing reading when only one reading is present.
• Use the average when both are present.
• Result remains missing if both are missing. (No equations needed: think “use what you have; average when you have two.”)

Validation

• Test cases include: both present, one present, both missing, implausible values.
• Regression: confirm unrelated vitals unaffected.

Data delta (measured)

• 1.4% of visit records (168 of 12,000, in 97 subjects) show a different SBP_MEAN after the fix.
• No subject’s primary endpoint classification changes.

Release note (excerpt)

• What changed: SBP_MEAN derivation logic updated from v1.2 → v1.3 to correctly handle missing replicates.
• Why: Bug fix to prevent implicit zero.
• Impact: 168 of 12,000 visit records (1.4%) in 97 subjects affected; no change to primary endpoint classification.
• Approvals: CDM Lead, Biostatistician.
• Effective date: 2025‑03‑15.
• Rollback: revert to v1.2 and re‑run pipeline.

In‑data traceability

Datasets now include: derivation_name = 'sbp_mean', derivation_version = '1.3'.

Example 2 — Dictionary upgrade for pooling (self‑contained)

Context

Two CV studies will be pooled for safety analysis.

• Study A coded AEs with MedDRA 26.1.
• Study B coded AEs with MedDRA 27.0.

Problem

Direct pooling risks mismatched Preferred Terms (PTs) and System Organ Classes (SOCs).

Decision

Adopt MedDRA 27.0 (Study B’s version, so only Study A is recoded) as the target version.

Action

• Recode Study A from 26.1 → 27.0 using a validated migration utility.
• Produce a change log listing AE records whose PT/SOC changed.

Validation

• Spot‑check samples where PT changed; confirm expected roll‑ups.
• Tally before/after counts by PT and SOC.
• Confirm medical review for clinically sensitive terms.

Data delta (measured)

• 3.2% of AE rows (64 of 2,000) changed PT; 0.7% (14 of 2,000) changed SOC.
• Seriousness/outcome flags unchanged.

Release note (excerpt)

• What changed: AE dictionary upgraded for Study A to MedDRA 27.0 to enable pooling with Study B.
• Why: Achieve dictionary parity for the pooled safety analysis.
• Impact: PT changes in 64 of 2,000 AE rows (3.2%); SOC changes in 14 (0.7%).
• Recoding decisions: terms needing a new choice (e.g., an LLT made non‑current) were recoded after medical review and listed, with reasons, in the change log.
• Approvals: PV Lead, CDM Lead, Biostatistician.
• Effective date: 2025‑04‑02.

In‑data traceability

Add meddra_version = '27.0' to the pooled AE datasets (for submission datasets, record it in define.xml); retain a migration mapping file in the archive.

Example 3 — Concomitant medications: WHODrug recode (self‑contained)

Context

Concomitant medications were coded in Study C with an older WHODrug Global release (March 2022), while Study D used a current one (March 2025). Formats such as B3 or C3 set only the file layout and product detail; it is the release that changes drug names and ATC assignments.

Problem

ATC classification and product names differ; pooling by ATC class is inconsistent.

Decision & Action

• Standardize both studies to the March 2025 release (Study D’s version) for pooling.
• Recode Study C to that release and document all product/ATC changes; where a drug has several ATC codes, apply one ATC selection rule (e.g., by indication) in both studies.

Data delta (measured)

• 5.6% of Study C’s concomitant medication rows (280 of 5,000) changed product name; 1.9% (95 of 5,000) changed ATC class (level 3 or 4).

Release note (excerpt)

• What changed: Study C concomitant medications recoded to WHODrug Global March 2025 to match Study D for pooled analysis.
• Impact: 280 of 5,000 Study C rows (5.6%) changed product name; 95 (1.9%) changed ATC class; clinical conclusions unchanged.
• Approvals: CDM Lead, PV Lead, Biostatistician.
• Effective date: 2025‑05‑10.

Pitfalls & misconceptions

• “Naming the algorithm is enough.” Not true. You must store the version with the name. Without a version, you cannot tell which logic generated a value.

• “Pooling can handle mixed dictionary versions.” Mixing versions silently shifts counts and rates. Always choose a target version and recode or justify and document exceptions.

• “Small changes don’t need notes.” Even a one‑line fix can move results. Publish a release note with quantified deltas.

• “We can change right before lock if needed.” Late changes are high risk for errors and unblinding. Use freeze windows and elevate exceptions with impact assessments.

• “Tests passed, so we’re done.” Capture failed tests and re‑tests in the record. Auditors often ask, “What failed first and how did you fix it?”

Practice in the wild (checklist)

• Maintain a derivation catalog with clear names, versions, plain‑language descriptions, inputs, and tests.
• Carry derivation_name and derivation_version in datasets that contain derived values.
• Record dictionary versions (MedDRA/WHODrug) in the relevant datasets.
• For every change, issue a release note with quantified data deltas and approvals.
• Define and honor freeze windows; document any exceptions with impact and sign‑offs.
• For pooling, select a target dictionary version and plan recoding with acceptance criteria.
• Archive prior logic, mapping files, and release notes in a retrievable location.
• Include blinding risk checks in impact assessments.
• Add a rollback plan to each release note.

Key points to remember

• Treat every derivation as versioned software. Maintain a derivation catalog and carry derivation_name and derivation_version in the dataset. Each entry should include a plain‑language description, inputs, edge‑case handling, where the logic lives, and tests (including negative and regression tests); record failed tests and re‑tests.

• Make dictionary versions explicit and align them before pooling. Record the MedDRA/WHODrug version in relevant datasets. For cross‑study analyses, choose a target version, recode feeder studies as needed, quantify PT/SOC or ATC shifts, obtain medical review where appropriate, and document any justified exceptions.

• Publish clear release notes for every change. State what changed and why, old → new versions, quantified data deltas (rows/subjects affected, % change), validation summary, approvals, effective date, environment (test/UAT/prod), and a rollback plan. Keep notes concise and readable.

• Embed traceability in the data. Alongside derivation_name and derivation_version, include derivation_source (where the logic resides) and the applicable dictionary_version. Update a freeze manifest to reflect all locked logic and reference assets.

• Honor freeze windows near database lock. Avoid late changes; when unavoidable, perform and document impact assessments (including blinding risk), obtain the right sign‑offs, and communicate broadly.

• Plan pooling deliberately. For trials intended for pooling, set the dictionary version policy at study start; define a target dictionary version and acceptance criteria, maintain migration/mapping files, and verify before/after tallies so cross‑study comparability is defensible.

• Archive for auditability. Store prior logic, mappings, validation evidence, and release notes in a retrievable location to preserve provenance and enable reproducibility.

• Keep the Data Management Plan living. Budget time and resources for controlled updates, and ensure DM, Statistics, PV/Medical Safety, and QA roles are clearly engaged in change control.

• Deploy with discipline. Bump versions, update manifests, notify stakeholders, and ensure the rollback path is tested and documented.