Skip to content

OCCDS: ADAE

Adverse events, concomitant medications and medical history are occurrences: things that happen, any number of times, at any time. Their ADaM structure is OCCDS (the occurrence data structure): one row per event, with the treatment of the subject, analysis dates and flags.

Every safety table of a study reads ADAE, and almost every one counts only the treatment-emergent events: the events that started on or after the first dose. That flag is the heart of this chapter. It depends on the start date, and some start dates are not complete.

The programs read data/adsl.rds from chapter 9.

A partial date is a date with a missing part: 2013-03 has no day, 2003 has no month and no day. SDTM keeps such dates as text. ADaM needs a real date, so the program must impute the missing part: fill it in by a rule of the SAP.

Before you choose a rule, look at the dates.

programs/11_1_partial_dates.R
# Chapter 11: partial start dates in AE. Compare the part you know with the first dose
library(dplyr)
adsl <- readRDS("data/adsl.rds") |>
select(USUBJID, TRTSDT)
ae <- pharmaversesdtm::ae |>
select(USUBJID, AESEQ, AEDECOD, AESTDTC) |>
left_join(adsl, by = join_by(USUBJID), relationship = "many-to-one") |>
mutate(precision = case_when(
nchar(AESTDTC) == 10 ~ "day",
nchar(AESTDTC) == 7 ~ "month",
nchar(AESTDTC) == 4 ~ "year"
))
ae |>
count(precision)
#> # A tibble: 3 x 2
#> precision n
#> <chr> <int>
#> 1 day 1165
#> 2 month 15
#> 3 year 11
# the first dose, cut to the length of the partial date: 2013-03-18 -> 2013-03
ae |>
filter(precision != "day") |>
mutate(dose_known = substr(as.character(TRTSDT), 1, nchar(AESTDTC))) |>
count(precision, decided = case_when(
AESTDTC < dose_known ~ "before the first dose",
AESTDTC > dose_known ~ "after the first dose",
.default = "open: same month or year"
))
#> # A tibble: 3 x 3
#> precision decided n
#> <chr> <chr> <int>
#> 1 month after the first dose 6
#> 2 month before the first dose 9
#> 3 year before the first dose 11

1165 start dates are complete. 15 have a year and a month, and 11 have the year only. nchar() counts the characters of a text, so it tells the precision of an ISO 8601 date.

The second result uses the part of the date you know. substr() cuts the first dose to the same length as the partial date, so 2013-03-18 becomes 2013-03 for a date without a day. ISO 8601 text sorts like a date, so < and > compare the two texts. A start in an earlier year than the first dose cannot be after the dose, whatever the month and the day.

Every partial date is decided by what is known. 6 dates with a month start after the first dose. 9 dates with a month, and all 11 dates with the year only, start before it. No partial date is in the same month or year as the first dose. Such an “open” date would need a rule for the unknown part.

