admiral-adae

name	admiral-adae
description	Derives an ADaM Adverse Events Analysis Dataset (ADAE) using the {admiral} R package and pharmaverse ecosystem. Use when a user needs to create ADAE from SDTM AE and supporting domains, derive standard adverse event analysis variables (severity, seriousness, treatment-emergent flags, study day variables, baseline flags), or generate QC-ready R code following CDISC ADaM conventions. Requires SDTM input data, ADSL, and an ADaM spec.
license	MIT
metadata	{"author":"Navitas Data Sciences","version":"0.1","pharmaverse":"true"}
compatibility	Requires R with admiral, dplyr, lubridate, and pharmaversesdtm installed. Designed for use in a GxP-compliant environment with access to SDTM datasets, a completed ADSL dataset, and an ADaM ADAE specification.

admiral-adae

Derives a CDISC-conformant ADAE dataset using {admiral}. Outputs executable, QC-ready R code with derivation logic traceable to the ADaM specification.

The primary design challenge in ADAE is the treatment-emergent adverse event (TEAE) flag (TRTEMFL) and its supporting date infrastructure. All date and study day derivations must flow from this before any analysis variables are added.

---

Inputs

Before generating code, confirm the following are available or explicitly noted as absent:

Input	Required	Notes
AE	Yes	One record per AE per subject; subject spine for ADAE
ADSL	Yes	Provides TRTSDT, TRTEDT, TRT01P/A, population flags
MH	No	Medical history; needed for pre-existing condition flag (PREFL)
CM	No	Concomitant medications; sometimes linked to AE causality
ADaM ADAE spec	Yes	Variable list, derivation rules, TEAE definition, grading rules
Study context	Yes	TEAE window definition, SMQ/grouping flag scope, severity scale

If AE or ADSL are absent, stop and request them. If optional domains are absent, omit the corresponding derivations and note this in code comments.

Note on pharmaversesdtm test data: The pharmaversesdtm::ae dataset does not contain AETOXGR. Users running this skill against pharmaverse test data should skip the AETOXGR derivation in Step 7. The derivation is retained in the skill for use with real study data where NCI CTCAE grading was collected.

Critical ADSL dependency: ADAE must merge a defined set of ADSL variables onto every AE record. Confirm with the statistician which ADSL variables are required — at minimum: TRTSDT, TRTEDT, TRTSDTM, TRT01P, TRT01PN, TRT01A, TRT01AN, and all population flags in scope (SAFFL, ITTFL).

---

Workflow

Follow these steps in order. Generate code section by section, not as a single block.

Step 1 — Setup and domain loading

library(admiral)
library(dplyr)
library(lubridate)
library(pharmaversesdtm)

# Load SDTM domains
ae   <- pharmaversesdtm::ae
adsl <- adsl  # assumed derived upstream; replace with path/load as needed
# mh <- pharmaversesdtm::mh  # uncomment if pre-existing condition flag in scope

# Remove DOMAIN from AE to avoid variable conflicts in merges
ae <- ae |> select(-DOMAIN)

# Confirm AE has at least one record
stopifnot(nrow(ae) > 0)

Step 2 — Subject spine from AE

ADAE is a one-record-per-AE dataset; the subject spine is AE itself. Start here and add ADSL variables in the next step.

adae <- ae

Step 3 — Merge ADSL variables

Merge a controlled subset of ADSL variables onto every AE record. Do not merge all of ADSL — select only variables referenced in the ADAE derivation logic and required for the output dataset per the ADaM spec.

# REVIEW: Confirm which ADSL variables are required per the ADAE spec.
#   The list below covers the minimum set for TEAE flag derivation and treatment
#   labelling. Extend with population flags and other ADSL variables as needed.
adsl_vars <- exprs(
  STUDYID, USUBJID,
  TRTSDT, TRTEDT, TRTSDTM,
  TRT01P, TRT01PN, TRT01A, TRT01AN,
  SAFFL, ITTFL
)

adae <- adae |>
  derive_vars_merged(
    dataset_add = adsl |> select(!!!adsl_vars),
    by_vars     = exprs(STUDYID, USUBJID)
  )

