Introduction
This article describes creating an OCCDS ADaM. Examples are currently presented and tested in the context of ADAE. However, the examples could be applied to other OCCDS ADaMs such as ADCM, ADMH, ADDV, etc.
Note: All examples assume CDISC SDTM and/or ADaM format as input unless otherwise specified.
Programming Workflow
- Read in Data
- Derive/Impute End and Start Analysis Date/time and Relative Day
- Derive Durations
- Derive ATC variables
- Derive Planned and Actual Treatment
- Derive Date/Date-time of Last Dose
- Derive Severity, Causality, and Toxicity Grade
- Derive Treatment Emergent Flag
- Derive Occurrence Flags
- Derive Query Variables
- Add ADSL variables
- Derive Analysis Sequence Number
- Add Labels and Attributes
Read in Data
To start, all data frames needed for the creation of ADAE should be read into the environment. This will be a company specific process. Some of the data frames needed may be AE and ADSL
For example purpose, the CDISC Pilot SDTM and ADaM datasets —which are included in {admiral.test}— are used.
library(admiral)
library(dplyr, warn.conflicts = FALSE)
library(admiral.test)
library(lubridate)
data("admiral_ae")
data("admiral_adsl")
ae <- admiral_ae
adsl <- admiral_adslAt this step, it may be useful to join ADSL to your AE domain as well. Only the ADSL variables used for derivations are selected at this step. The rest of the relevant ADSL variables would be added later.
adsl_vars <- vars(TRTSDT, TRTEDT, TRT01A, TRT01P, DTHDT, EOSDT)
adae <- derive_vars_merged(
ae,
dataset_add = adsl,
new_vars = adsl_vars,
by = vars(STUDYID, USUBJID)
)Derive/Impute End and Start Analysis Date/time and Relative Day
This part derives ASTDTM, ASTDT, ASTDY, AENDTM, AENDT, and AENDY. The function derive_vars_dtm() can be used to derive ASTDTM and AENDTM where ASTDTM could be company-specific. ASTDT and AENDT can be derived from ASTDTM and AENDTM, respectively, using function derive_vars_dtm_to_dt(). derive_vars_dy() can be used to create ASTDY and AENDY.
adae <- adae %>%
derive_vars_dtm(
dtc = AESTDTC,
new_vars_prefix = "AST",
highest_imputation = "M",
min_dates = vars(TRTSDT)
) %>%
derive_vars_dtm(
dtc = AEENDTC,
new_vars_prefix = "AEN",
highest_imputation = "M",
date_imputation = "last",
time_imputation = "last",
max_dates = vars(DTHDT, EOSDT)
) %>%
derive_vars_dtm_to_dt(vars(ASTDTM, AENDTM)) %>%
derive_vars_dy(
reference_date = TRTSDT,
source_vars = vars(ASTDT, AENDT)
)See also Date and Time Imputation.
Derive Durations
The function derive_vars_duration() can be used to create the variables ADURN and ADURU.
adae <- adae %>%
derive_vars_duration(
new_var = ADURN,
new_var_unit = ADURU,
start_date = ASTDT,
end_date = AENDT
)Derive ATC variables
The function derive_vars_atc() can be used to derive ATC Class Variables.
It helps to add Anatomical Therapeutic Chemical class variables from FACM to ADCM.
The expected result is the input dataset with ATC variables added.
cm <- tibble::tribble(
~USUBJID, ~CMGRPID, ~CMREFID, ~CMDECOD,
"BP40257-1001", "14", "1192056", "PARACETAMOL",
"BP40257-1001", "18", "2007001", "SOLUMEDROL",
"BP40257-1002", "19", "2791596", "SPIRONOLACTONE"
)
facm <- tibble::tribble(
~USUBJID, ~FAGRPID, ~FAREFID, ~FATESTCD, ~FASTRESC,
"BP40257-1001", "1", "1192056", "CMATC1CD", "N",
"BP40257-1001", "1", "1192056", "CMATC2CD", "N02",
"BP40257-1001", "1", "1192056", "CMATC3CD", "N02B",
"BP40257-1001", "1", "1192056", "CMATC4CD", "N02BE",
"BP40257-1001", "1", "2007001", "CMATC1CD", "D",
"BP40257-1001", "1", "2007001", "CMATC2CD", "D10",
"BP40257-1001", "1", "2007001", "CMATC3CD", "D10A",
"BP40257-1001", "1", "2007001", "CMATC4CD", "D10AA",
"BP40257-1001", "2", "2007001", "CMATC1CD", "D",
"BP40257-1001", "2", "2007001", "CMATC2CD", "D07",
"BP40257-1001", "2", "2007001", "CMATC3CD", "D07A",
"BP40257-1001", "2", "2007001", "CMATC4CD", "D07AA",
"BP40257-1001", "3", "2007001", "CMATC1CD", "H",
"BP40257-1001", "3", "2007001", "CMATC2CD", "H02",
"BP40257-1001", "3", "2007001", "CMATC3CD", "H02A",
"BP40257-1001", "3", "2007001", "CMATC4CD", "H02AB",
"BP40257-1002", "1", "2791596", "CMATC1CD", "C",
"BP40257-1002", "1", "2791596", "CMATC2CD", "C03",
"BP40257-1002", "1", "2791596", "CMATC3CD", "C03D",
"BP40257-1002", "1", "2791596", "CMATC4CD", "C03DA"
)
derive_vars_atc(cm, facm)
#> # A tibble: 5 x 8
#> USUBJID CMGRPID CMREFID CMDECOD ATC1CD ATC2CD ATC3CD ATC4CD
#> <chr> <chr> <chr> <chr> <chr> <chr> <chr> <chr>
#> 1 BP40257-1001 14 1192056 PARACETAMOL N N02 N02B N02BE
#> 2 BP40257-1001 18 2007001 SOLUMEDROL D D10 D10A D10AA
#> 3 BP40257-1001 18 2007001 SOLUMEDROL D D07 D07A D07AA
#> 4 BP40257-1001 18 2007001 SOLUMEDROL H H02 H02A H02AB
#> 5 BP40257-1002 19 2791596 SPIRONOLACTONE C C03 C03D C03DADerive Planned and Actual Treatment
TRTA and TRTP must match at least one value of the character treatment variables in ADSL (e.g., TRTxxA/TRTxxP, TRTSEQA/TRTSEQP, TRxxAGy/TRxxPGy).
An example of a simple implementation for a study without periods could be:
adae <- mutate(adae, TRTP = TRT01P, TRTA = TRT01A)
count(adae, TRTP, TRTA, TRT01P, TRT01A)
#> # A tibble: 2 x 5
#> TRTP TRTA TRT01P TRT01A n
#> <chr> <chr> <chr> <chr> <int>
#> 1 Placebo Placebo Placebo Placebo 10
#> 2 Xanomeline Low Do… Xanomeline Low D… Xanomeline Low D… Xanomeline Low D… 6For studies with periods see the “Visit and Period Variables” vignette.
Derive Date/Date-time of Last Dose
The function derive_var_last_dose_date() can be used to derive the last dose date before the start of the event.
Additionally, this function can also provide traceability variables (e.g. LDOSEDOM, LDOSESEQ) using the traceability_vars argument.
data(ex_single)
ex_single <- derive_vars_dtm(
ex_single,
dtc = EXSTDTC,
new_vars_prefix = "EXST",
flag_imputation = "none"
)
adae <- adae %>%
derive_var_last_dose_date(
ex_single,
filter_ex = (EXDOSE > 0 | (EXDOSE == 0 & grepl("PLACEBO", EXTRT))) &
!is.na(EXSTDTM),
dose_date = EXSTDTM,
analysis_date = ASTDT,
single_dose_condition = (EXSTDTC == EXENDTC),
new_var = LDOSEDTM,
output_datetime = TRUE
)Derive Severity, Causality, and Toxicity Grade
The variables ASEV, AREL, and ATOXGR can be added using simple dplyr::mutate() assignments, if no imputation is required.
Derive Treatment Emergent Flag
To derive the treatment emergent flag TRTEMFL, one can call derive_var_trtemfl(). In the example below, we use 30 days in the flag derivation.
adae <- adae %>%
derive_var_trtemfl(
trt_start_date = TRTSDT,
trt_end_date = TRTEDT,
end_window = 30
)To derive on-treatment flag (ONTRTFL) in an ADaM dataset with a single occurrence date, we use derive_var_ontrtfl().
The expected result is the input dataset with an additional column named ONTRTFL with a value of "Y" or NA.
If you want to also check an end date, you could add the end_date argument. Note that in this scenario you could set span_period = "Y" if you want occurrences that started prior to drug intake, and was ongoing or ended after this time to be considered as on-treatment.
bds1 <- tibble::tribble(
~USUBJID, ~ADT, ~TRTSDT, ~TRTEDT,
"P01", ymd("2020-02-24"), ymd("2020-01-01"), ymd("2020-03-01"),
"P02", ymd("2020-01-01"), ymd("2020-01-01"), ymd("2020-03-01"),
"P03", ymd("2019-12-31"), ymd("2020-01-01"), ymd("2020-03-01")
)
derive_var_ontrtfl(
bds1,
start_date = ADT,
ref_start_date = TRTSDT,
ref_end_date = TRTEDT
)
#> # A tibble: 3 x 5
#> USUBJID ADT TRTSDT TRTEDT ONTRTFL
#> <chr> <date> <date> <date> <chr>
#> 1 P01 2020-02-24 2020-01-01 2020-03-01 Y
#> 2 P02 2020-01-01 2020-01-01 2020-03-01 Y
#> 3 P03 2019-12-31 2020-01-01 2020-03-01 NA
bds2 <- tibble::tribble(
~USUBJID, ~ADT, ~TRTSDT, ~TRTEDT,
"P01", ymd("2020-07-01"), ymd("2020-01-01"), ymd("2020-03-01"),
"P02", ymd("2020-04-30"), ymd("2020-01-01"), ymd("2020-03-01"),
"P03", ymd("2020-03-15"), ymd("2020-01-01"), ymd("2020-03-01")
)
derive_var_ontrtfl(
bds2,
start_date = ADT,
ref_start_date = TRTSDT,
ref_end_date = TRTEDT,
ref_end_window = 60
)
#> # A tibble: 3 x 5
#> USUBJID ADT TRTSDT TRTEDT ONTRTFL
#> <chr> <date> <date> <date> <chr>
#> 1 P01 2020-07-01 2020-01-01 2020-03-01 NA
#> 2 P02 2020-04-30 2020-01-01 2020-03-01 Y
#> 3 P03 2020-03-15 2020-01-01 2020-03-01 Y
bds3 <- tibble::tribble(
~ADTM, ~TRTSDTM, ~TRTEDTM, ~TPT,
"2020-01-02T12:00", "2020-01-01T12:00", "2020-03-01T12:00", NA,
"2020-01-01T12:00", "2020-01-01T12:00", "2020-03-01T12:00", "PRE",
"2019-12-31T12:00", "2020-01-01T12:00", "2020-03-01T12:00", NA
) %>%
mutate(
ADTM = ymd_hm(ADTM),
TRTSDTM = ymd_hm(TRTSDTM),
TRTEDTM = ymd_hm(TRTEDTM)
)
derive_var_ontrtfl(
bds3,
start_date = ADTM,
ref_start_date = TRTSDTM,
ref_end_date = TRTEDTM,
filter_pre_timepoint = TPT == "PRE"
)
#> # A tibble: 3 x 5
#> ADTM TRTSDTM TRTEDTM TPT ONTRTFL
#> <dttm> <dttm> <dttm> <chr> <chr>
#> 1 2020-01-02 12:00:00 2020-01-01 12:00:00 2020-03-01 12:00:00 NA Y
#> 2 2020-01-01 12:00:00 2020-01-01 12:00:00 2020-03-01 12:00:00 PRE NA
#> 3 2019-12-31 12:00:00 2020-01-01 12:00:00 2020-03-01 12:00:00 NA NADerive Occurrence Flags
The function derive_var_extreme_flag() can help derive variables such as AOCCIFL, AOCCPIFL, AOCCSIFL, AOCXIFL, AOCXPIFL, and AOCXSIFL.
If grades were collected, the following can be used to flag first occurrence of maximum toxicity grade.
adae <- adae %>%
restrict_derivation(
derivation = derive_var_extreme_flag,
args = params(
by_vars = vars(USUBJID),
order = vars(desc(ATOXGR), ASTDTM, AESEQ),
new_var = AOCCIFL,
mode = "first"
),
filter = TRTEMFL == "Y"
)Similarly, ASEV can also be used to derive the occurrence flags, if severity is collected. In this case, the variable will need to be recoded to a numeric variable. Flag first occurrence of most severe adverse event:
adae <- adae %>%
mutate(
ASEVN = as.integer(factor(ASEV, levels = c("MILD", "MODERATE", "SEVERE", "DEATH THREATENING")))
) %>%
restrict_derivation(
derivation = derive_var_extreme_flag,
args = params(
by_vars = vars(USUBJID),
order = vars(desc(ASEVN), ASTDTM, AESEQ),
new_var = AOCCIFL,
mode = "first"
),
filter = TRTEMFL == "Y"
)Derive Query Variables
For deriving query variables SMQzzNAM, SMQzzCD, SMQzzSC, SMQzzSCN, or CQzzNAM the derive_vars_query() function can be used. As input it expects a queries dataset, which provides the definition of the queries. See Queries dataset documentation for a detailed description of the queries dataset. The create_query_data() function can be used to create queries datasets.
The following example shows how to derive query variables for Standardized MedDRA Queries (SMQs) in ADAE.
data("queries")
adae1 <- tibble::tribble(
~USUBJID, ~ASTDTM, ~AETERM, ~AESEQ, ~AEDECOD, ~AELLT, ~AELLTCD,
"01", "2020-06-02 23:59:59", "ALANINE AMINOTRANSFERASE ABNORMAL",
3, "Alanine aminotransferase abnormal", NA_character_, NA_integer_,
"02", "2020-06-05 23:59:59", "BASEDOW'S DISEASE",
5, "Basedow's disease", NA_character_, 1L,
"03", "2020-06-07 23:59:59", "SOME TERM",
2, "Some query", "Some term", NA_integer_,
"05", "2020-06-09 23:59:59", "ALVEOLAR PROTEINOSIS",
7, "Alveolar proteinosis", NA_character_, NA_integer_
)
adae_query <- derive_vars_query(dataset = adae1, dataset_queries = queries)Similarly to SMQ, the derive_vars_query() function can be used to derive Standardized Drug Groupings (SDG).
sdg <- tibble::tribble(
~VAR_PREFIX, ~QUERY_NAME, ~SDG_ID, ~QUERY_SCOPE, ~QUERY_SCOPE_NUM, ~TERM_LEVEL, ~TERM_NAME, ~TERM_ID,
"SDG01", "Diuretics", 11, "BROAD", 1, "CMDECOD", "Diuretic 1", NA,
"SDG01", "Diuretics", 11, "BROAD", 2, "CMDECOD", "Diuretic 2", NA,
"SDG02", "Costicosteroids", 12, "BROAD", 1, "CMDECOD", "Costicosteroid 1", NA,
"SDG02", "Costicosteroids", 12, "BROAD", 2, "CMDECOD", "Costicosteroid 2", NA,
"SDG02", "Costicosteroids", 12, "BROAD", 2, "CMDECOD", "Costicosteroid 3", NA,
)
adcm <- tibble::tribble(
~USUBJID, ~ASTDTM, ~CMDECOD,
"01", "2020-06-02 23:59:59", "Diuretic 1",
"02", "2020-06-05 23:59:59", "Diuretic 1",
"03", "2020-06-07 23:59:59", "Costicosteroid 2",
"05", "2020-06-09 23:59:59", "Diuretic 2"
)
adcm_query <- derive_vars_query(adcm, sdg)Add the ADSL variables
If needed, the other ADSL variables can now be added:
adae <- adae %>%
derive_vars_merged(
dataset_add = select(adsl, !!!negate_vars(adsl_vars)),
by_vars = vars(STUDYID, USUBJID)
)Derive Analysis Sequence Number
The function derive_var_obs_number() can be used for deriving ASEQ variable to ensure the uniqueness of subject records within the dataset.
For example, there can be multiple records present in ADCM for a single subject with the same ASTDTM and CMSEQ variables. But these records still differ at ATC level:
adcm <- tibble::tribble(
~USUBJID, ~ASTDTM, ~CMSEQ, ~CMDECOD, ~ATC1CD, ~ATC2CD, ~ATC3CD, ~ATC4CD,
"BP40257-1001", "2013-07-05 UTC", "14", "PARACETAMOL", "N", "N02", "N02B", "N02BE",
"BP40257-1001", "2013-08-15 UTC", "18", "SOLUMEDROL", "D", "D10", "D10A", "D10AA",
"BP40257-1001", "2013-08-15 UTC", "18", "SOLUMEDROL", "D", "D07", "D07A", "D07AA",
"BP40257-1001", "2013-08-15 UTC", "18", "SOLUMEDROL", "H", "H02", "H02A", "H02AB",
"BP40257-1002", "2012-12-15 UTC", "19", "SPIRONOLACTONE", "C", "C03", "C03D", "C03DA"
)
adcm_aseq <- adcm %>%
derive_var_obs_number(
by_vars = vars(USUBJID),
order = vars(ASTDTM, CMSEQ, ATC1CD, ATC2CD, ATC3CD, ATC4CD),
new_var = ASEQ,
check_type = "error"
)Add Labels and Attributes
Adding labels and attributes for SAS transport files is supported by the following packages:
metacore: establish a common foundation for the use of metadata within an R session.
metatools: enable the use of metacore objects. Metatools can be used to build datasets or enhance columns in existing datasets as well as checking datasets against the metadata.
xportr: functionality to associate all metadata information to a local R data frame, perform data set level validation checks and convert into a transport v5 file(xpt).
NOTE: All these packages are in the experimental phase, but the vision is to have them associated with an End to End pipeline under the umbrella of the pharmaverse. An example of applying metadata and perform associated checks can be found at the pharmaverse E2E example.