programs/11_2_adae_hand.R
# Chapter 11: ADAE by hand: analysis dates, treatment emergent, first occurrences
library(dplyr)
adsl <- readRDS("data/adsl.rds") |>
select(USUBJID, TRTSDT, TRTEDT, TRTA = TRT01A)
# Step 010: every AE with the treatment and the dates of the subject
adae_010 <- pharmaversesdtm::ae |>
select(
STUDYID, USUBJID, AESEQ, AETERM, AEDECOD, AEBODSYS, AESEV, AESER, AESTDTC,
AEENDTC
) |>
left_join(adsl, by = join_by(USUBJID), relationship = "many-to-one")
# Step 020: ASTDT. A missing day is the 1st, a missing month is January;
# ASTDTF says which. When the first dose has the same known part, the event
# may have started after it: then the start is the first dose
adae_020 <- adae_010 |>
mutate(
ASTDTF = case_when(nchar(AESTDTC) == 7 ~ "D", nchar(AESTDTC) == 4 ~ "M"),
ASTDT = lubridate::ymd(case_when(
nchar(AESTDTC) == 10 ~ AESTDTC,
nchar(AESTDTC) == 7 ~ paste0(AESTDTC, "-01"),
nchar(AESTDTC) == 4 ~ paste0(AESTDTC, "-01-01")
)),
ASTDT = if_else(
!is.na(ASTDTF) & startsWith(as.character(TRTSDT), AESTDTC),
pmax(ASTDT, TRTSDT),
ASTDT
)
)
# Step 021: AENDT. The end dates are complete or missing: no imputation
adae_021 <- adae_020 |>
mutate(AENDT = lubridate::ymd(AEENDTC))
# Step 030: ASTDY, the study day of the start. There is no day 0
adae_030 <- adae_021 |>
mutate(ASTDY = as.numeric(ASTDT - TRTSDT) + if_else(ASTDT >= TRTSDT, 1, 0))
# Step 040: treatment emergent: the event starts on or after the first dose
adae_040 <- adae_030 |>
mutate(TRTEMFL = if_else(ASTDT >= TRTSDT, "Y", NA))
# Step 050: first occurrence flags. The same code three times, so a function:
# "Y" on the first treatment-emergent event of each group (by ASTDT, AESEQ)
flag_first <- function(data, by) {
data |>
arrange(ASTDT, AESEQ) |>
mutate(
FIRST = if_else(TRTEMFL %in% "Y" & row_number() == 1, "Y", NA),
.by = all_of(c(by, "TRTEMFL"))
)
}
adae_hand <- adae_040 |>
flag_first("USUBJID") |>
rename(AOCCFL = FIRST) |>
flag_first(c("USUBJID", "AEBODSYS")) |>
rename(AOCCSFL = FIRST) |>
flag_first(c("USUBJID", "AEBODSYS", "AEDECOD")) |>
rename(AOCCPFL = FIRST) |>
arrange(USUBJID, AESEQ)
adae_hand |>
filter(USUBJID == "01-701-1015") |>
select(AESEQ, AEDECOD, ASTDT, ASTDY, TRTEMFL, AOCCFL, AOCCSFL, AOCCPFL)
#> # A tibble: 3 x 8
#> AESEQ AEDECOD ASTDT ASTDY TRTEMFL AOCCFL AOCCSFL AOCCPFL
#> <dbl> <chr> <date> <dbl> <chr> <chr> <chr> <chr>
#> 1 1 APPLICATION SITE ERYTHE~ 2014-01-03 2 Y Y Y Y
#> 2 2 APPLICATION SITE PRURIT~ 2014-01-03 2 Y <NA> <NA> Y
#> 3 3 DIARRHOEA 2014-01-09 8 Y <NA> Y Y
adae_hand |>
count(ASTDTF, TRTEMFL)
#> # A tibble: 5 x 3
#> ASTDTF TRTEMFL n
#> <chr> <chr> <int>
#> 1 D Y 6
#> 2 D <NA> 9
#> 3 M <NA> 11
#> 4 <NA> Y 1120
#> 5 <NA> <NA> 45
saveRDS(adae_hand, "data/adae_hand.rds")

The rule of this book for ASTDT, the analysis start date:

  • A missing day becomes the first day of the month. A missing month becomes January. The start is imputed early, because an early start can only lose the treatment-emergent flag if it is before the first dose, and the next rule prevents that.
  • When the known part of the date is the same as the first dose, the event may have started after the dose. Then the start is the first dose, not the 1st of the month. pmax() takes the later of two dates.
  • ASTDTF is the imputation flag: D when the day was imputed, M when the month (and the day) was imputed. It tells a reviewer that the date is not the collected date.

startsWith(as.character(TRTSDT), AESTDTC) asks “does the first dose start with the same text as the partial date?” That is the “open” case of section 11.1. In the pilot it never happens, but the rule must be there for the study where it does.

AENDT needs no imputation: every end date of the pilot is complete or missing.

Steps 030 and 040: study day and treatment emergent

Section titled “Steps 030 and 040: study day and treatment emergent”

ASTDY is the study day of the start, with no day 0, as in chapter 10. TRTEMFL = "Y" when the event starts on or after the first dose. Otherwise it is NA, not "N": in ADaM, a flag like TRTEMFL is "Y" or empty.

The count shows the result: 6 events with an imputed day are treatment emergent, and 9 are not. The 11 events with an imputed month all started before the first dose.

A table that counts subjects with an event needs one row per subject to count. A first occurrence flag marks it:

  • AOCCFL: the first treatment-emergent event of each subject.
  • AOCCSFL: the first per subject and system organ class (AEBODSYS).
  • AOCCPFL: the first per subject, system organ class and preferred term (AEDECOD).

The same code three times, with another group each time, so the program writes the function flag_first(). It sorts by start date and AESEQ, so “first” means the earliest start. In each group of by and TRTEMFL, the first row gets "Y" when it is treatment emergent. Then rename() gives the column its name.

Subject 01-701-1015 shows the three flags. APPLICATION SITE ERYTHEMA and APPLICATION SITE PRURITUS start on the same day, 2014-01-03. AESEQ breaks the tie, so ERYTHEMA is the first event of the subject (AOCCFL) and of its system organ class (AOCCSFL). PRURITUS is the first of its own preferred term (AOCCPFL). DIARRHOEA is in another system organ class, so it gets AOCCSFL.