Step 4 — AE date variables (ASTDT, ASTDTF, AENDT, AENDTF)

Derive analysis start and end dates from AE.AESTDTC and AE.AEENDTC. Always use derive_vars_dt() — never as.Date() directly on DTC variables.

Use date_imputation = "first" for start dates and "last" for end dates per CDISC convention. Always retain imputation flag variables (ASTDTF, AENDTF).

adae <- adae |>
  derive_vars_dt(
    dtc             = AESTDTC,
    new_vars_prefix = "AST",
    date_imputation = "first",
    flag_imputation = "auto"
  ) |>
  derive_vars_dt(
    dtc             = AEENDTC,
    new_vars_prefix = "AEN",
    date_imputation = "last",
    flag_imputation = "auto"
  )

Step 5 — Study day variables (ASTDY, AENDY)

Use derive_vars_dy() relative to TRTSDT from ADSL. Do not compute study days manually with date subtraction — this bypasses the Day 1 = first dose date offset logic required by ADaM.

adae <- adae |>
  derive_vars_dy(
    reference_date = TRTSDT,
    source_vars    = exprs(ASTDT, AENDT)
  )

Step 6 — Treatment-emergent flag (TRTEMFL)

This is the central derivation in ADAE. TRTEMFL = "Y" when:

• AE onset date (ASTDT) >= first dose date (TRTSDT), and
• AE onset date (ASTDT) <= last dose date (TRTEDT) + study-specific window

The derive_var_trtemfl() function handles this logic. The end_window parameter defines how many days post-last-dose an AE is still considered treatment-emergent — this is study- and protocol-specific.

# REVIEW: end_window is protocol-specific. Common values are 30 days post-last
#   dose for SAEs and 7 days for non-serious AEs, but always confirm from the
#   SAP. If the protocol does not specify a post-treatment window, set end_window
#   to 0 to include only AEs on or before the last dose date.
#   The ignore_time_for_trt_end argument should be TRUE if TRTEDTM is not
#   reliable for all subjects — confirm with the data manager.
adae <- adae |>
  derive_var_trtemfl(
    new_var                    = TRTEMFL,
    start_date                 = ASTDT,
    end_date                   = AENDT,
    trt_start_date             = TRTSDT,
    trt_end_date               = TRTEDT,
    end_window                 = 30,        # PLACEHOLDER — confirm from SAP
    ignore_time_for_trt_end    = TRUE
  )

Step 7 — Severity and grade variables (AESEV, AETOXGR)

Map AESEV from AE.AESEV (already decoded in SDTM) and AETOXGR from AE.AETOXGR if NCI CTCAE grading is used. If only AESEV is in scope, skip AETOXGR.

adae <- adae |>
  mutate(
    # AESEV: severity — use decoded AESEV directly from AE; no transformation required
    AESEV = AESEV,
    # AESEVN: optional numeric mapping for sorting
    # REVIEW: Confirm severity ordering and numeric mapping against the ADaM spec.
    AESEVN = case_when(
      AESEV == "MILD"     ~ 1L,
      AESEV == "MODERATE" ~ 2L,
      AESEV == "SEVERE"   ~ 3L
    )
  )

# AETOXGR: CTCAE numeric grade — carry through from AE if grading was collected
# Uncomment if in scope per ADaM spec:
# adae <- adae |>
#   mutate(AETOXGR = AETOXGR)

Step 8 — Seriousness and outcome variables (AESER, AEOUT, AESDTH)

These variables typically carry through from AE SDTM with controlled terminology alignment. If the ADaM spec requires recoding, apply case_when() with explicit # REVIEW: annotations.

adae <- adae |>
  mutate(
    # AESER: serious AE flag — "Y" or NA only; never "N" per CDISC convention
    AESER = if_else(AESER == "Y", "Y", NA_character_),
    # AESDTH: AE resulted in death — "Y" or NA
    AESDTH = if_else(AESDTH == "Y", "Y", NA_character_),
    # AEOUT: outcome — verify CDISC CT values in spec
    # REVIEW: Confirm AEOUT coded values align with the CDISC AE outcome codelist
    #   (RECOVER, NOT RECOVERED/NOT RESOLVED, RECOVERING/RESOLVING, etc.)
    AEOUT = AEOUT
  )

