derive_var_merged_summary {admiral}

R Documentation

Merge a Summary Variable

Description

Merge a summary variable from a dataset to the input dataset.

Note: This is a wrapper function for the more generic derive_vars_merged.

Usage

derive_var_merged_summary(
  dataset,
  dataset_add,
  by_vars,
  new_var,
  filter_add = NULL,
  analysis_var,
  summary_fun
)

Arguments

dataset	Input dataset The variables specified by the by_vars argument are expected.
dataset_add	Additional dataset The variables specified by the by_vars and the analysis_var arguments are expected.
by_vars	Grouping variables The values of analysis_var are summarized by the specified variables. The summarized values are merged to the input dataset (dataset) by the specified by variables. Permitted Values: list of variables created by exprs()
new_var	Variable to add The specified variable is added to the input dataset (dataset) and set to the summarized values.
filter_add	Filter for additional dataset (dataset_add) Only observations fulfilling the specified condition are taken into account for summarizing. If the argument is not specified, all observations are considered. Permitted Values: a condition
analysis_var	Analysis variable The values of the specified variable are summarized by the function specified for summary_fun.
summary_fun	Summary function The specified function that takes as input analysis_var and performs the calculation. This can include built-in functions as well as user defined functions, for example mean or function(x) mean(x, na.rm = TRUE).

Details

1. The records from the additional dataset (dataset_add) are restricted to those matching the filter_add condition.

2. The values of the analysis variable (analysis_var) are summarized by the summary function (summary_fun) for each by group (by_vars) in the additional dataset (dataset_add).

3. The summarized values are merged to the input dataset as a new variable (new_var). For observations without a matching observation in the additional dataset the new variable is set to NA. Observations in the additional dataset which have no matching observation in the input dataset are ignored.

Value

The output dataset contains all observations and variables of the input dataset and additionally the variable specified for new_var.

See Also

derive_summary_records(), get_summary_records()

General Derivation Functions for all ADaMs that returns variable appended to dataset: derive_var_extreme_flag(), derive_var_joined_exist_flag(), derive_var_merged_exist_flag(), 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(tibble)

# Add a variable for the mean of AVAL within each visit
adbds <- tribble(
  ~USUBJID,  ~AVISIT,  ~ASEQ, ~AVAL,
  "1",      "WEEK 1",      1,    10,
  "1",      "WEEK 1",      2,    NA,
  "1",      "WEEK 2",      3,    NA,
  "1",      "WEEK 3",      4,    42,
  "1",      "WEEK 4",      5,    12,
  "1",      "WEEK 4",      6,    12,
  "1",      "WEEK 4",      7,    15,
  "2",      "WEEK 1",      1,    21,
  "2",      "WEEK 4",      2,    22
)

derive_var_merged_summary(
  adbds,
  dataset_add = adbds,
  by_vars = exprs(USUBJID, AVISIT),
  new_var = MEANVIS,
  analysis_var = AVAL,
  summary_fun = function(x) mean(x, na.rm = TRUE)
)

# Add a variable listing the lesion ids at baseline
adsl <- tribble(
  ~USUBJID,
  "1",
  "2",
  "3"
)

adtr <- tribble(
  ~USUBJID,     ~AVISIT, ~LESIONID,
  "1",       "BASELINE",  "INV-T1",
  "1",       "BASELINE",  "INV-T2",
  "1",       "BASELINE",  "INV-T3",
  "1",       "BASELINE",  "INV-T4",
  "1",         "WEEK 1",  "INV-T1",
  "1",         "WEEK 1",  "INV-T2",
  "1",         "WEEK 1",  "INV-T4",
  "2",       "BASELINE",  "INV-T1",
  "2",       "BASELINE",  "INV-T2",
  "2",       "BASELINE",  "INV-T3",
  "2",         "WEEK 1",  "INV-T1",
  "2",         "WEEK 1",  "INV-N1"
)

derive_var_merged_summary(
  adsl,
  dataset_add = adtr,
  by_vars = exprs(USUBJID),
  filter_add = AVISIT == "BASELINE",
  new_var = LESIONSBL,
  analysis_var = LESIONID,
  summary_fun = function(x) paste(x, collapse = ", ")
)

---