programs/11_3_adae_admiral.R
# Chapter 11: the same ADAE with admiral
library(dplyr)
library(admiral)
adsl <- readRDS("data/adsl.rds")
adae <- pharmaversesdtm::ae |>
select(
STUDYID, USUBJID, AESEQ, AETERM, AEDECOD, AEBODSYS, AESEV, AESER, AESTDTC,
AEENDTC
) |>
derive_vars_merged(
dataset_add = adsl, by_vars = exprs(USUBJID),
new_vars = exprs(TRTSDT, TRTEDT, TRTA = TRT01A)
) |>
# impute a missing day or month to the first; never before the first dose
# when the first dose is in the known part (min_dates)
derive_vars_dt(
dtc = AESTDTC, new_vars_prefix = "AST", highest_imputation = "M",
date_imputation = "first", min_dates = exprs(TRTSDT)
) |>
derive_vars_dt(dtc = AEENDTC, new_vars_prefix = "AEN") |>
derive_vars_dy(reference_date = TRTSDT, source_vars = exprs(ASTDT)) |>
derive_var_trtemfl(
start_date = ASTDT, end_date = AENDT, trt_start_date = TRTSDT
) |>
restrict_derivation(
derivation = derive_var_extreme_flag,
args = params(
by_vars = exprs(USUBJID), order = exprs(ASTDT, AESEQ),
new_var = AOCCFL, mode = "first"
),
filter = TRTEMFL == "Y"
) |>
restrict_derivation(
derivation = derive_var_extreme_flag,
args = params(
by_vars = exprs(USUBJID, AEBODSYS), order = exprs(ASTDT, AESEQ),
new_var = AOCCSFL, mode = "first"
),
filter = TRTEMFL == "Y"
) |>
restrict_derivation(
derivation = derive_var_extreme_flag,
args = params(
by_vars = exprs(USUBJID, AEBODSYS, AEDECOD), order = exprs(ASTDT, AESEQ),
new_var = AOCCPFL, mode = "first"
),
filter = TRTEMFL == "Y"
) |>
arrange(USUBJID, AESEQ)
dim(adae)
#> [1] 1191 21
saveRDS(adae, "data/adae.rds")
Step By hand admiral
020 nchar(), paste0(), ymd(), pmax() derive_vars_dt(highest_imputation = "M", date_imputation = "first", min_dates = exprs(TRTSDT))
030 ASTDT - TRTSDT, plus 1 derive_vars_dy()
040 if_else(ASTDT >= TRTSDT, "Y", NA) derive_var_trtemfl()
050 flag_first() restrict_derivation(derive_var_extreme_flag, ..., filter = TRTEMFL == "Y")

The arguments of derive_vars_dt() are the rule of section 11.2, as parameters:

  • highest_imputation = "M": impute the day and the month, never the year. A date without a year stays missing.
  • date_imputation = "first": the first day, the first month.
  • min_dates = exprs(TRTSDT): when the first dose is a possible date of the partial date, the start is not before it. This is the floor of step 020.

derive_var_trtemfl() follows a set of rules from a PHUSE white paper. With only trt_start_date, an event that starts on or after the first dose is "Y". It has one rule that your program does not need here: an event with a missing start date is "Y" (the worst case), unless its end date is before the first dose. No ASTDT of the pilot is missing after the imputation, so the rule does not change a row.

The result has 1191 rows, one per AE. The program saves it as data/adae.rds.

programs/11_4_adae_compare.R
# Chapter 11: ADAE by hand against admiral, then against the reference ADAE
library(dplyr)
library(diffdf)
adae_hand <- readRDS("data/adae_hand.rds") |>
haven::zap_label()
adae <- readRDS("data/adae.rds") |>
haven::zap_label()
diffdf(adae_hand, adae, keys = c("USUBJID", "AESEQ"))
#> No issues were found!
vars <- c("USUBJID", "AESEQ", "ASTDT", "ASTDTF", "AENDT", "ASTDY", "TRTEMFL")
ref <- pharmaverseadam::adae |>
select(all_of(vars)) |>
haven::zap_label()
ours <- adae |>
select(all_of(vars))
diffdf(ours, ref, keys = c("USUBJID", "AESEQ"))
#> Warning message:
#> In diffdf(ours, ref, keys = c("USUBJID", "AESEQ")) :
#> Not all Values Compared Equal
#> Differences found between the objects!
#>
#> Summary of BASE and COMPARE
#> ==================================================================
#> PROPERTY BASE COMP
#> ------------------------------------------------------------------
#> Name ours ref
#> Class "tbl_df, tbl, data.frame" "tbl_df, tbl, data.frame"
#> Rows(#) 1191 1191
#> Columns(#) 7 7
#> ------------------------------------------------------------------
#>
#>
#> Not all Values Compared Equal
#> =============================
#> Variable No of Differences
#> -----------------------------
#> TRTEMFL 4
#> -----------------------------
#>
#>
#> =============================================
#> VARIABLE USUBJID AESEQ BASE COMPARE
#> ---------------------------------------------
#> TRTEMFL 01-705-1303 1 Y <NA>
#> TRTEMFL 01-705-1303 2 Y <NA>
#> TRTEMFL 01-705-1303 3 Y <NA>
#> TRTEMFL 01-705-1303 4 Y <NA>
#> ---------------------------------------------
#>
# The four events: the reference counts an event only up to 30 days after
# TRTEDT, and its TRTEDT ignores the open dose record (chapter 9)
adae |>
filter(USUBJID == "01-705-1303") |>
left_join(
pharmaverseadam::adae |> select(USUBJID, AESEQ, TRTEDT_REF = TRTEDT),
by = join_by(USUBJID, AESEQ)
) |>
select(AESEQ, ASTDT, TRTEDT, TRTEDT_REF, TRTEMFL)
#> # A tibble: 4 x 5
#> AESEQ ASTDT TRTEDT TRTEDT_REF TRTEMFL
#> <dbl> <date> <date> <date> <chr>
#> 1 1 2014-02-05 2014-06-02 2013-12-30 Y
#> 2 2 2014-02-05 2014-06-02 2013-12-30 Y
#> 3 3 2014-02-05 2014-06-02 2013-12-30 Y
#> 4 4 2014-02-05 2014-06-02 2013-12-30 Y

