derive_var_dthcaus {admiral}R Documentation

Derive Death Cause

Description

Derive death cause (DTHCAUS) and add traceability variables if required.

Usage

derive_var_dthcaus(
  dataset,
  ...,
  source_datasets,
  subject_keys = vars(STUDYID, USUBJID)
)

dthcaus_source(
  dataset_name,
  filter,
  date,
  order = NULL,
  mode = "first",
  dthcaus,
  traceability_vars = NULL
)

Arguments

dataset

Input dataset.

The variables specified by subject_keys are required.

...

Objects of class "dthcaus_source" created by dthcaus_source().

source_datasets

A named list containing datasets in which to search for the death cause

subject_keys

Variables to uniquely identify a subject

A list of quosures where the expressions are symbols as returned by vars() is expected.

dataset_name

The name of the dataset, i.e. a string, used to search for the death cause.

filter

An expression used for filtering dataset.

date

A date or datetime variable to be used for sorting dataset.

order

Sort order

Additional variables to be used for sorting the dataset which is ordered by the date and order. Can be used to avoid duplicate record warning.

Default: NULL

Permitted Values: list of variables or ⁠desc(<variable>)⁠ function calls created by vars(), e.g., vars(ADT, desc(AVAL)) or NULL

mode

One of "first" or "last". Either the "first" or "last" observation is preserved from the dataset which is ordered by date.

dthcaus

A variable name or a string literal — if a variable name, e.g., AEDECOD, it is the variable in the source dataset to be used to assign values to DTHCAUS; if a string literal, e.g. "Adverse Event", it is the fixed value to be assigned to DTHCAUS.

traceability_vars

A named list returned by vars() listing the traceability variables, e.g. vars(DTHDOM = "DS", DTHSEQ = DSSEQ). 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.

Details

This function derives DTHCAUS along with the user-defined traceability variables, if required. If a subject has death info from multiple sources, the one from the source with the earliest death date will be used. If dates are equivalent, the first source will be kept, so the user should provide the inputs in the preferred order.

Value

derive_var_dthcaus() returns the input dataset with DTHCAUS variable added.

dthcaus_source() returns an object of class "dthcaus_source".

Functions

Author(s)

Shimeng Huang, Samia Kabi, Thomas Neitmann, Tamara Senior

See Also

ADSL Functions that returns variable appended to dataset: derive_var_age_years(), derive_var_disposition_status(), derive_var_extreme_dtm(), derive_var_extreme_dt(), derive_vars_aage(), derive_vars_disposition_reason()

Source Specifications: assert_db_requirements(), assert_terms(), assert_valid_queries(), censor_source(), date_source(), death_event, event_source(), extend_source_datasets(), filter_date_sources(), format.sdg_select(), format.smq_select(), list_tte_source_objects(), params(), query(), sdg_select(), smq_select(), tte_source(), validate_query(), validate_sdg_select(), validate_smq_select()

Examples

library(tibble)
library(dplyr)
library(lubridate)

adsl <- tribble(
  ~STUDYID,  ~USUBJID,
  "STUDY01", "PAT01",
  "STUDY01", "PAT02",
  "STUDY01", "PAT03"
)
ae <- tribble(
  ~STUDYID,  ~USUBJID, ~AESEQ, ~AEDECOD,       ~AEOUT,  ~AEDTHDTC,
  "STUDY01", "PAT01",  12,     "SUDDEN DEATH", "FATAL", "2021-04-04"
) %>%
  mutate(
    AEDTHDT = ymd(AEDTHDTC)
  )
ds <- tribble(
  ~STUDYID, ~USUBJID, ~DSSEQ, ~DSDECOD, ~DSTERM, ~DSSTDTC,
  "STUDY01", "PAT02", 1, "INFORMED CONSENT OBTAINED", "INFORMED CONSENT OBTAINED", "2021-04-03",
  "STUDY01", "PAT02", 2, "RANDOMIZATION", "RANDOMIZATION", "2021-04-11",
  "STUDY01", "PAT02", 3, "DEATH", "DEATH DUE TO PROGRESSION OF DISEASE", "2022-02-01",
  "STUDY01", "PAT03", 1, "DEATH", "POST STUDY REPORTING OF DEATH", "2022-03-03"
) %>%
  mutate(
    DSSTDT = ymd(DSSTDTC)
  )

# Derive `DTHCAUS` only - for on-study deaths only
src_ae <- dthcaus_source(
  dataset_name = "ae",
  filter = AEOUT == "FATAL",
  date = AEDTHDT,
  mode = "first",
  dthcaus = AEDECOD
)

src_ds <- dthcaus_source(
  dataset_name = "ds",
  filter = DSDECOD == "DEATH" & grepl("DEATH DUE TO", DSTERM),
  date = DSSTDT,
  mode = "first",
  dthcaus = DSTERM
)

derive_var_dthcaus(adsl, src_ae, src_ds, source_datasets = list(ae = ae, ds = ds))

# Derive `DTHCAUS` and add traceability variables - for on-study deaths only
src_ae <- dthcaus_source(
  dataset_name = "ae",
  filter = AEOUT == "FATAL",
  date = AEDTHDT,
  mode = "first",
  dthcaus = AEDECOD,
  traceability_vars = vars(DTHDOM = "AE", DTHSEQ = AESEQ)
)

src_ds <- dthcaus_source(
  dataset_name = "ds",
  filter = DSDECOD == "DEATH" & grepl("DEATH DUE TO", DSTERM),
  date = DSSTDT,
  mode = "first",
  dthcaus = DSTERM,
  traceability_vars = vars(DTHDOM = "DS", DTHSEQ = DSSEQ)
)

derive_var_dthcaus(adsl, src_ae, src_ds, source_datasets = list(ae = ae, ds = ds))

# Derive `DTHCAUS` as above - now including post-study deaths with different `DTHCAUS` value
src_ae <- dthcaus_source(
  dataset_name = "ae",
  filter = AEOUT == "FATAL",
  date = AEDTHDT,
  mode = "first",
  dthcaus = AEDECOD,
  traceability_vars = vars(DTHDOM = "AE", DTHSEQ = AESEQ)
)

src_ds <- dthcaus_source(
  dataset_name = "ds",
  filter = DSDECOD == "DEATH" & grepl("DEATH DUE TO", DSTERM),
  date = DSSTDT,
  mode = "first",
  dthcaus = DSTERM,
  traceability_vars = vars(DTHDOM = "DS", DTHSEQ = DSSEQ)
)

src_ds_post <- dthcaus_source(
  dataset_name = "ds",
  filter = DSDECOD == "DEATH" & DSTERM == "POST STUDY REPORTING OF DEATH",
  date = DSSTDT,
  mode = "first",
  dthcaus = "POST STUDY: UNKNOWN CAUSE",
  traceability_vars = vars(DTHDOM = "DS", DTHSEQ = DSSEQ)
)

derive_var_dthcaus(adsl, src_ae, src_ds, src_ds_post, source_datasets = list(ae = ae, ds = ds))

[Package admiral version 0.8.4 Index]