Reject Dose Expansion

Review ask

As a clinical trial statistician or programmer, challenge anything in this benchmark: describe a problem in Comments, or propose a fix with the Edit button on any source file.

Task: Is this a specification error a study team could realistically make, and should the build stop on it rather than continue?
Inputs: Do they trigger the failure for the reason the summary gives?
Expected failure: Is this the right error, raised at the right point, and would it tell the programmer what to fix?

The other tabs beside Comments are background for assessment, not under review.

Summary

EditUnder reviewWhat this benchmark means

README.md

Goal: build an administration record for each administration in a collected exposure (EX) record, carrying the collected record's sequence number and EXTRT, EXDOSE, EXDOSU, ASTDT, AENDT, and NDOSE through and numbering each administration in ADOSEN.

Input: collected exposure records with treatment, dose, unit, start and end dates, and a count of administrations: EXTRT, EXDOSE, EXDOSU, EXSTDTC, EXENDTC, and EXDOSCNT.

Variables:

EXDOSE is the amount given at each administration.
ASTDT is the first day the collected record covers, taken from EXSTDTC.
AENDT is the last day the collected record covers, taken from EXENDTC.
ADOSEN numbers the administrations built from one collected record, from 1 up to its count (EXDOSCNT). Only three administrations are written out in advance, so a record standing for more loses the ones past the third, and a record with a missing or zero count builds none.
NDOSE is how many administrations the collected record stands for, taken from EXDOSCNT. A record whose NDOSE is larger than the highest ADOSEN built from it rejects the run, so no artifact is accepted. The expected output records the completed dataset presented to that failing check.

Note: administrations built from one collected record share that record's treatment, dose, unit, and dates; only ADOSEN differs between them.

How to fix

The per-administration rows belong in the input data. Expand the aggregate record into one collected record for each administration upstream, and read those records here one to one. For expected-but-uncollected rows, use the long-form planning input in adam-advs-carryforward and enrich it from collected data.

If the analysis genuinely needs only the totals, drop the administration level and key on the collected record instead:

keys: [STUDYID, USUBJID, EXSEQ]

Do not keep the administration level and widen the written-out administrations to whatever the current extract needs. It answers correctly only for data that has already been seen, and the next extract with a longer record loses administrations again without warning.

Expected failure

Editthe run is rejected; no artifact is accepted

expected/error.yaml

phase: verification
condition: assert_failed
requirement: REQ-0384

expected/error.yaml

phase: verification
condition: assert_failed
spec_paths:
  - verifications[1].assert
requirement: REQ-0384
context:
  verification_id: a-record-is-expanded-into-every-administration-it-holds
  failure_count: 3
  keys:
    - STUDYID: YAMAA-01
      USUBJID: YAMAA-01-102
      EXSEQ: 1
      ADOSEN: 1
    - STUDYID: YAMAA-01
      USUBJID: YAMAA-01-102
      EXSEQ: 1
      ADOSEN: 2
    - STUDYID: YAMAA-01
      USUBJID: YAMAA-01-102
      EXSEQ: 1
      ADOSEN: 3

YAML specification

1 spec file

spec.yaml

Edit106 lines

1schema_version: "1.0"2domain: ADEX3keys: [STUDYID, USUBJID, EXSEQ, ADOSEN]4input:5  EX:6    path: input/ex.csv7    types:8      EXSEQ: int9      EXDOSE: float10      EXDOSCNT: int11      EXSTDTC: date12      EXENDTC: date1314output:15  path: adex.csv16  columns: [STUDYID, USUBJID, EXSEQ, EXTRT, EXDOSE, EXDOSU, ASTDT, AENDT,17            ADOSEN, NDOSE]1819columns:20  - name: STUDYID21    type: str22    label: Study Identifier23    derivation: EX.STUDYID2425  - name: USUBJID26    type: str27    label: Unique Subject Identifier28    derivation: EX.USUBJID2930  - name: EXSEQ31    type: int32    label: Sequence Number33    derivation: EX.EXSEQ3435  - name: EXTRT36    type: str37    label: Name of Treatment38    derivation: EX.EXTRT3940  - name: EXDOSE41    type: float42    label: Dose43    derivation: EX.EXDOSE4445  - name: EXDOSU46    type: str47    label: Dose Units48    derivation: EX.EXDOSU4950  - name: ASTDT51    type: date52    label: Analysis Start Date53    derivation: EX.EXSTDTC5455  - name: AENDT56    type: date57    label: Analysis End Date58    derivation: EX.EXENDTC5960  # Set by each row template below.61  - name: ADOSEN62    type: int63    label: Administration Sequence Number6465  - name: NDOSE66    type: int67    label: Number of Administrations68    derivation: EX.EXDOSCNT6970  # Internal: the highest administration number built from each collected71  # record, compared against NDOSE by the assert below.72  - name: NDOSMAX73    type: int74    label: Maximum Administration Sequence Number75    derivation:76      aggregate:77        group_by: [STUDYID, USUBJID, EXSEQ]78        expr: "MAX(ADOSEN)"7980# One row per administration, written out in advance for only three: a81# record counting more loses the rest, and a record with a missing or zero82# count builds no row.83rows:84  - id: dose_185    filter: "EX.EXDOSCNT >= 1"86    derivations:87      ADOSEN: {literal: 1}8889  - id: dose_290    filter: "EX.EXDOSCNT >= 2"91    derivations:92      ADOSEN: {literal: 2}9394  - id: dose_395    filter: "EX.EXDOSCNT >= 3"96    derivations:97      ADOSEN: {literal: 3}9899verifications:100  - unique:101      columns: [STUDYID, USUBJID, EXSEQ, ADOSEN]102  # Fails on every row of a record counting more administrations than103  # were built.104  - assert:105      id: a-record-is-expanded-into-every-administration-it-holds106      require: "NDOSMAX = NDOSE"