The ADAE by hand and the ADAE of admiral agree.

The reference ADAE agrees on the start dates, the imputation flags, the end dates and the study days. It differs on four events, all of subject 01-705-1303. Two rules come together here:

  1. The reference counts an event as treatment emergent only up to 30 days after the last dose (end_window = 30 in the admiral template).
  2. The reference TRTEDT of this subject is 2013-12-30. That is the subject with an open dose row of chapter 9: the rule of this book gives 2014-06-02.

The four events start on 2014-02-05, more than 30 days after 2013-12-30. So the reference does not count them. Exercise 11-3 shows that the 30-day window alone changes nothing in your ADAE: the difference comes from TRTEDT. A rule in ADSL changes a count in a safety table. That is why ADSL comes first, and why every ADSL rule must be written down.

11.5 Concomitant medications and medical history

Section titled “11.5 Concomitant medications and medical history”

ADCM and ADMH use the same structure and the same tools: analysis dates with imputation (derive_vars_dt() again), and first occurrence flags. ADCM also needs ONTRTFL, a flag for medications taken during treatment, between TRTSDT and TRTEDT; admiral has derive_var_ontrtfl() for it. The coded terms come from dictionaries: MedDRA codes adverse events, and WHO Drug codes medications. SDTM holds the coded terms. ADaM keeps them and does not code again.

  • OCCDS has one row per event. ADAE takes the treatment and the dates of the subject from ADSL.
  • Look at the partial dates before you choose a rule. Compare the part you know with the first dose.
  • Impute the start early, never before the first dose when the dose is in the known part, and flag the imputation (ASTDTF).
  • TRTEMFL = "Y" when the event starts on or after the first dose. A flag of this kind is "Y" or empty.
  • First occurrence flags give one row per subject (and per class or term) to count.
  • admiral: derive_vars_dt() with highest_imputation and min_dates, derive_var_trtemfl(), and derive_var_extreme_flag() inside restrict_derivation().
  • The four differences from the reference come from a rule in ADSL, not from ADAE.

Exercise 11-1. How many subjects have at least one treatment-emergent serious event (AESER == "Y")? Count them with n_distinct(). Then count the serious rows with AOCCFL == "Y". Why are the two numbers different?

Exercise 11-2. How many rows have AOCCSFL == "Y"? Check the number another way, with distinct().

Exercise 11-3. Add TRTEM30FL with the reference rule: derive_var_trtemfl() with trt_end_date = TRTEDT and end_window = 30. How many events change their flag in your ADAE?

Exercise 11-4. A subject has the first dose on 18 March 2013 and an AE that starts 2013-03. A second subject has the same first dose and an AE that starts 2013-02. Run derive_vars_dt() of program 11_3 on these two rows. What are ASTDT and TRTEMFL?

The answers are in Answers, Part II.

Found an error or have a question? Write to datastep.studio@gmail.com· Every program runs in DataStep Studio for R, the R extension for VS Code and Positron.

Data: the CDISC pilot study (cdiscpilot01), from the R packagespharmaversesdtm andpharmaverseadam (Apache License 2.0).

R is a project of the R Foundation. SAS and all other SAS Institute Inc. product or service names are registered trademarks or trademarks of SAS Institute Inc. This book is not affiliated with or endorsed by SAS Institute Inc. or the R Foundation. CDISC, SDTM and ADaM are trademarks of the Clinical Data Interchange Standards Consortium.

© 2026 DataStep Labs. All rights reserved.