Skip to contents

Derive Last Dose

Source: R/derive_vars_last_dose.R
derive_vars_last_dose.Rd

Add EX source variables from last dose to the input dataset.

Usage

derive_vars_last_dose(
  dataset,
  dataset_ex,
  filter_ex = NULL,
  by_vars = exprs(STUDYID, USUBJID),
  dose_id = exprs(),
  dose_date,
  analysis_date,
  single_dose_condition = EXDOSFRQ == "ONCE",
  new_vars = NULL,
  traceability_vars = NULL
)

Arguments

dataset

Input dataset. The variables specified by the by_vars and analysis_date parameters are expected.

dataset_ex

Input EX dataset. The variables specified by the by_vars, dose_date, new_vars parameters, and source variables from traceability_vars parameter are expected.

filter_ex

Filtering condition applied to EX dataset. For example, it can be used to filter for valid dose. Defaults to NULL.

by_vars

Variables to join by (created by rlang::exprs).

dose_id

Variables to identify unique dose (created by rlang::exprs). Defaults to empty exprs().

dose_date

The EX dose date variable. A date or date-time object is expected.

analysis_date

The analysis date variable. A date or date-time object is expected.

single_dose_condition

The condition for checking if dataset_ex is single dose. An error is issued if the condition is not true. Defaults to (EXDOSFRQ == "ONCE").

new_vars

Variables to keep from dataset_ex, with the option to rename. Can either be variables created by rlang::exprs (e.g. exprs(VISIT)), or named list returned by exprs() (e.g. exprs(LSTEXVIS = VISIT)). If set to NULL, then all variables from dataset_ex are kept without renaming. Defaults to NULL.

traceability_vars

A named list returned by exprs() listing the traceability variables, e.g. exprs(LDOSEDOM = "EX", LDOSESEQ = EXSEQ). The left-hand side (names of the list elements) gives the names of the traceability variables in the returned dataset. The right-hand side (values of the list elements) gives the values of the traceability variables in the returned dataset. These can be either strings or symbols referring to existing variables.

Value

Input dataset with EX source variables from last dose added.

Details

When doing date comparison to identify last dose, date-time imputations are done as follows:

  • dose_date: time is imputed to 00:00:00 if the variable is a date variable

  • analysis_date: time is imputed to 23:59:59 if the variable is a date variable

The last dose records are identified as follows:

  1. The dataset_ex is filtered using filter_ex, if provided. This is useful for, for example, filtering for valid dose only.

  2. The datasets dataset and dataset_ex are joined using by_vars.

  3. The last dose is identified: the last dose is the EX record with maximum date where dose_date is lower to or equal to analysis_date, subject to both date values are non-NA. The last dose is identified per by_vars. If multiple EX records exist for the same dose_date, then either dose_id needs to be supplied (e.g. dose_id = exprs(EXSEQ)) to identify unique records, or an error is issued. When dose_id is supplied, the last EX record from the same dose_date sorted by dose_id will be used to identify last dose.

  4. The EX source variables (as specified in new_vars) from last dose are appended to the dataset and returned to the user.

This function only works correctly for EX dataset with a structure of single dose per row. If your study EX dataset has multiple doses per row, use create_single_dose_dataset() to transform the EX dataset into single dose per row structure before calling derive_vars_last_dose().

If variables (other than those specified in by_vars) exist in both dataset and dataset_ex, then join cannot be performed properly and an error is issued. To resolve the error, use new_vars to either keep variables unique to dataset_ex, or use this option to rename variables from dataset_ex (e.g. new_vars = exprs(LSTEXVIS = VISIT)).

See also

derive_var_last_dose_amt(), derive_var_last_dose_date(), derive_var_last_dose_grp(), create_single_dose_dataset()

General Derivation Functions for all ADaMs that returns variable appended to dataset: derive_var_extreme_flag(), derive_var_joined_exist_flag(), derive_var_last_dose_amt(), derive_var_last_dose_date(), derive_var_last_dose_grp(), derive_var_merged_cat(), derive_var_merged_character(), derive_var_merged_exist_flag(), derive_var_merged_summary(), derive_var_obs_number(), derive_var_relative_flag(), derive_vars_joined(), derive_vars_merged_lookup(), derive_vars_merged(), derive_vars_transposed(), get_summary_records()

Examples

library(dplyr, warn.conflicts = FALSE)
library(admiral.test)
data(admiral_ae)
data(ex_single)

# create datetime variables in input datasets
ex_single <- derive_vars_dtm(
  head(ex_single, 100),
  dtc = EXENDTC,
  new_vars_prefix = "EXEN",
  flag_imputation = "none"
)