Step 9 — Causality and action taken (AEREL, AEACN)

Carry through from AE, applying if_else() for flag recoding to "Y"/NA convention where applicable.

adae <- adae |>
  mutate(
    # AEREL: relationship to study treatment — usually "RELATED" / "NOT RELATED"
    # REVIEW: Some studies use "POSSIBLE", "PROBABLE" — confirm CT per spec.
    AEREL = AEREL,
    # AERELN: numeric causality code for sorting/analysis if required by spec
    AERELN = case_when(
      AEREL == "NOT RELATED" ~ 1L,
      AEREL == "RELATED"     ~ 2L
    ),
    # AERELNST: causality to non-study treatment if applicable
    # Uncomment if in scope: AERELNST = AERELNST
    #
    # AEACN: action taken with study treatment
    AEACN = AEACN
  )

Step 10 — Pre-existing condition flag (PREFL)

PREFL = "Y" when the AE term (AEDECOD) is present in MH prior to treatment start. Requires MH domain. If MH is absent, comment out this section.

# PREFL: pre-existing condition flag from MH
# REVIEW: The matching logic below uses AEDECOD = MHDECOD. Confirm the
#   match strategy with the medical reviewer — some specs require AEBODSYS
#   matching or a more specific term hierarchy.
# Requires: mh <- pharmaversesdtm::mh |> select(-DOMAIN)
#
# mh_terms <- mh |>
#   filter(MHSTAT != "HISTORY OF") |>   # REVIEW: filter condition is study-specific
#   distinct(STUDYID, USUBJID, MHDECOD)
#
# adae <- adae |>
#   derive_var_merged_exist_flag(
#     dataset_add   = mh_terms,
#     by_vars       = exprs(STUDYID, USUBJID, AEDECOD = MHDECOD),
#     new_var       = PREFL,
#     condition     = TRUE,
#     true_value    = "Y",
#     false_value   = NA_character_,
#     missing_value = NA_character_
#   )

Step 11 — Maximum severity flag (AESEQ, grouping flags)

If the spec requires a worst-case severity flag per subject (AMAXSEVFL) or cumulative AE counts, derive using derive_var_extreme_flag().

# AMAXSEVFL: flag for the most severe AE per subject within TRTEMFL == "Y"
# REVIEW: Confirm whether worst-severity flag applies to TEAE only or all AEs.
adae <- adae |>
  restrict_derivation(
    derivation = derive_var_extreme_flag,
    args = params(
      by_vars   = exprs(STUDYID, USUBJID),
      order     = exprs(desc(AESEVN), ASTDT, AESEQ),
      new_var   = AMAXSEVFL,
      mode      = "first"
    ),
    filter = TRTEMFL == "Y"
  )

Step 12 — SMQ and grouping flags (optional)

If the spec includes standardised MedDRA queries (SMQs) or custom AE grouping flags, derive using derive_vars_query() with a query dataset constructed from the specification.

# SMQ / grouping flags via derive_vars_query()
# REVIEW: SMQ membership lists are sponsor-defined; confirm the query dataset
#   structure and variable names against the ADaM ADAE spec and MedDRA version.
# Requires: queries_smq — a data frame in admiral query format
#   (see admiral::queries_mednav for structure reference)
#
# adae <- adae |>
#   derive_vars_query(
#     dataset_queries = queries_smq
#   )

Step 13 — Sequence number (AESEQ)

Assign a within-subject sequence number. AE.AESEQ from SDTM is typically carried through to ADaM — do not re-derive unless the spec explicitly requires a different ordering.

