Assign ETCD to exposure records from the trial design

Exposure (EX) does not carry ETCD — SDTMIG puts the element code in SE, not in EX — so every study writes a bespoke DATA step to decide which trial element each dosing record belongs to. Where Trial Arms (TA) determines the answer, derive_etcd() reads it off the design instead of asking the caller to supply it.

derive_etcd(exposure, dm, ta)

Arguments

exposure

Exposure records with USUBJID and a --STDTC date variable, typically EX. An existing ETCD column is overwritten.

dm

Demographics (DM), supplying USUBJID and the arm code.

ta

Trial Arms (TA), with ARMCD, ETCD, EPOCH and TAETORD.

Value

exposure as a tibble with an ETCD column added, rows and order unchanged.

How the element is chosen

The subject's arm (ACTARMCD if dm has it, else ARMCD) selects that arm's rows in ta. The candidate elements are the ones whose EPOCH is "TREATMENT" (matched case-insensitively — SDTMIG 3.1.2-era studies write "Treatment"), ordered by TAETORD. Then, per subject:

  • One candidate element. Every exposure record for that subject belongs to it. There is nothing to decide.

  • k candidate elements and n <= k exposure records. The records, in start-date order, take the first n elements in TAETORD order. This is the only assignment consistent with both orderings, so the design does determine it.

  • k > 1 candidate elements and n > k records. Ambiguous — several records would have to share an element and the design does not say which. derive_etcd() aborts and names the subjects.

A subject whose arm has no "TREATMENT" element in ta (a screen failure arm, typically) also aborts, because a dosing record for such a subject contradicts the design rather than being placed by it.

When you should not use it

The rule above uses only ordering. A design whose treatment elements are distinguished by something else — dose level, a titration rule, a branch on response — is not resolved by ordering alone, and you should attach ETCD yourself from whatever variable actually carries the distinction. The CDISCPILOT01 high-dose arm happens to be titrated in visit order, so ordering reproduces it; that is a property of that trial, not a general law.

SAS idiom replaced. The per-study PROC SQL join of EX to TA plus the BY USUBJID DATA step with RETAIN/counter logic that walks a subject's dosing records onto the arm's elements.

See also

derive_se(), which calls this automatically when exposure has no ETCD column.

Examples

ex <- derive_etcd(
  exposure = sdtmgap_example("lzzt_ex"),
  dm       = sdtmgap_example("lzzt_dm"),
  ta       = sdtmgap_example("lzzt_ta")
)
table(ex$ETCD)
#> 
#> HIE HIM HIS  LO PBO 
#>  28  72  72 193 226