Inputs

Under review1 source file

input/ex.csv

Edit6 rows

input/ex.csv
STUDYID	EXSEQ	EXTRT	EXDOSE	EXDOSU	EXDOSFRQ	EXSTDTC	EXENDTC	EXDOSCNT
YAMAA-01	1	Study Drug	10	mg	QD	2025-04-01	2025-04-01	1
YAMAA-01	2	Study Drug	10	mg	QD	2025-04-08	2025-04-09	2
YAMAA-01	1	Study Drug	20	mg	QD	2025-04-02	2025-04-06	5
YAMAA-01	1	Study Drug	20	mg	QD	2025-04-10	2025-04-12	3
YAMAA-01	1	Study Drug	10	mg	QD	2025-04-15	2025-04-15	0
YAMAA-01	1	Study Drug	10	mg	QD	2025-04-16	2025-04-16	—

Unexpected Output

Under review9 rows presented to the failing check - not an accepted artifact

expected/adex.csv

Edit9 rows

expected/adex.csv
STUDYID	EXSEQ	EXTRT	EXDOSE	EXDOSU	ASTDT	AENDT	ADOSEN	NDOSE
YAMAA-01	1	Study Drug	10	mg	2025-04-01	2025-04-01	1	1
YAMAA-01	2	Study Drug	10	mg	2025-04-08	2025-04-09	1	2
YAMAA-01	1	Study Drug	20	mg	2025-04-02	2025-04-06	1	5
YAMAA-01	1	Study Drug	20	mg	2025-04-10	2025-04-12	1	3
YAMAA-01	2	Study Drug	10	mg	2025-04-08	2025-04-09	2	2
YAMAA-01	1	Study Drug	20	mg	2025-04-02	2025-04-06	2	5
YAMAA-01	1	Study Drug	20	mg	2025-04-10	2025-04-12	2	3
YAMAA-01	1	Study Drug	20	mg	2025-04-02	2025-04-06	3	5
YAMAA-01	1	Study Drug	20	mg	2025-04-10	2025-04-12	3	3

Shaded columns are derived— = missing value

Comments and assessment materials

Dataset Name	Variable Name	Variable Label	Type	Codelist/Controlled Terms	Computational Method	Origin
ADEX	STUDYID	Study Identifier	character		Copy value from EX.STUDYID.	Predecessor
ADEX	USUBJID	Unique Subject Identifier	character		Copy value from EX.USUBJID.	Predecessor
ADEX	EXSEQ	Sequence Number	numeric		Copy value from EX.EXSEQ.	Predecessor
ADEX	EXTRT	Name of Treatment	character		Copy value from EX.EXTRT.	Predecessor
ADEX	EXDOSE	Dose	numeric		Copy value from EX.EXDOSE.	Predecessor
ADEX	EXDOSU	Dose Units	character		Copy value from EX.EXDOSU.	Predecessor
ADEX	ASTDT	Analysis Start Date	numeric	ISO 8601	Copy value from EX.EXSTDTC.	Predecessor
ADEX	AENDT	Analysis End Date	numeric	ISO 8601	Copy value from EX.EXENDTC.	Predecessor
ADEX	ADOSEN	Administration Sequence Number	numeric		Set per constructed row; see the Row construction sheet.	Derived
ADEX	NDOSE	Number of Administrations	numeric		Copy value from EX.EXDOSCNT.	Predecessor

Template	Include when	ADOSEN
dose_1	EX.EXDOSCNT >= 1	Constant "1"
dose_2	EX.EXDOSCNT >= 2	Constant "2"
dose_3	EX.EXDOSCNT >= 3	Constant "3"

Version	Date	Author	Description
1.3	2026-09-29	yamaa docs build	Show study codelist names, external dictionaries, and ISO 8601 formats in variable rows; list the document's codelist values and metadata
1.2	2026-09-29	yamaa docs build	Classify ADaM copies from a declared input as Predecessor and recodes as Derived, and SDTM recodes of locally derived columns as Derived
1.1	2026-09-29	yamaa docs build	Resolve lookups into the donor record they select, and give every derivation shape a plain-language rule instead of its raw YAML
1.0		yamaa docs build	Initial generation from spec.yaml

How to fix

input/ex.csv

expected/adex.csv

Comments

Mapping spec