# REVIEW: If AESEQ from AE SDTM is the correct sequence variable per spec,
#   carry it through directly. If the spec requires a re-derived sequence,
#   use derive_var_obs_number() instead.
# adae <- adae |>
#   derive_var_obs_number(
#     new_var  = AESEQ,
#     by_vars  = exprs(STUDYID, USUBJID),
#     order    = exprs(ASTDT, AETERM),
#     check_type = "warning"
#   )

Step 14 — Dataset attributes and final checks

# Required variable check
required_vars <- c(
  "STUDYID", "USUBJID",
  "AETERM", "AEDECOD", "AEBODSYS",
  "ASTDT", "ASTDTF", "AENDT", "AENDTF",
  "ASTDY", "AENDY",
  "AESEV", "AESER",
  "TRTEMFL",
  "TRT01P", "TRT01A"
)
missing_vars <- setdiff(required_vars, names(adae))
if (length(missing_vars) > 0) {
  stop("Missing required ADAE variables: ", paste(missing_vars, collapse = ", "))
}

# Record count sanity check — ADAE should have at least as many records as AE
stopifnot(nrow(adae) >= nrow(ae))

# Apply variable labels — use xportr for submission context
# adae <- adae |>
#   xportr_label(metacore_obj, domain = "ADAE") |>
#   xportr_type(metacore_obj, domain = "ADAE") |>
#   xportr_length(metacore_obj, domain = "ADAE") |>
#   xportr_order(metacore_obj, domain = "ADAE")
# xportr_write(adae, "adae.xpt", label = "Adverse Events Analysis Dataset")

---

Code quality requirements

Generated code must meet these standards for QC-readiness:

• Comments: Each derivation block must have a comment referencing the source variable (e.g. # ASTDT: AE onset analysis date from AE.AESTDTC)
• Human review flags: Use # REVIEW: comments where protocol-specific decisions are required (TEAE window, causality coding, SMQ membership, PREFL matching logic, severity ordering)
• No silent failures: Use stopifnot() for critical assertions (AE not empty, required variables present, row count preserved after merge)
• Pipe style: Use the native pipe |> and exprs() for admiral verb arguments
• No manual date arithmetic: Always use admiral date derivation functions

---

Common errors to avoid

• Merging all ADSL variables onto ADAE — select only the variables needed; full ADSL merge inflates the dataset and introduces variable naming conflicts
• Using as.Date() on AESTDTC or AEENDTC — always use derive_vars_dt() to handle partial dates with proper imputation
• Setting flag_imputation = "auto" without including ASTDTF and AENDTF in the output — imputation flags must appear in the dataset per ADaM specification
• Hardcoding end_window in derive_var_trtemfl() without a # REVIEW: annotation — this is always protocol-specific and must come from the SAP
• Using AESER == "N" comparisons — SDTM AE.AESER is "Y" or "" (blank), not "Y" or "N"; align to ADaM convention of "Y" or NA in output
• Computing study days manually (e.g. ASTDT - TRTSDT + 1) — use derive_vars_dy() to ensure correct ADaM study day offset logic
• Passing AE.AESEV directly as a numeric severity without a lookup — AESEV is character; derive AESEVN separately with an explicit case_when() lookup
• Using "N" for any flag variable (TRTEMFL, AESER, AESDTH, PREFL) — CDISC convention is "Y" or NA, never "N"
• Deriving TRTEMFL without confirming end_window against the SAP — an incorrect window silently miscategorises AEs with major safety implications
• Not removing DOMAIN from AE before derive_vars_merged() calls — causes variable conflict errors

---

Output checklist

Before returning code, verify:

• AE row count confirmed non-zero with stopifnot() at load
• DOMAIN removed from AE before processing
• ADSL variables merged selectively — not select(everything())
• ASTDT and AENDT derived via derive_vars_dt() with imputation arguments explicit
• ASTDTF and AENDTF present in output
• ASTDY and AENDY derived via derive_vars_dy() not manual arithmetic
• TRTEMFL derived via derive_var_trtemfl() with end_window annotated with # REVIEW:
• AESER and AESDTH recoded to "Y" / NA convention
• All # REVIEW: comments placed at protocol-specific decision points
• Required variables presence check with stop() on failure
• xportr block present (commented) for submission context