adae <- admiral_ae %>%
  head(100) %>%
  derive_vars_dtm(
    dtc = AESTDTC,
    new_vars_prefix = "AST",
    highest_imputation = "M"
  )

# add last dose vars
adae %>%
  derive_vars_last_dose(
    dataset_ex = ex_single,
    filter_ex = (EXDOSE > 0 | (EXDOSE == 0 & grepl("PLACEBO", EXTRT))) &
      !is.na(EXENDTM),
    new_vars = exprs(EXDOSE, EXTRT, EXSEQ, EXENDTC, VISIT),
    dose_date = EXENDTM,
    analysis_date = ASTDTM
  ) %>%
  select(STUDYID, USUBJID, AESEQ, AESTDTC, EXDOSE, EXTRT, EXENDTC, EXSEQ, VISIT)
#> # A tibble: 100 x 9
#>    STUDYID     USUBJID    AESEQ AESTDTC    EXDOSE EXTRT  EXENDTC   EXSEQ VISIT  
#>    <chr>       <chr>      <dbl> <chr>       <dbl> <chr>  <chr>     <int> <chr>  
#>  1 CDISCPILOT… 01-701-10…     1 2014-01-03     NA NA     NA           NA NA     
#>  2 CDISCPILOT… 01-701-10…     2 2014-01-03     NA NA     NA           NA NA     
#>  3 CDISCPILOT… 01-701-10…     3 2014-01-09     NA NA     NA           NA NA     
#>  4 CDISCPILOT… 01-701-10…     3 2012-08-26      0 PLACE… 2012-08-…     7 BASELI…
#>  5 CDISCPILOT… 01-701-10…     1 2012-08-07      0 PLACE… 2012-08-…     3 BASELI…
#>  6 CDISCPILOT… 01-701-10…     2 2012-08-07      0 PLACE… 2012-08-…     3 BASELI…
#>  7 CDISCPILOT… 01-701-10…     4 2012-08-07      0 PLACE… 2012-08-…     3 BASELI…
#>  8 CDISCPILOT… 01-701-10…     1 2013-07-21     NA NA     NA           NA NA     
#>  9 CDISCPILOT… 01-701-10…     2 2013-08-08     NA NA     NA           NA NA     
#> 10 CDISCPILOT… 01-701-10…     1 2014-08-27     NA NA     NA           NA NA     
#> # … with 90 more rows

# or with traceability variables
adae %>%
  derive_vars_last_dose(
    dataset_ex = ex_single,
    filter_ex = (EXDOSE > 0 | (EXDOSE == 0 & grepl("PLACEBO", EXTRT))) &
      !is.na(EXENDTM),
    new_vars = exprs(EXDOSE, EXTRT, EXSEQ, EXENDTC, VISIT),
    dose_date = EXENDTM,
    analysis_date = ASTDTM,
    traceability_vars = exprs(LDOSEDOM = "EX", LDOSESEQ = EXSEQ, LDOSEVAR = "EXENDTC")
  ) %>%
  select(STUDYID, USUBJID, AESEQ, AESTDTC, EXDOSE, EXTRT, EXENDTC, LDOSEDOM, LDOSESEQ, LDOSEVAR)
#> # A tibble: 100 x 10
#>    STUDYID USUBJID AESEQ AESTDTC EXDOSE EXTRT EXENDTC LDOSEDOM LDOSESEQ LDOSEVAR
#>    <chr>   <chr>   <dbl> <chr>    <dbl> <chr> <chr>   <chr>       <int> <chr>   
#>  1 CDISCP… 01-701…     1 2014-0…     NA NA    NA      NA             NA NA      
#>  2 CDISCP… 01-701…     2 2014-0…     NA NA    NA      NA             NA NA      
#>  3 CDISCP… 01-701…     3 2014-0…     NA NA    NA      NA             NA NA      
#>  4 CDISCP… 01-701…     3 2012-0…      0 PLAC… 2012-0… EX              7 EXENDTC 
#>  5 CDISCP… 01-701…     1 2012-0…      0 PLAC… 2012-0… EX              3 EXENDTC 
#>  6 CDISCP… 01-701…     2 2012-0…      0 PLAC… 2012-0… EX              3 EXENDTC 
#>  7 CDISCP… 01-701…     4 2012-0…      0 PLAC… 2012-0… EX              3 EXENDTC 
#>  8 CDISCP… 01-701…     1 2013-0…     NA NA    NA      NA             NA NA      
#>  9 CDISCP… 01-701…     2 2013-0…     NA NA    NA      NA             NA NA      
#> 10 CDISCP… 01-701…     1 2014-0…     NA NA    NA      NA             NA NA      
#> # … with 90 more rows