diff --git a/.Rprofile b/.Rprofile index d059c2fcc5..6d46e67550 100644 --- a/.Rprofile +++ b/.Rprofile @@ -1,8 +1,7 @@ # Set renv profile base on R version. .get_dependencies <- function(project_dir) { - admdev_loc <- find.package("admiraldev", lib.loc = .libPaths(), quiet = TRUE) - adm_dev_suggests <- if(length(admdev_loc) != 0) { + adm_dev_suggests <- if (length(admdev_loc) != 0) { renv:::renv_dependencies_discover_description(admdev_loc, fields = c("Depends", "Imports", "LinkingTo", "Suggests")) } else { data.frame(Packages = character(0)) @@ -19,7 +18,7 @@ )) ) ) - packages[!(packages %in% c("admiral", "admiraldev", "admiralci", "admiral.test", "pharmaversesdtm", getwd()))] + packages[!(packages %in% c("admiral", "admiraldev", "admiralci", "pharmaversesdtm", getwd()))] } options(renv.snapshot.filter = .get_dependencies) diff --git a/.devcontainer/4.1/devcontainer.json b/.devcontainer/4.1/devcontainer.json index 1d05f7fdf1..ab6ddfeeae 100644 --- a/.devcontainer/4.1/devcontainer.json +++ b/.devcontainer/4.1/devcontainer.json @@ -31,7 +31,7 @@ "postCreateCommand": "bash ./.devcontainer/postCreateCommand.sh", - "postAttachCommand": "$BROWSER \"https://${CODESPACE_NAME}-8787.${GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN}/\"", + "postAttachCommand": "$BROWSER \"https://${CODESPACE_NAME}-8787.${GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN}/\"; echo 'To open rstudio in your browser, just type rstudio in the terminal'", "customizations": { "vscode": { diff --git a/.devcontainer/4.2/devcontainer.json b/.devcontainer/4.2/devcontainer.json index f30486e0d8..decbcca545 100644 --- a/.devcontainer/4.2/devcontainer.json +++ b/.devcontainer/4.2/devcontainer.json @@ -31,7 +31,7 @@ "postCreateCommand": "bash ./.devcontainer/postCreateCommand.sh", - "postAttachCommand": "$BROWSER \"https://${CODESPACE_NAME}-8787.${GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN}/\"", + "postAttachCommand": "$BROWSER \"https://${CODESPACE_NAME}-8787.${GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN}/\"; echo 'To open rstudio in your browser, just type rstudio in the terminal'", "customizations": { "vscode": { diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json index 4f49db8fe5..3f47589f32 100644 --- a/.devcontainer/devcontainer.json +++ b/.devcontainer/devcontainer.json @@ -31,7 +31,7 @@ "postCreateCommand": "bash ./.devcontainer/postCreateCommand.sh", - "postAttachCommand": "$BROWSER \"https://${CODESPACE_NAME}-8787.${GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN}/\"", + "postAttachCommand": "$BROWSER \"https://${CODESPACE_NAME}-8787.${GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN}/\"; echo 'To open rstudio in your browser, just type rstudio in the terminal'", "customizations": { "vscode": { diff --git a/.devcontainer/postCreateCommand.sh b/.devcontainer/postCreateCommand.sh index 9b9db23af9..8dfe4e236e 100644 --- a/.devcontainer/postCreateCommand.sh +++ b/.devcontainer/postCreateCommand.sh @@ -1,5 +1,11 @@ #!/bin/bash +# move script rstudio into /usr/bin +sudo cp "$(pwd)/.devcontainer/rstudio.sh" /usr/bin/rstudio +sudo chmod +x /usr/bin/rstudio + +# Restore renv and install staged dependencies R -q -e 'renv::restore(lockfile = file.path("renv", "profiles", paste(R.version$major, substr(R.version$minor, 1, 1), sep = "."), "renv.lock")); staged.dependencies::install_deps(staged.dependencies::dependency_table(project = ".", verbose = 1), verbose = 1);' +# Define rstudio default working directory jq --arg folder "$(pwd)/" '. + { "initial_working_directory": $folder }' .devcontainer/rstudio-prefs.json > ~/.config/rstudio/rstudio-prefs.json diff --git a/.devcontainer/rstudio.sh b/.devcontainer/rstudio.sh new file mode 100644 index 0000000000..053a247b5b --- /dev/null +++ b/.devcontainer/rstudio.sh @@ -0,0 +1,5 @@ +#!/bin/bash + +$BROWSER "https://${CODESPACE_NAME}-8787.${GITHUB_CODESPACES_PORT_FORWARDING_DOMAIN}" + +exit 1 diff --git a/.github/workflows/common.yml b/.github/workflows/common.yml index dc1fa875a9..01a35f6c13 100644 --- a/.github/workflows/common.yml +++ b/.github/workflows/common.yml @@ -15,17 +15,13 @@ on: - "v*" branches: - main - - devel - patch - - pre-release # 'pull_request' events are triggered when PRs are # created against one of these target branches. pull_request: branches: - main - - devel - patch - - pre-release # 'release' events are triggered when... # you guessed it - when releases are made. release: @@ -81,7 +77,7 @@ jobs: latest-tag-alt-name: cran-release multiversion-docs-landing-page: cran-release branches-or-tags-to-list: >- - ^cran-release$|^main$|^v([0-9]+\\.)?([0-9]+\\.)?([0-9]+)$ + ^cran-release$|^v([0-9]+\\.)?([0-9]+\\.)?([0-9]+)$ linter: name: Lint uses: pharmaverse/admiralci/.github/workflows/lintr.yml@main diff --git a/DESCRIPTION b/DESCRIPTION index 9de4163d70..02f6075009 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -1,7 +1,7 @@ Package: admiral Type: Package Title: ADaM in R Asset Library -Version: 0.12.2.9000 +Version: 0.12.2.9001 Authors@R: c( person("Ben", "Straub", email = "ben.x.straub@gsk.com", role = c("aut", "cre")), person("Stefan", "Bundfuss", role = "aut"), diff --git a/NEWS.md b/NEWS.md index 949a521d97..a8d686cdc6 100644 --- a/NEWS.md +++ b/NEWS.md @@ -6,8 +6,19 @@ - `derive_var_extreme_flag()` and `derive_vars_merged()` were enhanced with the arguments `true_value` and `false_value` to align with preexisting functions that had similar functionality (#2125) +- `derive_summary_records()`, `derive_var_merged_summary()`, and `get_summary_records()` +were enhanced such that more than one summary variable can be derived, e.g., +`AVAL` as the sum and `ADT` as the maximum of the contributing records. (#1792) + ## Breaking Changes +- In `derive_summary_records()` and `get_summary_records()` the arguments +`analysis_var` and `summary_fun` were deprecated in favor of `set_values_to`. +(#1792) + +- In `derive_var_merged_summary()` the arguments `new_var`, `analysis_var`, and +`summary_fun` were deprecated in favor of `new_vars`. (#1792) + - admiral now only supports R >= 4.0.0 - For the function `derive_vars_merged()`, the argument `match_flag` was renamed to `exist_flag` (#2125) @@ -34,6 +45,8 @@ ## Documentation +- A way to standardize roxygen labels and descriptions for function arguments was implemented and tested (#2034) + ## Various # admiral 0.12.2 diff --git a/R/call_derivation.R b/R/call_derivation.R index 6afa0c5b80..38ad64629c 100644 --- a/R/call_derivation.R +++ b/R/call_derivation.R @@ -3,7 +3,7 @@ #' Call a single derivation multiple times with some parameters/arguments being fixed across #' iterations and others varying. #' -#' @param dataset The input dataset +#' @param dataset `r roxygen_param_dataset()` #' @param derivation The derivation function to call #' #' A function that performs a specific derivation is expected. A derivation diff --git a/R/create_single_dose_dataset.R b/R/create_single_dose_dataset.R index 1a0c782b24..936593cea0 100644 --- a/R/create_single_dose_dataset.R +++ b/R/create_single_dose_dataset.R @@ -185,10 +185,8 @@ dose_freq_lookup <- tribble( #' necessary when e.g. calculating last dose before an adverse event in `ADAE` #' or deriving a total dose parameter in `ADEX` when `EXDOSFRQ != ONCE`. #' -#' @param dataset Input dataset -#' -#' The columns specified by `dose_freq`, `start_date` and the `end_date` -#' parameters are expected. +#' @param dataset +#' `r roxygen_param_dataset(expected_vars = c("dose_freq", "start_date", "end_date"))` #' #' @param dose_freq The dose frequency #' diff --git a/R/derive_adeg_params.R b/R/derive_adeg_params.R index 05ae271421..5c8afc3a80 100644 --- a/R/derive_adeg_params.R +++ b/R/derive_adeg_params.R @@ -6,10 +6,9 @@ #' #' **Note:** This is a wrapper function for the more generic `derive_param_computed()`. #' -#' @param dataset Input dataset -#' -#' The variables specified by the `by_vars` and the `unit_var` parameter, -#' `PARAMCD`, and `AVAL` are expected. +#' @param dataset +#' `r roxygen_param_dataset(expected_vars = c("by_vars", "get_unit_expr"))` +#' `PARAMCD`, and `AVAL` are expected as well. #' #' The variable specified by `by_vars` and `PARAMCD` must be a unique key of #' the input dataset after restricting it by the filter condition (`filter` @@ -257,10 +256,9 @@ compute_qtc <- function(qt, rr, method) { #' The analysis value of the new parameter is derived as #' \deqn{\frac{60000}{HR}}{60000 / HR} #' -#' @param dataset Input dataset -#' -#' The variables specified by the `by_vars` parameter, `PARAMCD`, and `AVAL` -#' are expected. +#' @param dataset +#' `r roxygen_param_dataset(expected_vars = c("by_vars"))` +#' `PARAMCD`, and `AVAL` are expected as well. #' #' The variable specified by `by_vars` and `PARAMCD` must be a unique key of #' the input dataset after restricting it by the filter condition (`filter` diff --git a/R/derive_advs_params.R b/R/derive_advs_params.R index 881db1b92f..06e646a90a 100644 --- a/R/derive_advs_params.R +++ b/R/derive_advs_params.R @@ -5,10 +5,9 @@ #' #' **Note:** This is a wrapper function for the more generic `derive_param_computed()`. #' -#' @param dataset Input dataset -#' -#' The variables specified by the `by_vars` parameter, `PARAMCD`, and -#' `AVAL` are expected. +#' @param dataset +#' `r roxygen_param_dataset(expected_vars = c("by_vars"))` +#' `PARAMCD`, and `AVAL` are expected as well. #' #' The variable specified by `by_vars` and `PARAMCD` must be a unique key of #' the input dataset after restricting it by the filter condition (`filter` @@ -226,10 +225,9 @@ compute_map <- function(diabp, sysbp, hr = NULL) { #' #' **Note:** This is a wrapper function for the more generic `derive_param_computed()`. #' -#' @param dataset Input dataset -#' -#' The variables specified by the `by_vars` parameter, `PARAMCD`, and -#' `AVAL` are expected. +#' @param dataset +#' `r roxygen_param_dataset(expected_vars = c("by_vars"))` +#' `PARAMCD`, and `AVAL` are expected as well. #' #' The variable specified by `by_vars` and `PARAMCD` must be a unique key of #' the input dataset after restricting it by the filter condition (`filter` @@ -549,10 +547,9 @@ compute_bsa <- function(height = height, #' #' **Note:** This is a wrapper function for the more generic `derive_param_computed()`. #' -#' @param dataset Input dataset -#' -#' The variables specified by the `by_vars` parameter, `PARAMCD`, and -#' `AVAL` are expected. +#' @param dataset +#' `r roxygen_param_dataset(expected_vars = c("by_vars"))` +#' `PARAMCD`, and `AVAL` are expected as well. #' #' The variable specified by `by_vars` and `PARAMCD` must be a unique key of #' the input dataset after restricting it by the filter condition (`filter` diff --git a/R/derive_basetype_records.R b/R/derive_basetype_records.R index ef81d4cab4..c1b4cf85b9 100644 --- a/R/derive_basetype_records.R +++ b/R/derive_basetype_records.R @@ -12,9 +12,8 @@ #' Adds the `BASETYPE` variable to a dataset and duplicates records based upon #' the provided conditions. #' -#' @param dataset Input dataset -#' -#' The columns specified in the expressions inside `basetypes` are required. +#' @param dataset +#' `r roxygen_param_dataset(expected_vars = c("basetypes"))` #' #' @param basetypes A *named* list of expressions created using the #' `rlang::exprs()` function diff --git a/R/derive_date_vars.R b/R/derive_date_vars.R index fd59df5145..1c65d29c44 100644 --- a/R/derive_date_vars.R +++ b/R/derive_date_vars.R @@ -1252,9 +1252,8 @@ compute_tmf <- function(dtc, #' impute, we only enable to impute up to a highest level, i.e. you couldn't #' choose to say impute months, but not days. #' -#' @param dataset Input dataset. -#' -#' The date character vector (`dtc`) must be present. +#' @param dataset +#' `r roxygen_param_dataset(expected_vars = c("dtc"))` #' #' @param new_vars_prefix Prefix used for the output variable(s). #' @@ -1461,9 +1460,8 @@ derive_vars_dt <- function(dataset, # nolint: cyclocomp_linter #' impute, we only enable to impute up to a highest level, i.e. you couldn't #' choose to say impute months, but not days. #' -#' @param dataset Input dataset -#' -#' The date character vector (`dtc`) must be present. +#' @param dataset +#' `r roxygen_param_dataset(expected_vars = c("dtc"))` #' #' @param new_vars_prefix Prefix used for the output variable(s). #' diff --git a/R/derive_expected_records.R b/R/derive_expected_records.R index d7ba0e61e3..1369267729 100644 --- a/R/derive_expected_records.R +++ b/R/derive_expected_records.R @@ -3,10 +3,8 @@ #' Add expected records as new observations for each 'by group' when the dataset #' contains missing observations. #' -#' @param dataset Input dataset -#' -#' A data frame, the columns from `dataset_ref` and specified by the -#' `by_vars` parameter are expected. +#' @param dataset +#' `r roxygen_param_dataset(expected_vars = c("dataset_ref", "by_vars"))` #' #' @param dataset_expected_obs *Deprecated*, please use `dataset_ref` instead. #' diff --git a/R/derive_extreme_records.R b/R/derive_extreme_records.R index f8a0c64ce1..981e3d96ea 100644 --- a/R/derive_extreme_records.R +++ b/R/derive_extreme_records.R @@ -7,7 +7,7 @@ #' distinguishes `derive_extreme_records()` from `derive_summary_records()`, #' where only the by variables are populated for the new records. #' -#' @param dataset Input dataset +#' @param dataset `r roxygen_param_dataset()` #' #' If `dataset_add` is not specified, the new records are selected from the #' input dataset. In this case the variables specified by `by_vars` and @@ -92,6 +92,14 @@ #' automatically. #' #' +#' @param keep_source_vars Variables to be kept in the new records +#' +#' A named list or tidyselect expressions created by `exprs()` defining the +#' variables to be kept for the new records. The variables specified for +#' `by_vars` and `set_values_to` need not be specified here as they are kept +#' automatically. +#' +#' #' @inheritParams filter_extreme #' @inheritParams derive_summary_records #' diff --git a/R/derive_joined.R b/R/derive_joined.R index 1e0f5cff48..586f256360 100644 --- a/R/derive_joined.R +++ b/R/derive_joined.R @@ -6,9 +6,8 @@ #' variables from both datasets. For example, add the lowest value (nadir) #' before the current observation. #' -#' @param dataset Input dataset -#' -#' The variables specified by `by_vars` are expected. +#' @param dataset +#' `r roxygen_param_dataset(expected_vars = c("by_vars"))` #' #' @param dataset_add Additional dataset #' diff --git a/R/derive_locf_records.R b/R/derive_locf_records.R index 89f05f502f..55339fb16c 100644 --- a/R/derive_locf_records.R +++ b/R/derive_locf_records.R @@ -3,10 +3,8 @@ #' Adds LOCF records as new observations for each 'by group' when the dataset #' does not contain observations for missed visits/time points. #' -#' @param dataset Input dataset -#' -#' The columns specified by the `by_vars`, `analysis_var`, `order`, -#' `keep_vars` parameters are expected. +#' @param dataset +#' `r roxygen_param_dataset(expected_vars = c("by_vars", "analysis_var", "order", "keep_vars"))` #' #' @param dataset_expected_obs *Deprecated*, please use `dataset_ref` instead. #' diff --git a/R/derive_merged.R b/R/derive_merged.R index 7f3f03224c..aa36bbe947 100644 --- a/R/derive_merged.R +++ b/R/derive_merged.R @@ -6,9 +6,8 @@ #' (`filter_add` argument) and/or selecting the first or last observation for #' each by group (`order` and `mode` argument). #' -#' @param dataset Input dataset -#' -#' The variables specified by the `by_vars` argument are expected. +#' @param dataset +#' `r roxygen_param_dataset(expected_vars = c("by_vars"))` #' #' @param dataset_add Additional dataset #' @@ -746,34 +745,51 @@ get_not_mapped <- function() { admiral_environment$nmap } -#' Merge a Summary Variable +#' Merge Summary Variables #' #' @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`. -#' -#' @param dataset Input dataset -#' -#' The variables specified by the `by_vars` argument are expected. +#' @param dataset +#' `r roxygen_param_dataset(expected_vars = c("by_vars"))` #' #' @param dataset_add Additional dataset #' -#' The variables specified by the `by_vars` and the `analysis_var` arguments -#' are expected. +#' The variables specified by the `by_vars` and the variables used on the left +#' hand sides of the `new_vars` arguments are expected. #' #' @param new_var Variable to add #' +#' `r lifecycle::badge("deprecated")` Please use `new_vars` instead. +#' #' The specified variable is added to the input dataset (`dataset`) and set to #' the summarized values. #' #' @param 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. +#' The expressions on the left hand sides of `new_vars` are evaluated by the +#' specified *variables*. Then the resulting values are merged to the input +#' dataset (`dataset`) by the specified *variables*. #' #' *Permitted Values*: list of variables created by `exprs()` #' +#' @param new_vars New variables to add +#' +#' The specified variables are added to the input dataset. +#' +#' A named list of expressions is expected: +#' + LHS refer to a variable. +#' + RHS refers to the values to set to the variable. This can be a string, a +#' symbol, a numeric value, an expression or NA. If summary functions are +#' used, the values are summarized by the variables specified for `by_vars`. +#' +#' For example: +#' ``` +#' new_vars = exprs( +#' DOSESUM = sum(AVAL), +#' DOSEMEAN = mean(AVAL) +#' ) +#' ``` +#' #' @param filter_add Filter for additional dataset (`dataset_add`) #' #' Only observations fulfilling the specified condition are taken into account @@ -784,11 +800,15 @@ get_not_mapped <- function() { #' #' @param analysis_var Analysis variable #' +#' `r lifecycle::badge("deprecated")` Please use `new_vars` instead. +#' #' The values of the specified variable are summarized by the function #' specified for `summary_fun`. #' #' @param summary_fun Summary function #' +#' `r lifecycle::badge("deprecated")` Please use `new_vars` instead. +#' #' 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)`. @@ -799,18 +819,17 @@ get_not_mapped <- function() { #' 1. The records from the additional dataset (`dataset_add`) are restricted #' to those matching the `filter_add` condition. #' -#' 1. 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`). +#' 1. The new variables (`new_vars`) are created for each by group (`by_vars`) +#' in the additional dataset (`dataset_add`) by calling `summarize()`. I.e., +#' all observations of a by group are summarized to a single observation. #' -#' 1. 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. +#' 1. The new variables are merged to the input dataset. For observations +#' without a matching observation in the additional dataset the new variables +#' are set to `NA`. Observations in the additional dataset which have no +#' matching observation in the input dataset are ignored. #' #' @return The output dataset contains all observations and variables of the -#' input dataset and additionally the variable specified for `new_var`. +#' input dataset and additionally the variables specified for `new_vars`. #' #' @family der_gen #' @keywords der_gen @@ -840,9 +859,10 @@ get_not_mapped <- function() { #' adbds, #' dataset_add = adbds, #' by_vars = exprs(USUBJID, AVISIT), -#' new_var = MEANVIS, -#' analysis_var = AVAL, -#' summary_fun = function(x) mean(x, na.rm = TRUE) +#' new_vars = exprs( +#' MEANVIS = mean(AVAL, na.rm = TRUE), +#' MAXVIS = max(AVAL, na.rm = TRUE) +#' ) #' ) #' #' # Add a variable listing the lesion ids at baseline @@ -874,14 +894,13 @@ get_not_mapped <- function() { #' dataset_add = adtr, #' by_vars = exprs(USUBJID), #' filter_add = AVISIT == "BASELINE", -#' new_var = LESIONSBL, -#' analysis_var = LESIONID, -#' summary_fun = function(x) paste(x, collapse = ", ") +#' new_vars = exprs(LESIONSBL = paste(LESIONID, collapse = ", ")) #' ) #' derive_var_merged_summary <- function(dataset, dataset_add, by_vars, + new_vars = NULL, new_var, filter_add = NULL, analysis_var, @@ -889,20 +908,31 @@ derive_var_merged_summary <- function(dataset, assert_vars(by_vars) by_vars_left <- replace_values_by_names(by_vars) by_vars_right <- chr2vars(paste(vars2chr(by_vars))) - new_var <- assert_symbol(enexpr(new_var)) - analysis_var <- assert_symbol(enexpr(analysis_var)) + # once new_var is removed new_vars should be mandatory + assert_expr_list(new_vars, named = TRUE, optional = TRUE) filter_add <- assert_filter_cond(enexpr(filter_add), optional = TRUE) - assert_s3_class(summary_fun, "function") assert_data_frame( dataset, required_vars = by_vars_left ) assert_data_frame( dataset_add, - required_vars = expr_c(by_vars_right, analysis_var) + required_vars = expr_c(by_vars_right, extract_vars(new_vars)) ) + if (!missing(new_var) || !missing(analysis_var) || !missing(summary_fun)) { + deprecate_warn( + "1.0.0", + I("derive_var_merged_summary(new_var = , anaylsis_var = , summary_fun = )"), + "derive_var_merged_summary(new_vars = )" + ) + new_var <- assert_symbol(enexpr(new_var)) + analysis_var <- assert_symbol(enexpr(analysis_var)) + assert_s3_class(summary_fun, "function") + new_vars <- exprs(!!new_var := {{ summary_fun }}(!!analysis_var), !!!new_vars) + } + # Summarise the analysis value and merge to the original dataset derive_vars_merged( dataset, @@ -910,10 +940,9 @@ derive_var_merged_summary <- function(dataset, dataset_add, by_vars = by_vars_right, filter = !!filter_add, - analysis_var = !!analysis_var, - summary_fun = summary_fun - ), - by_vars = by_vars, - new_vars = exprs(!!new_var := !!analysis_var) + set_values_to = new_vars, + ) %>% + select(!!!by_vars_right, names(new_vars)), + by_vars = by_vars ) } diff --git a/R/derive_param_computed.R b/R/derive_param_computed.R index ff48bcbe1c..4a9f1b1600 100644 --- a/R/derive_param_computed.R +++ b/R/derive_param_computed.R @@ -7,9 +7,9 @@ #' blood pressure (DIABP) with the formula #' \deqn{MAP = \frac{SYSBP + 2 DIABP}{3}}{MAP = (SYSBP + 2 DIABP) / 3} #' -#' @param dataset Input dataset -#' -#' The variables specified by the `by_vars` parameter are expected. +#' @param dataset +#' `r roxygen_param_dataset(expected_vars = c("by_vars"))` +#' `PARAMCD` is expected as well. #' #' The variable specified by `by_vars` and `PARAMCD` must be a unique key of #' the input dataset after restricting it by the filter condition (`filter` @@ -428,7 +428,8 @@ assert_parameters_argument <- function(parameters, optional = TRUE) { #' The function creates temporary parameters and variables of the form #' `.`, e.g., `AVAL.WEIGHT`. #' -#' @param dataset Input dataset +#' @param dataset +#' `r roxygen_param_dataset(expected_vars = c("by_vars"))` #' #' @param by_vars By variables #' diff --git a/R/derive_param_doseint.R b/R/derive_param_doseint.R index 016af0088b..6a863e8891 100644 --- a/R/derive_param_doseint.R +++ b/R/derive_param_doseint.R @@ -8,10 +8,9 @@ #' The analysis value of the new parameter is derived as #' Total Dose / Planned Dose * 100 #' -#' @param dataset Input dataset -#' -#' The variables specified by the `by_vars` parameter, `PARAMCD`, and -#' `AVAL` are expected. +#' @param dataset +#' `r roxygen_param_dataset(expected_vars = c("by_vars"))` +#' `PARAMCD`, and `AVAL` are expected as well. #' #' The variable specified by `by_vars` and `PARAMCD` must be a unique key of #' the input dataset after restricting it by the filter condition (`filter` diff --git a/R/derive_param_exist_flag.R b/R/derive_param_exist_flag.R index c3df01bad8..6ecad23db6 100644 --- a/R/derive_param_exist_flag.R +++ b/R/derive_param_exist_flag.R @@ -5,10 +5,9 @@ #' function can derive a parameter indicating if there is measurable disease at #' baseline. #' -#' @param dataset Input dataset -#' -#' The variables specified for `by_vars` and the `PARAMCD` variable are -#' expected. +#' @param dataset +#' `r roxygen_param_dataset(expected_vars = c("by_vars"))` +#' `PARAMCD` is expected as well. #' #' @param dataset_ref Reference dataset, e.g., ADSL #' diff --git a/R/derive_param_exposure.R b/R/derive_param_exposure.R index 652e9d2992..3c0e81c6b3 100644 --- a/R/derive_param_exposure.R +++ b/R/derive_param_exposure.R @@ -3,10 +3,9 @@ #' Add a record computed from the aggregated analysis value of another parameter and compute the #' start (`ASTDT(M)`)and end date (`AENDT(M)`) as the minimum and maximum date by `by_vars`. #' -#' @param dataset Input dataset -#' -#' + The variables specified by the `by_vars`,`analysis_var` parameters and `PARAMCD` are -#' expected, +#' @param dataset +#' `r roxygen_param_dataset(expected_vars = c("by_vars", "analysis_var"))` +#' `PARAMCD` is expected as well, #' + Either `ASTDTM` and `AENDTM` or `ASTDT` and `AENDT` are also expected. #' #' @param filter Filter condition @@ -138,11 +137,23 @@ derive_param_exposure <- function(dataset, dtm <- c("ASTDTM", "AENDTM") %in% colnames(dataset) dt <- c("ASTDT", "AENDT") %in% colnames(dataset) + set_dtm <- NULL + set_dt <- NULL if (all(dtm)) { dates <- exprs(ASTDTM, AENDTM) + set_dtm <- exprs( + ASTDTM = min(ASTDTM, na.rm = TRUE), + AENDTM = max(coalesce(AENDTM, ASTDTM), na.rm = TRUE) + ) } else { dates <- exprs(ASTDT, AENDT) } + if (all(dt)) { + set_dt <- exprs( + ASTDT = min(ASTDT, na.rm = TRUE), + AENDT = max(coalesce(AENDT, ASTDT), na.rm = TRUE) + ) + } assert_data_frame(dataset, required_vars = expr_c(by_vars, analysis_var, exprs(PARAMCD), dates) @@ -155,57 +166,19 @@ derive_param_exposure <- function(dataset, assert_character_vector(input_code, values = params_available) assert_s3_class(summary_fun, "function") - subset_ds <- dataset %>% - filter_if(filter) - - add_data <- subset_ds %>% - get_summary_records( - by_vars = by_vars, - filter = PARAMCD == !!input_code, - analysis_var = !!analysis_var, - summary_fun = summary_fun, - set_values_to = set_values_to - ) - - # add the dates for the derived parameters - tmp_start <- get_new_tmp_var(dataset) - tmp_end <- get_new_tmp_var(dataset) - if (all(dtm)) { - dates <- subset_ds %>% - group_by(!!!by_vars) %>% - summarise( - !!tmp_start := min(ASTDTM, na.rm = TRUE), - !!tmp_end := max(coalesce(AENDTM, ASTDTM), na.rm = TRUE) - ) %>% - ungroup() - expo_data <- add_data %>% - derive_vars_merged(dataset_add = dates, by_vars = by_vars) %>% - mutate( - ASTDTM = !!tmp_start, - AENDTM = !!tmp_end - ) %>% - remove_tmp_vars() - - if (all(dt)) { - expo_data <- expo_data %>% - mutate(ASTDT = date(ASTDTM), AENDT = date(AENDTM)) - } - } else { - dates <- subset_ds %>% - group_by(!!!by_vars) %>% - summarise( - !!tmp_start := min(ASTDT, na.rm = TRUE), - !!tmp_end := max(coalesce(AENDT, ASTDT), na.rm = TRUE) - ) %>% - ungroup() - expo_data <- add_data %>% - derive_vars_merged(dataset_add = dates, by_vars = by_vars) %>% - mutate( - ASTDT = !!tmp_start, - AENDT = !!tmp_end - ) %>% - remove_tmp_vars() + if (is.null(filter)) { + filter <- TRUE } - bind_rows(dataset, expo_data) + derive_summary_records( + dataset, + by_vars = by_vars, + filter = PARAMCD == !!input_code & !!filter, + set_values_to = exprs( + !!analysis_var := {{ summary_fun }}(!!analysis_var), + !!!set_dtm, + !!!set_dt, + !!!set_values_to + ) + ) } diff --git a/R/derive_param_extreme_record.R b/R/derive_param_extreme_record.R index d14753b984..e55431b7ea 100644 --- a/R/derive_param_extreme_record.R +++ b/R/derive_param_extreme_record.R @@ -4,7 +4,7 @@ #' source datasets, based on user-defined filter, order and by group criteria. #' All variables of the selected observation are kept. #' -#' @param dataset Input dataset +#' @param dataset `r roxygen_param_dataset()` #' #' @param sources Sources #' diff --git a/R/derive_param_framingham.R b/R/derive_param_framingham.R index 7f10bb234f..5186206151 100644 --- a/R/derive_param_framingham.R +++ b/R/derive_param_framingham.R @@ -4,10 +4,9 @@ #' Adds a record for framingham score (FCVD101) for each by group #' (e.g., subject and visit) where the source parameters are available. #' -#' @param dataset Input dataset -#' -#' The variables specified by the `by_vars` parameter, `PARAMCD`, and -#' `AVAL` are expected. +#' @param dataset +#' `r roxygen_param_dataset(expected_vars = c("by_vars"))` +#' `PARAMCD`, and `AVAL` are expected as well. #' #' The variable specified by `by_vars` and `PARAMCD` must be a unique key of #' the input dataset after restricting it by the filter condition (`filter` diff --git a/R/derive_param_tte.R b/R/derive_param_tte.R index 9b5069813d..db870381d1 100644 --- a/R/derive_param_tte.R +++ b/R/derive_param_tte.R @@ -2,9 +2,8 @@ #' #' Add a time-to-event parameter to the input dataset. #' -#' @param dataset Input dataset -#' -#' The `PARAMCD` variable is expected. +#' @param dataset `r roxygen_param_dataset()` +#' `PARAMCD` is expected. #' #' @param dataset_adsl ADSL input dataset #' diff --git a/R/derive_param_wbc_abs.R b/R/derive_param_wbc_abs.R index 60ec791326..5dc7a1e79d 100644 --- a/R/derive_param_wbc_abs.R +++ b/R/derive_param_wbc_abs.R @@ -4,10 +4,9 @@ #' #' Add a parameter by converting lab differentials from fraction or percentage to absolute values #' -#' @param dataset Input dataset -#' -#' The variables specified by the `by_vars` argument, `PARAMCD`, and `AVAL` -#' are expected to be present. +#' @param dataset +#' `r roxygen_param_dataset(expected_vars = c("by_vars"))` +#' `PARAMCD`, and `AVAL` are expected as well. #' #' The variable specified by `by_vars` and `PARAMCD` must be a unique key of #' the input dataset, and to the parameters specified by `wbc_code` and `diff_code`. diff --git a/R/derive_summary_records.R b/R/derive_summary_records.R index 9418e0cafd..ced3a0093e 100644 --- a/R/derive_summary_records.R +++ b/R/derive_summary_records.R @@ -11,7 +11,7 @@ #' retain those common values in the newly derived records. Otherwise new value #' will be set to `NA`. #' -#' @param dataset A data frame. +#' @param dataset `r roxygen_param_dataset(expected_vars = c("by_vars", "analysis_var"))` #' #' @param by_vars Variables to consider for generation of groupwise summary #' records. Providing the names of variables in [exprs()] will create a @@ -29,111 +29,87 @@ #' + `filter = (dplyr::n() > 2)` will filter n count of `by_vars` greater #' than 2. #' -#' @param analysis_var Analysis variable. -#' -#' @param summary_fun Function that takes as an input the `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)`. -#' -#' @param set_values_to Variables to be set -#' -#' The specified variables are set to the specified values for the new -#' observations. -#' -#' A list of variable name-value pairs is expected. -#' + LHS refers to a variable. -#' + RHS refers to the values to set to the variable. This can be a string, a -#' symbol, a numeric value, an expression, or `NA`, e.g., `exprs(PARAMCD = -#' "TDOSE", PARCAT1 = "OVERALL")`. +#' @inheritParams get_summary_records #' #' @return A data frame with derived records appended to original dataset. #' #' @family der_prm_bds_findings #' @keywords der_prm_bds_findings #' -#' @seealso `get_summary_records()` +#' @seealso [get_summary_records()], [derive_var_merged_summary()] #' #' @export #' #' @examples #' library(tibble) -#' library(dplyr, warn.conflicts = TRUE) +#' library(dplyr) #' #' adeg <- tribble( -#' ~USUBJID, ~EGSEQ, ~PARAM, ~AVISIT, ~EGDTC, ~AVAL, ~TRTA, -#' "XYZ-1001", 1, "QTcF Int. (msec)", "Baseline", "2016-02-24T07:50", 385, "", -#' "XYZ-1001", 2, "QTcF Int. (msec)", "Baseline", "2016-02-24T07:52", 399, "", -#' "XYZ-1001", 3, "QTcF Int. (msec)", "Baseline", "2016-02-24T07:56", 396, "", -#' "XYZ-1001", 4, "QTcF Int. (msec)", "Visit 2", "2016-03-08T09:45", 384, "Placebo", -#' "XYZ-1001", 5, "QTcF Int. (msec)", "Visit 2", "2016-03-08T09:48", 393, "Placebo", -#' "XYZ-1001", 6, "QTcF Int. (msec)", "Visit 2", "2016-03-08T09:51", 388, "Placebo", -#' "XYZ-1001", 7, "QTcF Int. (msec)", "Visit 3", "2016-03-22T10:45", 385, "Placebo", -#' "XYZ-1001", 8, "QTcF Int. (msec)", "Visit 3", "2016-03-22T10:48", 394, "Placebo", -#' "XYZ-1001", 9, "QTcF Int. (msec)", "Visit 3", "2016-03-22T10:51", 402, "Placebo", -#' "XYZ-1002", 1, "QTcF Int. (msec)", "Baseline", "2016-02-22T07:58", 399, "", -#' "XYZ-1002", 2, "QTcF Int. (msec)", "Baseline", "2016-02-22T07:58", 410, "", -#' "XYZ-1002", 3, "QTcF Int. (msec)", "Baseline", "2016-02-22T08:01", 392, "", -#' "XYZ-1002", 4, "QTcF Int. (msec)", "Visit 2", "2016-03-06T09:50", 401, "Active 20mg", -#' "XYZ-1002", 5, "QTcF Int. (msec)", "Visit 2", "2016-03-06T09:53", 407, "Active 20mg", -#' "XYZ-1002", 6, "QTcF Int. (msec)", "Visit 2", "2016-03-06T09:56", 400, "Active 20mg", -#' "XYZ-1002", 7, "QTcF Int. (msec)", "Visit 3", "2016-03-24T10:50", 412, "Active 20mg", -#' "XYZ-1002", 8, "QTcF Int. (msec)", "Visit 3", "2016-03-24T10:53", 414, "Active 20mg", -#' "XYZ-1002", 9, "QTcF Int. (msec)", "Visit 3", "2016-03-24T10:56", 402, "Active 20mg", -#' ) +#' ~USUBJID, ~EGSEQ, ~PARAM, ~AVISIT, ~EGDTC, ~AVAL, ~TRTA, +#' "XYZ-1001", 1, "QTcF Int. (msec)", "Baseline", "2016-02-24T07:50", 385, NA_character_, +#' "XYZ-1001", 2, "QTcF Int. (msec)", "Baseline", "2016-02-24T07:52", 399, NA_character_, +#' "XYZ-1001", 3, "QTcF Int. (msec)", "Baseline", "2016-02-24T07:56", 396, NA_character_, +#' "XYZ-1001", 4, "QTcF Int. (msec)", "Visit 2", "2016-03-08T09:45", 384, "Placebo", +#' "XYZ-1001", 5, "QTcF Int. (msec)", "Visit 2", "2016-03-08T09:48", 393, "Placebo", +#' "XYZ-1001", 6, "QTcF Int. (msec)", "Visit 2", "2016-03-08T09:51", 388, "Placebo", +#' "XYZ-1001", 7, "QTcF Int. (msec)", "Visit 3", "2016-03-22T10:45", 385, "Placebo", +#' "XYZ-1001", 8, "QTcF Int. (msec)", "Visit 3", "2016-03-22T10:48", 394, "Placebo", +#' "XYZ-1001", 9, "QTcF Int. (msec)", "Visit 3", "2016-03-22T10:51", 402, "Placebo", +#' "XYZ-1002", 1, "QTcF Int. (msec)", "Baseline", "2016-02-22T07:58", 399, NA_character_, +#' "XYZ-1002", 2, "QTcF Int. (msec)", "Baseline", "2016-02-22T07:58", 410, NA_character_, +#' "XYZ-1002", 3, "QTcF Int. (msec)", "Baseline", "2016-02-22T08:01", 392, NA_character_, +#' "XYZ-1002", 4, "QTcF Int. (msec)", "Visit 2", "2016-03-06T09:50", 401, "Active 20mg", +#' "XYZ-1002", 5, "QTcF Int. (msec)", "Visit 2", "2016-03-06T09:53", 407, "Active 20mg", +#' "XYZ-1002", 6, "QTcF Int. (msec)", "Visit 2", "2016-03-06T09:56", 400, "Active 20mg", +#' "XYZ-1002", 7, "QTcF Int. (msec)", "Visit 3", "2016-03-24T10:50", 412, "Active 20mg", +#' "XYZ-1002", 8, "QTcF Int. (msec)", "Visit 3", "2016-03-24T10:53", 414, "Active 20mg", +#' "XYZ-1002", 9, "QTcF Int. (msec)", "Visit 3", "2016-03-24T10:56", 402, "Active 20mg" +#' ) %>% +#' mutate( +#' ADTM = convert_dtc_to_dtm(EGDTC) +#' ) #' #' # Summarize the average of the triplicate ECG interval values (AVAL) #' derive_summary_records( #' adeg, #' by_vars = exprs(USUBJID, PARAM, AVISIT), -#' analysis_var = AVAL, -#' summary_fun = function(x) mean(x, na.rm = TRUE), -#' set_values_to = exprs(DTYPE = "AVERAGE") -#' ) -#' -#' advs <- tribble( -#' ~USUBJID, ~VSSEQ, ~PARAM, ~AVAL, ~VSSTRESU, ~VISIT, ~VSDTC, -#' "XYZ-001-001", 1164, "Weight", 99, "kg", "Screening", "2018-03-19", -#' "XYZ-001-001", 1165, "Weight", 101, "kg", "Run-In", "2018-03-26", -#' "XYZ-001-001", 1166, "Weight", 100, "kg", "Baseline", "2018-04-16", -#' "XYZ-001-001", 1167, "Weight", 94, "kg", "Week 24", "2018-09-30", -#' "XYZ-001-001", 1168, "Weight", 92, "kg", "Week 48", "2019-03-17", -#' "XYZ-001-001", 1169, "Weight", 95, "kg", "Week 52", "2019-04-14", -#' ) +#' set_values_to = exprs( +#' AVAL = mean(AVAL, na.rm = TRUE), +#' DTYPE = "AVERAGE" +#' ) +#' ) %>% +#' arrange(USUBJID, AVISIT) #' -#' # Set new values to any variable. Here, `DTYPE = MAXIMUM` refers to `max()` records -#' # and `DTYPE = AVERAGE` refers to `mean()` records. +#' # Derive more than one summary variable #' derive_summary_records( -#' advs, -#' by_vars = exprs(USUBJID, PARAM), -#' analysis_var = AVAL, -#' summary_fun = max, -#' set_values_to = exprs(DTYPE = "MAXIMUM") -#' ) %>% -#' derive_summary_records( -#' by_vars = exprs(USUBJID, PARAM), -#' analysis_var = AVAL, -#' summary_fun = mean, -#' set_values_to = exprs(DTYPE = "AVERAGE") +#' adeg, +#' by_vars = exprs(USUBJID, PARAM, AVISIT), +#' set_values_to = exprs( +#' AVAL = mean(AVAL), +#' ADTM = max(ADTM), +#' DTYPE = "AVERAGE" #' ) +#' ) %>% +#' arrange(USUBJID, AVISIT) %>% +#' select(-EGSEQ, -TRTA) #' #' # Sample ADEG dataset with triplicate record for only AVISIT = 'Baseline' #' adeg <- tribble( -#' ~USUBJID, ~EGSEQ, ~PARAM, ~AVISIT, ~EGDTC, ~AVAL, ~TRTA, -#' "XYZ-1001", 1, "QTcF Int. (msec)", "Baseline", "2016-02-24T07:50", 385, "", -#' "XYZ-1001", 2, "QTcF Int. (msec)", "Baseline", "2016-02-24T07:52", 399, "", -#' "XYZ-1001", 3, "QTcF Int. (msec)", "Baseline", "2016-02-24T07:56", 396, "", -#' "XYZ-1001", 4, "QTcF Int. (msec)", "Visit 2", "2016-03-08T09:48", 393, "Placebo", -#' "XYZ-1001", 5, "QTcF Int. (msec)", "Visit 2", "2016-03-08T09:51", 388, "Placebo", -#' "XYZ-1001", 6, "QTcF Int. (msec)", "Visit 3", "2016-03-22T10:48", 394, "Placebo", -#' "XYZ-1001", 7, "QTcF Int. (msec)", "Visit 3", "2016-03-22T10:51", 402, "Placebo", -#' "XYZ-1002", 1, "QTcF Int. (msec)", "Baseline", "2016-02-22T07:58", 399, "", -#' "XYZ-1002", 2, "QTcF Int. (msec)", "Baseline", "2016-02-22T07:58", 410, "", -#' "XYZ-1002", 3, "QTcF Int. (msec)", "Baseline", "2016-02-22T08:01", 392, "", -#' "XYZ-1002", 4, "QTcF Int. (msec)", "Visit 2", "2016-03-06T09:53", 407, "Active 20mg", -#' "XYZ-1002", 5, "QTcF Int. (msec)", "Visit 2", "2016-03-06T09:56", 400, "Active 20mg", -#' "XYZ-1002", 6, "QTcF Int. (msec)", "Visit 3", "2016-03-24T10:53", 414, "Active 20mg", -#' "XYZ-1002", 7, "QTcF Int. (msec)", "Visit 3", "2016-03-24T10:56", 402, "Active 20mg", +#' ~USUBJID, ~EGSEQ, ~PARAM, ~AVISIT, ~EGDTC, ~AVAL, ~TRTA, +#' "XYZ-1001", 1, "QTcF Int. (msec)", "Baseline", "2016-02-24T07:50", 385, NA_character_, +#' "XYZ-1001", 2, "QTcF Int. (msec)", "Baseline", "2016-02-24T07:52", 399, NA_character_, +#' "XYZ-1001", 3, "QTcF Int. (msec)", "Baseline", "2016-02-24T07:56", 396, NA_character_, +#' "XYZ-1001", 4, "QTcF Int. (msec)", "Visit 2", "2016-03-08T09:48", 393, "Placebo", +#' "XYZ-1001", 5, "QTcF Int. (msec)", "Visit 2", "2016-03-08T09:51", 388, "Placebo", +#' "XYZ-1001", 6, "QTcF Int. (msec)", "Visit 3", "2016-03-22T10:48", 394, "Placebo", +#' "XYZ-1001", 7, "QTcF Int. (msec)", "Visit 3", "2016-03-22T10:51", 402, "Placebo", +#' "XYZ-1002", 1, "QTcF Int. (msec)", "Baseline", "2016-02-22T07:58", 399, NA_character_, +#' "XYZ-1002", 2, "QTcF Int. (msec)", "Baseline", "2016-02-22T07:58", 410, NA_character_, +#' "XYZ-1002", 3, "QTcF Int. (msec)", "Baseline", "2016-02-22T08:01", 392, NA_character_, +#' "XYZ-1002", 4, "QTcF Int. (msec)", "Visit 2", "2016-03-06T09:53", 407, "Active 20mg", +#' "XYZ-1002", 5, "QTcF Int. (msec)", "Visit 2", "2016-03-06T09:56", 400, "Active 20mg", +#' "XYZ-1002", 6, "QTcF Int. (msec)", "Visit 3", "2016-03-24T10:53", 414, "Active 20mg", +#' "XYZ-1002", 7, "QTcF Int. (msec)", "Visit 3", "2016-03-24T10:56", 402, "Active 20mg" #' ) #' #' # Compute the average of AVAL only if there are more than 2 records within the @@ -142,25 +118,36 @@ #' adeg, #' by_vars = exprs(USUBJID, PARAM, AVISIT), #' filter = n() > 2, -#' analysis_var = AVAL, -#' summary_fun = function(x) mean(x, na.rm = TRUE), -#' set_values_to = exprs(DTYPE = "AVERAGE") -#' ) +#' set_values_to = exprs( +#' AVAL = mean(AVAL, na.rm = TRUE), +#' DTYPE = "AVERAGE" +#' ) +#' ) %>% +#' arrange(USUBJID, AVISIT) derive_summary_records <- function(dataset, by_vars, filter = NULL, analysis_var, summary_fun, - set_values_to = NULL) { + set_values_to) { assert_vars(by_vars) - analysis_var <- assert_symbol(enexpr(analysis_var)) filter <- assert_filter_cond(enexpr(filter), optional = TRUE) - assert_s3_class(summary_fun, "function") assert_data_frame( dataset, - required_vars = expr_c(by_vars, analysis_var) + required_vars = by_vars ) - assert_varval_list(set_values_to, optional = TRUE) + assert_varval_list(set_values_to) + + if (!missing(analysis_var) || !missing(summary_fun)) { + deprecate_warn( + "1.0.0", + I("derive_summary_records(anaylsis_var = , summary_fun = )"), + "derive_summary_records(set_values_to = )" + ) + analysis_var <- assert_symbol(enexpr(analysis_var)) + assert_s3_class(summary_fun, "function") + set_values_to <- exprs(!!analysis_var := {{ summary_fun }}(!!analysis_var), !!!set_values_to) + } # Summarise the analysis value and bind to the original dataset bind_rows( @@ -169,8 +156,6 @@ derive_summary_records <- function(dataset, dataset, by_vars = by_vars, filter = !!filter, - analysis_var = !!analysis_var, - summary_fun = summary_fun, set_values_to = set_values_to ) ) diff --git a/R/derive_var_analysis_ratio.R b/R/derive_var_analysis_ratio.R index 98a35cce18..7a41ac6015 100644 --- a/R/derive_var_analysis_ratio.R +++ b/R/derive_var_analysis_ratio.R @@ -2,7 +2,8 @@ #' #' Derives a ratio variable for a BDS dataset based on user specified variables. #' -#' @param dataset Input dataset +#' @param dataset +#' `r roxygen_param_dataset(expected_vars = c("numer_var", "denom_var"))` #' #' @param numer_var Variable containing numeric values to be used in the numerator of #' the ratio calculation. diff --git a/R/derive_var_anrind.R b/R/derive_var_anrind.R index 909e5b452c..ae37f01591 100644 --- a/R/derive_var_anrind.R +++ b/R/derive_var_anrind.R @@ -1,6 +1,10 @@ #' Derive Reference Range Indicator #' -#' @param dataset The input dataset +#' @param dataset +#' `r roxygen_param_dataset()` +#' `ANRLO`, `ANRHI`, and `AVAL` are expected and if `use_a1hia1lo` is set to `TRUE`, +#' `A1LO` and `A1H1` are expected as well. +#' #' @param use_a1hia1lo A logical value indicating whether to use `A1H1` and `A1LO` in #' the derivation of `ANRIND`. #' diff --git a/R/derive_var_atoxgr.R b/R/derive_var_atoxgr.R index 1addcf86f2..7cb8467250 100644 --- a/R/derive_var_atoxgr.R +++ b/R/derive_var_atoxgr.R @@ -3,9 +3,8 @@ #' @description #' Derives a character lab grade based on severity/toxicity criteria. #' -#' @param dataset Input data set -#' -#' The columns specified by `tox_description_var` parameter is expected. +#' @param dataset +#' `r roxygen_param_dataset(expected_vars = c("tox_description_var"))` #' #' @param new_var Name of the character grade variable to create, for example, `ATOXGRH` #' or `ATOXGRL`. @@ -246,10 +245,9 @@ derive_var_atoxgr_dir <- function(dataset, #' #' Derives character lab grade based on high and low severity/toxicity grade(s). #' -#' @param dataset Input data set -#' -#' The columns `ATOXGRL`, `ATOXGRH` and specified by `lotox_description_var`, -#' and `hitox_description_var` parameters are expected. +#' @param dataset +#' `r roxygen_param_dataset(expected_vars = c("lotox_description_var", "hitox_description_var"))` +#' `ATOXGRL`, and `ATOXGRH` are expected as well. #' #' @param lotox_description_var Variable containing the toxicity grade description #' for low values, eg. "Anemia" diff --git a/R/derive_var_base.R b/R/derive_var_base.R index 5f88f582bf..af60e1d676 100644 --- a/R/derive_var_base.R +++ b/R/derive_var_base.R @@ -4,7 +4,7 @@ #' #' **Note:** This is a wrapper function for the more generic `derive_vars_merged()`. #' -#' @param dataset The input dataset +#' @param dataset `r roxygen_param_dataset(expected_vars = c("by_vars", "source_var"))` #' #' @param by_vars Grouping variables uniquely identifying a set #' of records for which to calculate `new_var` diff --git a/R/derive_var_chg.R b/R/derive_var_chg.R index 3a0ca93f03..0d913d4437 100644 --- a/R/derive_var_chg.R +++ b/R/derive_var_chg.R @@ -4,6 +4,8 @@ #' #' @param dataset The input dataset. Required variables are `AVAL` and #' `BASE`. +#' @param dataset +#' `r roxygen_param_dataset()` `AVAL` and `BASE` are expected. #' #' @details #' Change from baseline is calculated by subtracting the baseline value diff --git a/R/derive_var_dthcaus.R b/R/derive_var_dthcaus.R index 084182fa8d..f3f74631fb 100644 --- a/R/derive_var_dthcaus.R +++ b/R/derive_var_dthcaus.R @@ -2,9 +2,8 @@ #' #' Derive death cause (`DTHCAUS`) and add traceability variables if required. #' -#' @param dataset Input dataset. -#' -#' The variables specified by `subject_keys` are required. +#' @param dataset +#' `r roxygen_param_dataset(expected_vars = c("subject_keys"))` #' #' @param source_datasets A named `list` containing datasets in which to search for the #' death cause diff --git a/R/derive_var_extreme_date.R b/R/derive_var_extreme_date.R index f30e9e1c0b..c4611189c6 100644 --- a/R/derive_var_extreme_date.R +++ b/R/derive_var_extreme_date.R @@ -3,9 +3,8 @@ #' Add the first or last datetime from multiple sources to the dataset, e.g., #' the last known alive datetime (`LSTALVDTM`). #' -#' @param dataset Input dataset -#' -#' The variables specified by `subject_keys` are required. +#' @param dataset +#' `r roxygen_param_dataset(expected_vars = c("subject_keys"))` #' #' @param new_var Name of variable to create #' diff --git a/R/derive_var_extreme_flag.R b/R/derive_var_extreme_flag.R index 0dcab3cdd8..f5c52f658c 100644 --- a/R/derive_var_extreme_flag.R +++ b/R/derive_var_extreme_flag.R @@ -2,9 +2,8 @@ #' #' Add a variable flagging the first or last observation within each by group #' -#' @param dataset Input dataset -#' -#' The variables specified by the `by_vars` parameter are expected. +#' @param dataset +#' `r roxygen_param_dataset(expected_vars = c("by_vars"))` #' #' @param order Sort order #' diff --git a/R/derive_var_joined_exist_flag.R b/R/derive_var_joined_exist_flag.R index fd61afa929..fece51a587 100644 --- a/R/derive_var_joined_exist_flag.R +++ b/R/derive_var_joined_exist_flag.R @@ -10,10 +10,8 @@ #' response value can be confirmed by an other assessment. This is commonly #' used in endpoints such as best overall response. #' -#' @param dataset Input dataset -#' -#' The variables specified by the `by_vars` and `join_vars` parameter are -#' expected. +#' @param dataset +#' `r roxygen_param_dataset(expected_vars = c("by_vars", "join_vars"))` #' #' @param by_vars By variables #' diff --git a/R/derive_var_obs_number.R b/R/derive_var_obs_number.R index ffa425263f..46bcbef97d 100644 --- a/R/derive_var_obs_number.R +++ b/R/derive_var_obs_number.R @@ -2,10 +2,8 @@ #' #' Adds a variable numbering the observations within each by group #' -#' @param dataset Input dataset -#' -#' The variables specified by the `order` and the `by_vars` parameter are -#' expected. +#' @param dataset +#' `r roxygen_param_dataset(expected_vars = c("by_vars", "order"))` #' #' @param by_vars Grouping variables #' diff --git a/R/derive_var_ontrtfl.R b/R/derive_var_ontrtfl.R index e3a6ddebb1..64eab8116b 100644 --- a/R/derive_var_ontrtfl.R +++ b/R/derive_var_ontrtfl.R @@ -4,7 +4,7 @@ #' assessment date (e.g `ADT`) or event start and end dates (e.g. #' `ASTDT`/`AENDT`). #' -#' @param dataset Input dataset. +#' @param dataset `r roxygen_param_dataset()` #' #' Required columns are `start_date`, `end_date`, `ref_start_date` and #' `ref_end_date`. diff --git a/R/derive_var_pchg.R b/R/derive_var_pchg.R index 035ab479f6..03ac7e8c30 100644 --- a/R/derive_var_pchg.R +++ b/R/derive_var_pchg.R @@ -2,8 +2,8 @@ #' #' Derive percent change from baseline (`PCHG`) in a BDS dataset #' -#' @param dataset The input dataset. Required variables are `AVAL` and -#' `BASE`. +#' @param dataset `r roxygen_param_dataset()` +#' `AVAL` and `BASE` are expected. #' #' @details #' Percent change from baseline is calculated by dividing change from diff --git a/R/derive_var_relative_flag.R b/R/derive_var_relative_flag.R index 42883f1c45..a2295d85ce 100644 --- a/R/derive_var_relative_flag.R +++ b/R/derive_var_relative_flag.R @@ -5,10 +5,8 @@ #' called to flag for each subject all observations before the first disease #' progression or to flag all AEs after a specific AE. #' -#' @param dataset Input dataset -#' -#' The variables specified by the `order` and the `by_vars` argument are -#' expected. +#' @param dataset +#' `r roxygen_param_dataset(expected_vars = c("by_vars", "order"))` #' #' @param by_vars Grouping variables #' diff --git a/R/derive_var_shift.R b/R/derive_var_shift.R index f02600bbb6..38dfe85e8d 100644 --- a/R/derive_var_shift.R +++ b/R/derive_var_shift.R @@ -4,9 +4,8 @@ #' values based on user-defined pairing, e.g., shift from baseline to #' analysis value, shift from baseline grade to analysis grade, ... #' -#' @param dataset Input dataset -#' -#' The columns specified by `from_var` and the `to_var` parameters are expected. +#' @param dataset +#' `r roxygen_param_dataset(expected_vars = c("from_var", "to_var"))` #' #' @param new_var Name of the character shift variable to create. #' diff --git a/R/derive_var_trtdurd.R b/R/derive_var_trtdurd.R index d2e3e46042..88c36c0c00 100644 --- a/R/derive_var_trtdurd.R +++ b/R/derive_var_trtdurd.R @@ -4,10 +4,8 @@ #' #' **Note:** This is a wrapper function for the more generic `derive_vars_duration()`. #' -#' @param dataset Input dataset -#' -#' The columns specified by the `start_date` and the `end_date` parameter are -#' expected. +#' @param dataset +#' `r roxygen_param_dataset(expected_vars = c("start_date", "end_date"))` #' #' @param start_date The start date #' diff --git a/R/derive_var_trtemfl.R b/R/derive_var_trtemfl.R index dc88db41db..ef09e50296 100644 --- a/R/derive_var_trtemfl.R +++ b/R/derive_var_trtemfl.R @@ -2,7 +2,7 @@ #' #' Derive treatment emergent analysis flag (e.g., `TRTEMFL`). #' -#' @param dataset Input dataset +#' @param dataset `r roxygen_param_dataset()` #' #' The variables specified by `start_date`, `end_date`, `trt_start_date`, #' `trt_end_date`, `initial_intensity`, and `intensity` are expected. diff --git a/R/derive_vars_aage.R b/R/derive_vars_aage.R index 8e4afc3e31..18ad0c95f8 100644 --- a/R/derive_vars_aage.R +++ b/R/derive_vars_aage.R @@ -6,10 +6,8 @@ #' #' @inheritParams derive_vars_duration #' -#' @param dataset Input dataset -#' -#' The columns specified by the `start_date` and the `end_date` parameter are -#' expected. +#' @param dataset +#' `r roxygen_param_dataset(expected_vars = c("start_date", "end_date"))` #' #' @param start_date The start date #' @@ -120,9 +118,8 @@ derive_vars_aage <- function(dataset, #' units given in the `age_var+U` variable or `age_unit` argument and stores #' in a new variable (`new_var`). #' -#' @param dataset Input dataset. -#' -#' The column specified by the `age_var` argument is expected. +#' @param dataset +#' `r roxygen_param_dataset(expected_vars = c("age_var"))` #' #' @param age_var Age variable. #' diff --git a/R/derive_vars_dtm_to_dt.R b/R/derive_vars_dtm_to_dt.R index 7b1a74078d..a073a62adf 100644 --- a/R/derive_vars_dtm_to_dt.R +++ b/R/derive_vars_dtm_to_dt.R @@ -2,7 +2,8 @@ #' #' This function creates date(s) as output from datetime variable(s) #' -#' @param dataset Input dataset +#' @param dataset +#' `r roxygen_param_dataset(expected_vars = c("source_vars"))` #' #' @param source_vars A list of datetime variables created using `exprs()` from #' which dates are to be extracted diff --git a/R/derive_vars_dtm_to_tm.R b/R/derive_vars_dtm_to_tm.R index 5a094b2fd1..8a4d64520b 100644 --- a/R/derive_vars_dtm_to_tm.R +++ b/R/derive_vars_dtm_to_tm.R @@ -2,7 +2,8 @@ #' #' This function creates time variable(s) as output from datetime variable(s) #' -#' @param dataset Input dataset +#' @param dataset +#' `r roxygen_param_dataset(expected_vars = c("source_vars"))` #' #' @param source_vars A list of datetime variables created using `exprs()` from #' which time is to be extracted diff --git a/R/derive_vars_duration.R b/R/derive_vars_duration.R index 2b46e4b6ae..3734b84cd4 100644 --- a/R/derive_vars_duration.R +++ b/R/derive_vars_duration.R @@ -3,10 +3,8 @@ #' Derives duration between two dates, specified by the variables present in #' input dataset e.g., duration of adverse events, relative day, age, ... #' -#' @param dataset Input dataset -#' -#' The variables specified by the `start_date` and the `end_date` parameter are -#' expected. +#' @param dataset +#' `r roxygen_param_dataset(expected_vars = c("start_date", "end_date"))` #' #' @param new_var Name of variable to create #' diff --git a/R/derive_vars_dy.R b/R/derive_vars_dy.R index e6d2d515f3..82de671881 100644 --- a/R/derive_vars_dy.R +++ b/R/derive_vars_dy.R @@ -3,10 +3,8 @@ #' Adds relative day variables (`--DY`) to the dataset, e.g., `ASTDY` and #' `AENDY`. #' -#' @param dataset Input dataset -#' -#' The columns specified by the `reference_date` and the `source_vars` -#' parameter are expected. +#' @param dataset +#' `r roxygen_param_dataset(expected_vars = c("reference_date", "source_vars"))` #' #' @param reference_date A date or date-time column, e.g., date of first treatment #' or date-time of last exposure to treatment. diff --git a/R/derive_vars_query.R b/R/derive_vars_query.R index 6604ccf9bd..ca9025f8d3 100644 --- a/R/derive_vars_query.R +++ b/R/derive_vars_query.R @@ -26,7 +26,7 @@ #' `GRPID`, `SCOPE`, and `SCOPEN` respectively, #' whenever not missing. #' -#' @param dataset Input dataset. +#' @param dataset `r roxygen_param_dataset()` #' #' @param dataset_queries A dataset containing required columns `PREFIX`, #' `GRPNAME`, `SRCVAR`, `TERMNAME`, `TERMID`, and optional columns diff --git a/R/derive_vars_transposed.R b/R/derive_vars_transposed.R index 1ae95521b7..d91e32d2cf 100644 --- a/R/derive_vars_transposed.R +++ b/R/derive_vars_transposed.R @@ -2,9 +2,8 @@ #' #' Adds variables from a vertical dataset after transposing it into a wide one. #' -#' @param dataset Input dataset -#' -#' The variables specified by the `by_vars` parameter are required +#' @param dataset +#' `r roxygen_param_dataset(expected_vars = c("by_vars"))` #' #' @param dataset_merge Dataset to transpose and merge #' @@ -102,9 +101,8 @@ derive_vars_transposed <- function(dataset, #' #' **Note:** This is a wrapper function for the more generic `derive_vars_transposed()`. #' -#' @param dataset Input dataset -#' -#' The variables specified by the `by_vars` parameter are required +#' @param dataset +#' `r roxygen_param_dataset(expected_vars = c("by_vars"))` #' #' @param dataset_facm FACM dataset #' diff --git a/R/duplicates.R b/R/duplicates.R index 43a48e9feb..f4520d84fa 100644 --- a/R/duplicates.R +++ b/R/duplicates.R @@ -35,7 +35,7 @@ get_duplicates_dataset <- function() { #' Extract Duplicate Records #' -#' @param dataset A data frame +#' @param dataset `r roxygen_param_dataset(expected_vars = c("by_vars"))` #' @param by_vars A list of expressions created using `exprs()` identifying #' groups of records in which to look for duplicates #' @@ -78,7 +78,7 @@ extract_duplicate_records <- function(dataset, by_vars) { #' Signal Duplicate Records #' -#' @param dataset A data frame +#' @param dataset `r roxygen_param_dataset(expected_vars = c("by_vars"))` #' @param by_vars A list of expressions created using `exprs()` identifying #' groups of records in which to look for duplicates #' @param msg The condition message diff --git a/R/filter_exist.R b/R/filter_exist.R index b842b02a2a..17de6f306e 100644 --- a/R/filter_exist.R +++ b/R/filter_exist.R @@ -5,9 +5,7 @@ #' this could be used to return ADSL records for subjects that experienced a certain #' adverse event during the course of the study (as per records in ADAE). #' -#' @param dataset Input dataset -#' -#' The variables specified in the `by_vars` parameter are expected in this dataset. +#' @param dataset `r roxygen_param_dataset(expected_vars = c("by_vars"))` #' #' @param dataset_add Source dataset #' diff --git a/R/filter_extreme.R b/R/filter_extreme.R index 8dab991b4f..c08a60646e 100644 --- a/R/filter_extreme.R +++ b/R/filter_extreme.R @@ -2,10 +2,7 @@ #' #' Filters the first or last observation for each by group. #' -#' @param dataset Input dataset -#' -#' The variables specified by the `order` and the `by_vars` parameter are -#' expected. +#' @param dataset `r roxygen_param_dataset(expected_vars = c("by_vars", "order"))` #' #' @param by_vars Grouping variables #' diff --git a/R/filter_joined.R b/R/filter_joined.R index 1d85e6cfdb..d39e4d1ceb 100644 --- a/R/filter_joined.R +++ b/R/filter_joined.R @@ -16,10 +16,7 @@ #' response value can be confirmed by a subsequent assessment. This is commonly #' used in endpoints such as best overall response. #' -#' @param dataset Input dataset -#' -#' The variables specified for `by_vars`, `join_vars`, and `order` are -#' expected. +#' @param dataset `r roxygen_param_dataset(expected_vars = c("by_vars", "order", "join_vars"))` #' #' @param by_vars By variables #' diff --git a/R/filter_relative.R b/R/filter_relative.R index 34c57d796b..aa38420db8 100644 --- a/R/filter_relative.R +++ b/R/filter_relative.R @@ -5,10 +5,7 @@ #' called to select for each subject all observations before the first disease #' progression. #' -#' @param dataset Input dataset -#' -#' The variables specified by the `order` and the `by_vars` parameter are -#' expected. +#' @param dataset `r roxygen_param_dataset(expected_vars = c("by_vars", "order"))` #' #' @param by_vars Grouping variables #' diff --git a/R/get_summary_records.R b/R/get_summary_records.R index 52406841a8..c911a4afe7 100644 --- a/R/get_summary_records.R +++ b/R/get_summary_records.R @@ -11,7 +11,8 @@ #' to the original dataset observations. If you would like to this instead, #' see the `derive_summary_records()` function. #' -#' @param dataset A data frame. +#' @param dataset +#' `r roxygen_param_dataset(expected_vars = c("by_vars", "analysis_var"))` #' #' @param by_vars Variables to consider for generation of groupwise summary #' records. Providing the names of variables in [exprs()] will create a @@ -31,19 +32,35 @@ #' #' @param analysis_var Analysis variable. #' +#' `r lifecycle::badge("deprecated")` Please use `set_values_to` instead. +#' #' @param summary_fun Function that takes as an input the `analysis_var` and #' performs the calculation. +#' +#' `r lifecycle::badge("deprecated")` Please use `set_values_to` instead. +#' #' This can include built-in functions as well as user defined functions, #' for example `mean` or `function(x) mean(x, na.rm = TRUE)`. #' -#' @param set_values_to A list of variable name-value pairs. Use this argument -#' if you need to change the values of any newly derived records. +#' @param set_values_to Variables to be set #' -#' Set a list of variables to some specified value for the new observation(s) +#' The specified variables are set to the specified values for the new +#' observations. +#' +#' Set a list of variables to some specified value for the new records #' + LHS refer to a variable. -#' + RHS refers to the values to set to the variable. This can be a string, a symbol, a numeric -#' value, an expression or NA. -#' (e.g. `exprs(PARAMCD = "TDOSE",PARCAT1 = "OVERALL")`). +#' + RHS refers to the values to set to the variable. This can be a string, a +#' symbol, a numeric value, an expression or NA. If summary functions are +#' used, the values are summarized by the variables specified for `by_vars`. +#' +#' For example: +#' ``` +#' set_values_to = exprs( +#' AVAL = sum(AVAL), +#' PARAMCD = "TDOSE", +#' PARCAT1 = "OVERALL" +#' ) +#' ``` #' #' @return A data frame of derived records. #' @@ -51,88 +68,74 @@ #' #' @keywords der_gen #' -#' @seealso `derive_summary_records()` +#' @seealso [derive_summary_records()], [derive_var_merged_summary()] #' #' @export #' #' @examples #' library(tibble) -#' library(dplyr, warn.conflicts = FALSE) #' #' adeg <- tribble( -#' ~USUBJID, ~EGSEQ, ~PARAM, ~AVISIT, ~EGDTC, ~AVAL, ~TRTA, -#' "XYZ-1001", 1, "QTcF Int. (msec)", "Baseline", "2016-02-24T07:50", 385, "", -#' "XYZ-1001", 2, "QTcF Int. (msec)", "Baseline", "2016-02-24T07:52", 399, "", -#' "XYZ-1001", 3, "QTcF Int. (msec)", "Baseline", "2016-02-24T07:56", 396, "", -#' "XYZ-1001", 4, "QTcF Int. (msec)", "Visit 2", "2016-03-08T09:45", 384, "Placebo", -#' "XYZ-1001", 5, "QTcF Int. (msec)", "Visit 2", "2016-03-08T09:48", 393, "Placebo", -#' "XYZ-1001", 6, "QTcF Int. (msec)", "Visit 2", "2016-03-08T09:51", 388, "Placebo", -#' "XYZ-1001", 7, "QTcF Int. (msec)", "Visit 3", "2016-03-22T10:45", 385, "Placebo", -#' "XYZ-1001", 8, "QTcF Int. (msec)", "Visit 3", "2016-03-22T10:48", 394, "Placebo", -#' "XYZ-1001", 9, "QTcF Int. (msec)", "Visit 3", "2016-03-22T10:51", 402, "Placebo", -#' "XYZ-1002", 1, "QTcF Int. (msec)", "Baseline", "2016-02-22T07:58", 399, "", -#' "XYZ-1002", 2, "QTcF Int. (msec)", "Baseline", "2016-02-22T07:58", 410, "", -#' "XYZ-1002", 3, "QTcF Int. (msec)", "Baseline", "2016-02-22T08:01", 392, "", -#' "XYZ-1002", 4, "QTcF Int. (msec)", "Visit 2", "2016-03-06T09:50", 401, "Active 20mg", -#' "XYZ-1002", 5, "QTcF Int. (msec)", "Visit 2", "2016-03-06T09:53", 407, "Active 20mg", -#' "XYZ-1002", 6, "QTcF Int. (msec)", "Visit 2", "2016-03-06T09:56", 400, "Active 20mg", -#' "XYZ-1002", 7, "QTcF Int. (msec)", "Visit 3", "2016-03-24T10:50", 412, "Active 20mg", -#' "XYZ-1002", 8, "QTcF Int. (msec)", "Visit 3", "2016-03-24T10:53", 414, "Active 20mg", -#' "XYZ-1002", 9, "QTcF Int. (msec)", "Visit 3", "2016-03-24T10:56", 402, "Active 20mg", +#' ~USUBJID, ~EGSEQ, ~PARAM, ~AVISIT, ~EGDTC, ~AVAL, ~TRTA, +#' "XYZ-1001", 1, "QTcF Int. (msec)", "Baseline", "2016-02-24T07:50", 385, NA_character_, +#' "XYZ-1001", 2, "QTcF Int. (msec)", "Baseline", "2016-02-24T07:52", 399, NA_character_, +#' "XYZ-1001", 3, "QTcF Int. (msec)", "Baseline", "2016-02-24T07:56", 396, NA_character_, +#' "XYZ-1001", 4, "QTcF Int. (msec)", "Visit 2", "2016-03-08T09:45", 384, "Placebo", +#' "XYZ-1001", 5, "QTcF Int. (msec)", "Visit 2", "2016-03-08T09:48", 393, "Placebo", +#' "XYZ-1001", 6, "QTcF Int. (msec)", "Visit 2", "2016-03-08T09:51", 388, "Placebo", +#' "XYZ-1001", 7, "QTcF Int. (msec)", "Visit 3", "2016-03-22T10:45", 385, "Placebo", +#' "XYZ-1001", 8, "QTcF Int. (msec)", "Visit 3", "2016-03-22T10:48", 394, "Placebo", +#' "XYZ-1001", 9, "QTcF Int. (msec)", "Visit 3", "2016-03-22T10:51", 402, "Placebo", +#' "XYZ-1002", 1, "QTcF Int. (msec)", "Baseline", "2016-02-22T07:58", 399, NA_character_, +#' "XYZ-1002", 2, "QTcF Int. (msec)", "Baseline", "2016-02-22T07:58", 410, NA_character_, +#' "XYZ-1002", 3, "QTcF Int. (msec)", "Baseline", "2016-02-22T08:01", 392, NA_character_, +#' "XYZ-1002", 4, "QTcF Int. (msec)", "Visit 2", "2016-03-06T09:50", 401, "Active 20mg", +#' "XYZ-1002", 5, "QTcF Int. (msec)", "Visit 2", "2016-03-06T09:53", 407, "Active 20mg", +#' "XYZ-1002", 6, "QTcF Int. (msec)", "Visit 2", "2016-03-06T09:56", 400, "Active 20mg", +#' "XYZ-1002", 7, "QTcF Int. (msec)", "Visit 3", "2016-03-24T10:50", 412, "Active 20mg", +#' "XYZ-1002", 8, "QTcF Int. (msec)", "Visit 3", "2016-03-24T10:53", 414, "Active 20mg", +#' "XYZ-1002", 9, "QTcF Int. (msec)", "Visit 3", "2016-03-24T10:56", 402, "Active 20mg" #' ) #' #' # Summarize the average of the triplicate ECG interval values (AVAL) #' get_summary_records( #' adeg, #' by_vars = exprs(USUBJID, PARAM, AVISIT), -#' analysis_var = AVAL, -#' summary_fun = function(x) mean(x, na.rm = TRUE), -#' set_values_to = exprs(DTYPE = "AVERAGE") -#' ) -#' -#' advs <- tribble( -#' ~USUBJID, ~VSSEQ, ~PARAM, ~AVAL, ~VSSTRESU, ~VISIT, ~VSDTC, -#' "XYZ-001-001", 1164, "Weight", 99, "kg", "Screening", "2018-03-19", -#' "XYZ-001-001", 1165, "Weight", 101, "kg", "Run-In", "2018-03-26", -#' "XYZ-001-001", 1166, "Weight", 100, "kg", "Baseline", "2018-04-16", -#' "XYZ-001-001", 1167, "Weight", 94, "kg", "Week 24", "2018-09-30", -#' "XYZ-001-001", 1168, "Weight", 92, "kg", "Week 48", "2019-03-17", -#' "XYZ-001-001", 1169, "Weight", 95, "kg", "Week 52", "2019-04-14", +#' set_values_to = exprs( +#' AVAL = mean(AVAL, na.rm = TRUE), +#' DTYPE = "AVERAGE" +#' ) #' ) #' -#' # Set new values to any variable. Here, `DTYPE = MAXIMUM` refers to `max()` records -#' # and `DTYPE = AVERAGE` refers to `mean()` records. +#' # Derive more than one summary variable #' get_summary_records( -#' advs, -#' by_vars = exprs(USUBJID, PARAM), -#' analysis_var = AVAL, -#' summary_fun = max, -#' set_values_to = exprs(DTYPE = "MAXIMUM") -#' ) %>% -#' get_summary_records( -#' by_vars = exprs(USUBJID, PARAM), -#' analysis_var = AVAL, -#' summary_fun = mean, -#' set_values_to = exprs(DTYPE = "AVERAGE") +#' adeg, +#' by_vars = exprs(USUBJID, PARAM, AVISIT), +#' set_values_to = exprs( +#' AVAL = mean(AVAL), +#' ASTDTM = min(convert_dtc_to_dtm(EGDTC)), +#' AENDTM = max(convert_dtc_to_dtm(EGDTC)), +#' DTYPE = "AVERAGE" #' ) +#' ) #' #' # Sample ADEG dataset with triplicate record for only AVISIT = 'Baseline' #' adeg <- tribble( -#' ~USUBJID, ~EGSEQ, ~PARAM, ~AVISIT, ~EGDTC, ~AVAL, ~TRTA, -#' "XYZ-1001", 1, "QTcF Int. (msec)", "Baseline", "2016-02-24T07:50", 385, "", -#' "XYZ-1001", 2, "QTcF Int. (msec)", "Baseline", "2016-02-24T07:52", 399, "", -#' "XYZ-1001", 3, "QTcF Int. (msec)", "Baseline", "2016-02-24T07:56", 396, "", -#' "XYZ-1001", 4, "QTcF Int. (msec)", "Visit 2", "2016-03-08T09:48", 393, "Placebo", -#' "XYZ-1001", 5, "QTcF Int. (msec)", "Visit 2", "2016-03-08T09:51", 388, "Placebo", -#' "XYZ-1001", 6, "QTcF Int. (msec)", "Visit 3", "2016-03-22T10:48", 394, "Placebo", -#' "XYZ-1001", 7, "QTcF Int. (msec)", "Visit 3", "2016-03-22T10:51", 402, "Placebo", -#' "XYZ-1002", 1, "QTcF Int. (msec)", "Baseline", "2016-02-22T07:58", 399, "", -#' "XYZ-1002", 2, "QTcF Int. (msec)", "Baseline", "2016-02-22T07:58", 410, "", -#' "XYZ-1002", 3, "QTcF Int. (msec)", "Baseline", "2016-02-22T08:01", 392, "", -#' "XYZ-1002", 4, "QTcF Int. (msec)", "Visit 2", "2016-03-06T09:53", 407, "Active 20mg", -#' "XYZ-1002", 5, "QTcF Int. (msec)", "Visit 2", "2016-03-06T09:56", 400, "Active 20mg", -#' "XYZ-1002", 6, "QTcF Int. (msec)", "Visit 3", "2016-03-24T10:53", 414, "Active 20mg", -#' "XYZ-1002", 7, "QTcF Int. (msec)", "Visit 3", "2016-03-24T10:56", 402, "Active 20mg", +#' ~USUBJID, ~EGSEQ, ~PARAM, ~AVISIT, ~EGDTC, ~AVAL, ~TRTA, +#' "XYZ-1001", 1, "QTcF Int. (msec)", "Baseline", "2016-02-24T07:50", 385, NA_character_, +#' "XYZ-1001", 2, "QTcF Int. (msec)", "Baseline", "2016-02-24T07:52", 399, NA_character_, +#' "XYZ-1001", 3, "QTcF Int. (msec)", "Baseline", "2016-02-24T07:56", 396, NA_character_, +#' "XYZ-1001", 4, "QTcF Int. (msec)", "Visit 2", "2016-03-08T09:48", 393, "Placebo", +#' "XYZ-1001", 5, "QTcF Int. (msec)", "Visit 2", "2016-03-08T09:51", 388, "Placebo", +#' "XYZ-1001", 6, "QTcF Int. (msec)", "Visit 3", "2016-03-22T10:48", 394, "Placebo", +#' "XYZ-1001", 7, "QTcF Int. (msec)", "Visit 3", "2016-03-22T10:51", 402, "Placebo", +#' "XYZ-1002", 1, "QTcF Int. (msec)", "Baseline", "2016-02-22T07:58", 399, NA_character_, +#' "XYZ-1002", 2, "QTcF Int. (msec)", "Baseline", "2016-02-22T07:58", 410, NA_character_, +#' "XYZ-1002", 3, "QTcF Int. (msec)", "Baseline", "2016-02-22T08:01", 392, NA_character_, +#' "XYZ-1002", 4, "QTcF Int. (msec)", "Visit 2", "2016-03-06T09:53", 407, "Active 20mg", +#' "XYZ-1002", 5, "QTcF Int. (msec)", "Visit 2", "2016-03-06T09:56", 400, "Active 20mg", +#' "XYZ-1002", 6, "QTcF Int. (msec)", "Visit 3", "2016-03-24T10:53", 414, "Active 20mg", +#' "XYZ-1002", 7, "QTcF Int. (msec)", "Visit 3", "2016-03-24T10:56", 402, "Active 20mg" #' ) #' #' # Compute the average of AVAL only if there are more than 2 records within the @@ -141,32 +144,40 @@ #' adeg, #' by_vars = exprs(USUBJID, PARAM, AVISIT), #' filter = n() > 2, -#' analysis_var = AVAL, -#' summary_fun = function(x) mean(x, na.rm = TRUE), -#' set_values_to = exprs(DTYPE = "AVERAGE") +#' set_values_to = exprs( +#' AVAL = mean(AVAL, na.rm = TRUE), +#' DTYPE = "AVERAGE" +#' ) #' ) get_summary_records <- function(dataset, by_vars, filter = NULL, analysis_var, summary_fun, - set_values_to = NULL) { + set_values_to) { assert_vars(by_vars) - analysis_var <- assert_symbol(enexpr(analysis_var)) filter <- assert_filter_cond(enexpr(filter), optional = TRUE) - assert_s3_class(summary_fun, "function") assert_data_frame( dataset, - required_vars = expr_c(by_vars, analysis_var), + required_vars = by_vars, check_is_grouped = FALSE ) - assert_varval_list(set_values_to, optional = TRUE) + assert_varval_list(set_values_to) + if (!missing(analysis_var) || !missing(summary_fun)) { + deprecate_warn( + "1.0.0", + I("get_summary_records(anaylsis_var = , summary_fun = )"), + "get_summary_records(set_values_to = )" + ) + analysis_var <- assert_symbol(enexpr(analysis_var)) + assert_s3_class(summary_fun, "function") + set_values_to <- exprs(!!analysis_var := {{ summary_fun }}(!!analysis_var), !!!set_values_to) + } # Summarise the analysis value dataset %>% group_by(!!!by_vars) %>% filter_if(filter) %>% - summarise(!!analysis_var := summary_fun(!!analysis_var)) %>% - ungroup() %>% - process_set_values_to(set_values_to) + summarise(!!!set_values_to) %>% + ungroup() } diff --git a/R/period_dataset.R b/R/period_dataset.R index f16998e8ab..a57b330cf1 100644 --- a/R/period_dataset.R +++ b/R/period_dataset.R @@ -6,11 +6,10 @@ #' `APERIOD`, `APERSDT`, `APEREDT`, `TRTA`, `APHASEN`, `PHSDTM`, `PHEDTM`, ... #' in OCCDS and BDS datasets. #' -#' @param dataset ADSL dataset -#' -#' The variables specified by `new_vars` and `subject_keys` are expected. For -#' each element of `new_vars` at least one variable of the form of the right -#' hand side value must be available in the dataset. +#' @param dataset +#' `r roxygen_param_dataset(expected_vars = c("new_vars", "subject_keys"))` +#' For each element of `new_vars` at least one variable of the form of the right +#' hand side value must be available in the dataset. #' #' @param new_vars New variables #' @@ -232,9 +231,7 @@ create_period_dataset <- function(dataset, #' reference dataset which has one observations per patient and subperiod, #' period, or phase. #' -#' @param dataset ADSL dataset -#' -#' The variables specified by `subject_keys` are expected. +#' @param dataset `r roxygen_param_dataset(expected_vars = c("subject_keys"))` #' #' @param dataset_ref Period reference dataset #' diff --git a/R/restrict_derivation.R b/R/restrict_derivation.R index 7a5605e7b4..ac0d6d5657 100644 --- a/R/restrict_derivation.R +++ b/R/restrict_derivation.R @@ -2,7 +2,7 @@ #' #' Execute a derivation on a subset of the input dataset. #' -#' @param dataset Input dataset +#' @param dataset `r roxygen_param_dataset()` #' #' @param derivation Derivation #' diff --git a/R/roxygen2.R b/R/roxygen2.R new file mode 100644 index 0000000000..f37a44b158 --- /dev/null +++ b/R/roxygen2.R @@ -0,0 +1,16 @@ +# THIS FILE INCLUDES FUNCTION THAT ARE RE-USED THROUGHOUT +# roxygen2 COMMENTS TO GENERATE DOCUMENTATION TEXT + +roxygen_param_dataset <- function(expected_vars = NULL) { + if (is.null(expected_vars)) { + dataset_text <- "Input dataset" + } else { + dataset_text <- paste0( + "Input dataset \n \n", + "The variables specified by the ", + enumerate(expected_vars), + " argument(s) to be expected." + ) + } + return(dataset_text) +} diff --git a/R/slice_derivation.R b/R/slice_derivation.R index 2a4eb39056..c0c4a94ab7 100644 --- a/R/slice_derivation.R +++ b/R/slice_derivation.R @@ -4,7 +4,7 @@ #' derivation is called separately. Some or all arguments of the derivation #' may vary depending on the slice. #' -#' @param dataset Input dataset +#' @param dataset `r roxygen_param_dataset()` #' #' @param derivation Derivation #' diff --git a/README.md b/README.md index 4774a48cf0..b063a6f2c5 100644 --- a/README.md +++ b/README.md @@ -37,8 +37,8 @@ remotes::install_github("pharmaverse/admiral") The {admiral} family has several downstream and upstream dependencies and so this release shall be done in three Phases: -* Phase 1 release is for [{admiraldev}](https://pharmaverse.github.io/admiraldev/main/), [{pharmaversesdtm}](https://pharmaverse.github.io/pharmaversesdtm/main/), and [{admiral}](https://pharmaverse.github.io/admiral/cran-release/) core -* Phase 2 release is extension packages, e.g. [{admiralonco}](https://pharmaverse.github.io/admiralonco/main/), [{admiralophtha}](https://pharmaverse.github.io/admiralophtha/main/), [{admiralvaccine}](https://pharmaverse.github.io/admiralvaccine/main/) +* Phase 1 release is for [{admiraldev}](https://pharmaverse.github.io/admiraldev/), [{pharmaversesdtm}](https://pharmaverse.github.io/pharmaversesdtm/), and [{admiral}](https://pharmaverse.github.io/admiral/) core +* Phase 2 release is extension packages, e.g. [{admiralonco}](https://pharmaverse.github.io/admiralonco/), [{admiralophtha}](https://pharmaverse.github.io/admiralophtha/), [{admiralvaccine}](https://pharmaverse.github.io/admiralvaccine/) | Release Schedule | Phase 1- Date and Packages | Phase 2- Date and Packages | | ---------------- | ------------------------------------------------------------------------ | -------------------------------------------------------------------- | diff --git a/inst/templates/ad_adeg.R b/inst/templates/ad_adeg.R index 62a680a7da..a7e4d5d7b8 100644 --- a/inst/templates/ad_adeg.R +++ b/inst/templates/ad_adeg.R @@ -198,10 +198,11 @@ adeg <- adeg %>% adeg <- adeg %>% derive_summary_records( by_vars = exprs(STUDYID, USUBJID, !!!adsl_vars, PARAMCD, AVISITN, AVISIT, ADT), - analysis_var = AVAL, - summary_fun = function(x) mean(x, na.rm = TRUE), filter = dplyr::n() >= 2 & PARAMCD != "EGINTP", - set_values_to = exprs(DTYPE = "AVERAGE") + set_values_to = exprs( + AVAL = mean(AVAL, na.rm = TRUE), + DTYPE = "AVERAGE" + ) ) adeg <- adeg %>% diff --git a/inst/templates/ad_advs.R b/inst/templates/ad_advs.R index 1e43d8391d..fd630e2c47 100644 --- a/inst/templates/ad_advs.R +++ b/inst/templates/ad_advs.R @@ -158,9 +158,10 @@ advs <- advs %>% derive_summary_records( by_vars = exprs(STUDYID, USUBJID, !!!adsl_vars, PARAMCD, AVISITN, AVISIT, ADT, ADY), filter = !is.na(AVAL), - analysis_var = AVAL, - summary_fun = mean, - set_values_to = exprs(DTYPE = "AVERAGE") + set_values_to = exprs( + AVAL = mean(AVAL), + DTYPE = "AVERAGE" + ) ) advs <- advs %>% diff --git a/man/call_derivation.Rd b/man/call_derivation.Rd index 313cef60c5..79c795f5e9 100644 --- a/man/call_derivation.Rd +++ b/man/call_derivation.Rd @@ -7,7 +7,7 @@ call_derivation(dataset = NULL, derivation, variable_params, ...) } \arguments{ -\item{dataset}{The input dataset} +\item{dataset}{Input dataset} \item{derivation}{The derivation function to call diff --git a/man/create_period_dataset.Rd b/man/create_period_dataset.Rd index 8a6f99bf3f..64086f3002 100644 --- a/man/create_period_dataset.Rd +++ b/man/create_period_dataset.Rd @@ -11,10 +11,10 @@ create_period_dataset( ) } \arguments{ -\item{dataset}{ADSL dataset +\item{dataset}{Input dataset -The variables specified by \code{new_vars} and \code{subject_keys} are expected. For -each element of \code{new_vars} at least one variable of the form of the right +The variables specified by the \code{new_vars} and \code{subject_keys} argument(s) to be expected. +For each element of \code{new_vars} at least one variable of the form of the right hand side value must be available in the dataset.} \item{new_vars}{New variables diff --git a/man/create_single_dose_dataset.Rd b/man/create_single_dose_dataset.Rd index fc4e10c82d..70d314fd0d 100644 --- a/man/create_single_dose_dataset.Rd +++ b/man/create_single_dose_dataset.Rd @@ -21,8 +21,7 @@ create_single_dose_dataset( \arguments{ \item{dataset}{Input dataset -The columns specified by \code{dose_freq}, \code{start_date} and the \code{end_date} -parameters are expected.} +The variables specified by the \code{dose_freq}, \code{start_date} and \code{end_date} argument(s) to be expected.} \item{dose_freq}{The dose frequency diff --git a/man/derive_basetype_records.Rd b/man/derive_basetype_records.Rd index 44b88473c3..1bc0d42fa1 100644 --- a/man/derive_basetype_records.Rd +++ b/man/derive_basetype_records.Rd @@ -9,7 +9,7 @@ derive_basetype_records(dataset, basetypes) \arguments{ \item{dataset}{Input dataset -The columns specified in the expressions inside \code{basetypes} are required.} +The variables specified by the \code{basetypes} argument(s) to be expected.} \item{basetypes}{A \emph{named} list of expressions created using the \code{rlang::exprs()} function diff --git a/man/derive_expected_records.Rd b/man/derive_expected_records.Rd index 146b48ff60..43bbe10b66 100644 --- a/man/derive_expected_records.Rd +++ b/man/derive_expected_records.Rd @@ -15,8 +15,7 @@ derive_expected_records( \arguments{ \item{dataset}{Input dataset -A data frame, the columns from \code{dataset_ref} and specified by the -\code{by_vars} parameter are expected.} +The variables specified by the \code{dataset_ref} and \code{by_vars} argument(s) to be expected.} \item{dataset_expected_obs}{\emph{Deprecated}, please use \code{dataset_ref} instead.} diff --git a/man/derive_extreme_event.Rd b/man/derive_extreme_event.Rd index 21b4e90564..e61c514891 100644 --- a/man/derive_extreme_event.Rd +++ b/man/derive_extreme_event.Rd @@ -20,8 +20,7 @@ derive_extreme_event( \arguments{ \item{dataset}{Input dataset -The variables specified by the \code{order} and the \code{by_vars} parameter are -expected.} +The variables specified by the \code{by_vars} and \code{order} argument(s) to be expected.} \item{by_vars}{Grouping variables @@ -85,12 +84,22 @@ by variables and the order. The specified variables are set to the specified values for the new observations. -A list of variable name-value pairs is expected. +Set a list of variables to some specified value for the new records \itemize{ -\item LHS refers to a variable. +\item LHS refer to a variable. \item RHS refers to the values to set to the variable. This can be a string, a -symbol, a numeric value, an expression, or \code{NA}, e.g., \code{exprs(PARAMCD = "TDOSE", PARCAT1 = "OVERALL")}. -}} +symbol, a numeric value, an expression or NA. If summary functions are +used, the values are summarized by the variables specified for \code{by_vars}. +} + +For example: + +\if{html}{\out{
}}\preformatted{ set_values_to = exprs( + AVAL = sum(AVAL), + PARAMCD = "TDOSE", + PARCAT1 = "OVERALL" + ) +}\if{html}{\out{
}}} \item{keep_source_vars}{Variables to keep from the source dataset diff --git a/man/derive_extreme_records.Rd b/man/derive_extreme_records.Rd index fb64ea4bb2..3063a5056f 100644 --- a/man/derive_extreme_records.Rd +++ b/man/derive_extreme_records.Rd @@ -117,12 +117,22 @@ automatically.} The specified variables are set to the specified values for the new observations. -A list of variable name-value pairs is expected. +Set a list of variables to some specified value for the new records \itemize{ -\item LHS refers to a variable. +\item LHS refer to a variable. \item RHS refers to the values to set to the variable. This can be a string, a -symbol, a numeric value, an expression, or \code{NA}, e.g., \code{exprs(PARAMCD = "TDOSE", PARCAT1 = "OVERALL")}. -}} +symbol, a numeric value, an expression or NA. If summary functions are +used, the values are summarized by the variables specified for \code{by_vars}. +} + +For example: + +\if{html}{\out{
}}\preformatted{ set_values_to = exprs( + AVAL = sum(AVAL), + PARAMCD = "TDOSE", + PARCAT1 = "OVERALL" + ) +}\if{html}{\out{
}}} } \value{ The input dataset with the first or last observation of each by group diff --git a/man/derive_locf_records.Rd b/man/derive_locf_records.Rd index 5f500aaf0b..dc8cb92d95 100644 --- a/man/derive_locf_records.Rd +++ b/man/derive_locf_records.Rd @@ -17,8 +17,7 @@ derive_locf_records( \arguments{ \item{dataset}{Input dataset -The columns specified by the \code{by_vars}, \code{analysis_var}, \code{order}, -\code{keep_vars} parameters are expected.} +The variables specified by the \code{by_vars}, \code{analysis_var}, \code{order} and \code{keep_vars} argument(s) to be expected.} \item{dataset_expected_obs}{\emph{Deprecated}, please use \code{dataset_ref} instead.} diff --git a/man/derive_param_bmi.Rd b/man/derive_param_bmi.Rd index 5674f1007c..ecca7410dc 100644 --- a/man/derive_param_bmi.Rd +++ b/man/derive_param_bmi.Rd @@ -18,8 +18,8 @@ derive_param_bmi( \arguments{ \item{dataset}{Input dataset -The variables specified by the \code{by_vars} parameter, \code{PARAMCD}, and -\code{AVAL} are expected. +The variables specified by the \code{by_vars} argument(s) to be expected. +\code{PARAMCD}, and \code{AVAL} are expected as well. The variable specified by \code{by_vars} and \code{PARAMCD} must be a unique key of the input dataset after restricting it by the filter condition (\code{filter} diff --git a/man/derive_param_bsa.Rd b/man/derive_param_bsa.Rd index 6295555c54..78a98814e6 100644 --- a/man/derive_param_bsa.Rd +++ b/man/derive_param_bsa.Rd @@ -19,8 +19,8 @@ derive_param_bsa( \arguments{ \item{dataset}{Input dataset -The variables specified by the \code{by_vars} parameter, \code{PARAMCD}, and -\code{AVAL} are expected. +The variables specified by the \code{by_vars} argument(s) to be expected. +\code{PARAMCD}, and \code{AVAL} are expected as well. The variable specified by \code{by_vars} and \code{PARAMCD} must be a unique key of the input dataset after restricting it by the filter condition (\code{filter} diff --git a/man/derive_param_computed.Rd b/man/derive_param_computed.Rd index 12cdf77ec6..88002805cb 100644 --- a/man/derive_param_computed.Rd +++ b/man/derive_param_computed.Rd @@ -21,7 +21,8 @@ derive_param_computed( \arguments{ \item{dataset}{Input dataset -The variables specified by the \code{by_vars} parameter are expected. +The variables specified by the \code{by_vars} argument(s) to be expected. +\code{PARAMCD} is expected as well. The variable specified by \code{by_vars} and \code{PARAMCD} must be a unique key of the input dataset after restricting it by the filter condition (\code{filter} diff --git a/man/derive_param_doseint.Rd b/man/derive_param_doseint.Rd index f67b68afff..877ac7d3ad 100644 --- a/man/derive_param_doseint.Rd +++ b/man/derive_param_doseint.Rd @@ -17,8 +17,8 @@ derive_param_doseint( \arguments{ \item{dataset}{Input dataset -The variables specified by the \code{by_vars} parameter, \code{PARAMCD}, and -\code{AVAL} are expected. +The variables specified by the \code{by_vars} argument(s) to be expected. +\code{PARAMCD}, and \code{AVAL} are expected as well. The variable specified by \code{by_vars} and \code{PARAMCD} must be a unique key of the input dataset after restricting it by the filter condition (\code{filter} diff --git a/man/derive_param_exist_flag.Rd b/man/derive_param_exist_flag.Rd index 7431e6308d..f56fdbb032 100644 --- a/man/derive_param_exist_flag.Rd +++ b/man/derive_param_exist_flag.Rd @@ -20,8 +20,8 @@ derive_param_exist_flag( \arguments{ \item{dataset}{Input dataset -The variables specified for \code{by_vars} and the \code{PARAMCD} variable are -expected.} +The variables specified by the \code{by_vars} argument(s) to be expected. +\code{PARAMCD} is expected as well.} \item{dataset_ref}{Reference dataset, e.g., ADSL diff --git a/man/derive_param_exposure.Rd b/man/derive_param_exposure.Rd index 5f0d4fd0be..c946090150 100644 --- a/man/derive_param_exposure.Rd +++ b/man/derive_param_exposure.Rd @@ -16,9 +16,10 @@ derive_param_exposure( } \arguments{ \item{dataset}{Input dataset + +The variables specified by the \code{by_vars} and \code{analysis_var} argument(s) to be expected. +\code{PARAMCD} is expected as well, \itemize{ -\item The variables specified by the \code{by_vars},\code{analysis_var} parameters and \code{PARAMCD} are -expected, \item Either \code{ASTDTM} and \code{AENDTM} or \code{ASTDT} and \code{AENDT} are also expected. }} diff --git a/man/derive_param_framingham.Rd b/man/derive_param_framingham.Rd index 26a89ff1f7..8aec00eec6 100644 --- a/man/derive_param_framingham.Rd +++ b/man/derive_param_framingham.Rd @@ -24,8 +24,8 @@ derive_param_framingham( \arguments{ \item{dataset}{Input dataset -The variables specified by the \code{by_vars} parameter, \code{PARAMCD}, and -\code{AVAL} are expected. +The variables specified by the \code{by_vars} argument(s) to be expected. +\code{PARAMCD}, and \code{AVAL} are expected as well. The variable specified by \code{by_vars} and \code{PARAMCD} must be a unique key of the input dataset after restricting it by the filter condition (\code{filter} diff --git a/man/derive_param_map.Rd b/man/derive_param_map.Rd index 93b412d356..472e26bd56 100644 --- a/man/derive_param_map.Rd +++ b/man/derive_param_map.Rd @@ -18,8 +18,8 @@ derive_param_map( \arguments{ \item{dataset}{Input dataset -The variables specified by the \code{by_vars} parameter, \code{PARAMCD}, and -\code{AVAL} are expected. +The variables specified by the \code{by_vars} argument(s) to be expected. +\code{PARAMCD}, and \code{AVAL} are expected as well. The variable specified by \code{by_vars} and \code{PARAMCD} must be a unique key of the input dataset after restricting it by the filter condition (\code{filter} diff --git a/man/derive_param_qtc.Rd b/man/derive_param_qtc.Rd index 512945e8b0..594b7b1cd3 100644 --- a/man/derive_param_qtc.Rd +++ b/man/derive_param_qtc.Rd @@ -18,8 +18,8 @@ derive_param_qtc( \arguments{ \item{dataset}{Input dataset -The variables specified by the \code{by_vars} and the \code{unit_var} parameter, -\code{PARAMCD}, and \code{AVAL} are expected. +The variables specified by the \code{by_vars} and \code{get_unit_expr} argument(s) to be expected. +\code{PARAMCD}, and \code{AVAL} are expected as well. The variable specified by \code{by_vars} and \code{PARAMCD} must be a unique key of the input dataset after restricting it by the filter condition (\code{filter} diff --git a/man/derive_param_rr.Rd b/man/derive_param_rr.Rd index f6ba8b9add..ddf944a837 100644 --- a/man/derive_param_rr.Rd +++ b/man/derive_param_rr.Rd @@ -16,8 +16,8 @@ derive_param_rr( \arguments{ \item{dataset}{Input dataset -The variables specified by the \code{by_vars} parameter, \code{PARAMCD}, and \code{AVAL} -are expected. +The variables specified by the \code{by_vars} argument(s) to be expected. +\code{PARAMCD}, and \code{AVAL} are expected as well. The variable specified by \code{by_vars} and \code{PARAMCD} must be a unique key of the input dataset after restricting it by the filter condition (\code{filter} diff --git a/man/derive_param_tte.Rd b/man/derive_param_tte.Rd index 4177cbf61f..dc17c2b7f7 100644 --- a/man/derive_param_tte.Rd +++ b/man/derive_param_tte.Rd @@ -19,8 +19,7 @@ derive_param_tte( } \arguments{ \item{dataset}{Input dataset - -The \code{PARAMCD} variable is expected.} +\code{PARAMCD} is expected.} \item{dataset_adsl}{ADSL input dataset diff --git a/man/derive_param_wbc_abs.Rd b/man/derive_param_wbc_abs.Rd index e2278299b9..15c8555dc6 100644 --- a/man/derive_param_wbc_abs.Rd +++ b/man/derive_param_wbc_abs.Rd @@ -18,8 +18,8 @@ derive_param_wbc_abs( \arguments{ \item{dataset}{Input dataset -The variables specified by the \code{by_vars} argument, \code{PARAMCD}, and \code{AVAL} -are expected to be present. +The variables specified by the \code{by_vars} argument(s) to be expected. +\code{PARAMCD}, and \code{AVAL} are expected as well. The variable specified by \code{by_vars} and \code{PARAMCD} must be a unique key of the input dataset, and to the parameters specified by \code{wbc_code} and \code{diff_code}.} diff --git a/man/derive_summary_records.Rd b/man/derive_summary_records.Rd index 05281d4767..eba2324687 100644 --- a/man/derive_summary_records.Rd +++ b/man/derive_summary_records.Rd @@ -10,11 +10,13 @@ derive_summary_records( filter = NULL, analysis_var, summary_fun, - set_values_to = NULL + set_values_to ) } \arguments{ -\item{dataset}{A data frame.} +\item{dataset}{Input dataset + +The variables specified by the \code{by_vars} and \code{analysis_var} argument(s) to be expected.} \item{by_vars}{Variables to consider for generation of groupwise summary records. Providing the names of variables in \code{\link[=exprs]{exprs()}} will create a @@ -33,10 +35,15 @@ values greater than mean of \code{AVAL} with in \code{by_vars}. than 2. }} -\item{analysis_var}{Analysis variable.} +\item{analysis_var}{Analysis variable. + +\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Please use \code{set_values_to} instead.} \item{summary_fun}{Function that takes as an input the \code{analysis_var} and performs the calculation. + +\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Please use \code{set_values_to} instead. + This can include built-in functions as well as user defined functions, for example \code{mean} or \code{function(x) mean(x, na.rm = TRUE)}.} @@ -45,12 +52,22 @@ for example \code{mean} or \code{function(x) mean(x, na.rm = TRUE)}.} The specified variables are set to the specified values for the new observations. -A list of variable name-value pairs is expected. +Set a list of variables to some specified value for the new records \itemize{ -\item LHS refers to a variable. +\item LHS refer to a variable. \item RHS refers to the values to set to the variable. This can be a string, a -symbol, a numeric value, an expression, or \code{NA}, e.g., \code{exprs(PARAMCD = "TDOSE", PARCAT1 = "OVERALL")}. -}} +symbol, a numeric value, an expression or NA. If summary functions are +used, the values are summarized by the variables specified for \code{by_vars}. +} + +For example: + +\if{html}{\out{
}}\preformatted{ set_values_to = exprs( + AVAL = sum(AVAL), + PARAMCD = "TDOSE", + PARCAT1 = "OVERALL" + ) +}\if{html}{\out{
}}} } \value{ A data frame with derived records appended to original dataset. @@ -68,82 +85,74 @@ will be set to \code{NA}. } \examples{ library(tibble) -library(dplyr, warn.conflicts = TRUE) +library(dplyr) adeg <- tribble( - ~USUBJID, ~EGSEQ, ~PARAM, ~AVISIT, ~EGDTC, ~AVAL, ~TRTA, - "XYZ-1001", 1, "QTcF Int. (msec)", "Baseline", "2016-02-24T07:50", 385, "", - "XYZ-1001", 2, "QTcF Int. (msec)", "Baseline", "2016-02-24T07:52", 399, "", - "XYZ-1001", 3, "QTcF Int. (msec)", "Baseline", "2016-02-24T07:56", 396, "", - "XYZ-1001", 4, "QTcF Int. (msec)", "Visit 2", "2016-03-08T09:45", 384, "Placebo", - "XYZ-1001", 5, "QTcF Int. (msec)", "Visit 2", "2016-03-08T09:48", 393, "Placebo", - "XYZ-1001", 6, "QTcF Int. (msec)", "Visit 2", "2016-03-08T09:51", 388, "Placebo", - "XYZ-1001", 7, "QTcF Int. (msec)", "Visit 3", "2016-03-22T10:45", 385, "Placebo", - "XYZ-1001", 8, "QTcF Int. (msec)", "Visit 3", "2016-03-22T10:48", 394, "Placebo", - "XYZ-1001", 9, "QTcF Int. (msec)", "Visit 3", "2016-03-22T10:51", 402, "Placebo", - "XYZ-1002", 1, "QTcF Int. (msec)", "Baseline", "2016-02-22T07:58", 399, "", - "XYZ-1002", 2, "QTcF Int. (msec)", "Baseline", "2016-02-22T07:58", 410, "", - "XYZ-1002", 3, "QTcF Int. (msec)", "Baseline", "2016-02-22T08:01", 392, "", - "XYZ-1002", 4, "QTcF Int. (msec)", "Visit 2", "2016-03-06T09:50", 401, "Active 20mg", - "XYZ-1002", 5, "QTcF Int. (msec)", "Visit 2", "2016-03-06T09:53", 407, "Active 20mg", - "XYZ-1002", 6, "QTcF Int. (msec)", "Visit 2", "2016-03-06T09:56", 400, "Active 20mg", - "XYZ-1002", 7, "QTcF Int. (msec)", "Visit 3", "2016-03-24T10:50", 412, "Active 20mg", - "XYZ-1002", 8, "QTcF Int. (msec)", "Visit 3", "2016-03-24T10:53", 414, "Active 20mg", - "XYZ-1002", 9, "QTcF Int. (msec)", "Visit 3", "2016-03-24T10:56", 402, "Active 20mg", -) + ~USUBJID, ~EGSEQ, ~PARAM, ~AVISIT, ~EGDTC, ~AVAL, ~TRTA, + "XYZ-1001", 1, "QTcF Int. (msec)", "Baseline", "2016-02-24T07:50", 385, NA_character_, + "XYZ-1001", 2, "QTcF Int. (msec)", "Baseline", "2016-02-24T07:52", 399, NA_character_, + "XYZ-1001", 3, "QTcF Int. (msec)", "Baseline", "2016-02-24T07:56", 396, NA_character_, + "XYZ-1001", 4, "QTcF Int. (msec)", "Visit 2", "2016-03-08T09:45", 384, "Placebo", + "XYZ-1001", 5, "QTcF Int. (msec)", "Visit 2", "2016-03-08T09:48", 393, "Placebo", + "XYZ-1001", 6, "QTcF Int. (msec)", "Visit 2", "2016-03-08T09:51", 388, "Placebo", + "XYZ-1001", 7, "QTcF Int. (msec)", "Visit 3", "2016-03-22T10:45", 385, "Placebo", + "XYZ-1001", 8, "QTcF Int. (msec)", "Visit 3", "2016-03-22T10:48", 394, "Placebo", + "XYZ-1001", 9, "QTcF Int. (msec)", "Visit 3", "2016-03-22T10:51", 402, "Placebo", + "XYZ-1002", 1, "QTcF Int. (msec)", "Baseline", "2016-02-22T07:58", 399, NA_character_, + "XYZ-1002", 2, "QTcF Int. (msec)", "Baseline", "2016-02-22T07:58", 410, NA_character_, + "XYZ-1002", 3, "QTcF Int. (msec)", "Baseline", "2016-02-22T08:01", 392, NA_character_, + "XYZ-1002", 4, "QTcF Int. (msec)", "Visit 2", "2016-03-06T09:50", 401, "Active 20mg", + "XYZ-1002", 5, "QTcF Int. (msec)", "Visit 2", "2016-03-06T09:53", 407, "Active 20mg", + "XYZ-1002", 6, "QTcF Int. (msec)", "Visit 2", "2016-03-06T09:56", 400, "Active 20mg", + "XYZ-1002", 7, "QTcF Int. (msec)", "Visit 3", "2016-03-24T10:50", 412, "Active 20mg", + "XYZ-1002", 8, "QTcF Int. (msec)", "Visit 3", "2016-03-24T10:53", 414, "Active 20mg", + "XYZ-1002", 9, "QTcF Int. (msec)", "Visit 3", "2016-03-24T10:56", 402, "Active 20mg" +) \%>\% + mutate( + ADTM = convert_dtc_to_dtm(EGDTC) + ) # Summarize the average of the triplicate ECG interval values (AVAL) derive_summary_records( adeg, by_vars = exprs(USUBJID, PARAM, AVISIT), - analysis_var = AVAL, - summary_fun = function(x) mean(x, na.rm = TRUE), - set_values_to = exprs(DTYPE = "AVERAGE") -) - -advs <- tribble( - ~USUBJID, ~VSSEQ, ~PARAM, ~AVAL, ~VSSTRESU, ~VISIT, ~VSDTC, - "XYZ-001-001", 1164, "Weight", 99, "kg", "Screening", "2018-03-19", - "XYZ-001-001", 1165, "Weight", 101, "kg", "Run-In", "2018-03-26", - "XYZ-001-001", 1166, "Weight", 100, "kg", "Baseline", "2018-04-16", - "XYZ-001-001", 1167, "Weight", 94, "kg", "Week 24", "2018-09-30", - "XYZ-001-001", 1168, "Weight", 92, "kg", "Week 48", "2019-03-17", - "XYZ-001-001", 1169, "Weight", 95, "kg", "Week 52", "2019-04-14", -) + set_values_to = exprs( + AVAL = mean(AVAL, na.rm = TRUE), + DTYPE = "AVERAGE" + ) +) \%>\% + arrange(USUBJID, AVISIT) -# Set new values to any variable. Here, `DTYPE = MAXIMUM` refers to `max()` records -# and `DTYPE = AVERAGE` refers to `mean()` records. +# Derive more than one summary variable derive_summary_records( - advs, - by_vars = exprs(USUBJID, PARAM), - analysis_var = AVAL, - summary_fun = max, - set_values_to = exprs(DTYPE = "MAXIMUM") -) \%>\% - derive_summary_records( - by_vars = exprs(USUBJID, PARAM), - analysis_var = AVAL, - summary_fun = mean, - set_values_to = exprs(DTYPE = "AVERAGE") + adeg, + by_vars = exprs(USUBJID, PARAM, AVISIT), + set_values_to = exprs( + AVAL = mean(AVAL), + ADTM = max(ADTM), + DTYPE = "AVERAGE" ) +) \%>\% + arrange(USUBJID, AVISIT) \%>\% + select(-EGSEQ, -TRTA) # Sample ADEG dataset with triplicate record for only AVISIT = 'Baseline' adeg <- tribble( - ~USUBJID, ~EGSEQ, ~PARAM, ~AVISIT, ~EGDTC, ~AVAL, ~TRTA, - "XYZ-1001", 1, "QTcF Int. (msec)", "Baseline", "2016-02-24T07:50", 385, "", - "XYZ-1001", 2, "QTcF Int. (msec)", "Baseline", "2016-02-24T07:52", 399, "", - "XYZ-1001", 3, "QTcF Int. (msec)", "Baseline", "2016-02-24T07:56", 396, "", - "XYZ-1001", 4, "QTcF Int. (msec)", "Visit 2", "2016-03-08T09:48", 393, "Placebo", - "XYZ-1001", 5, "QTcF Int. (msec)", "Visit 2", "2016-03-08T09:51", 388, "Placebo", - "XYZ-1001", 6, "QTcF Int. (msec)", "Visit 3", "2016-03-22T10:48", 394, "Placebo", - "XYZ-1001", 7, "QTcF Int. (msec)", "Visit 3", "2016-03-22T10:51", 402, "Placebo", - "XYZ-1002", 1, "QTcF Int. (msec)", "Baseline", "2016-02-22T07:58", 399, "", - "XYZ-1002", 2, "QTcF Int. (msec)", "Baseline", "2016-02-22T07:58", 410, "", - "XYZ-1002", 3, "QTcF Int. (msec)", "Baseline", "2016-02-22T08:01", 392, "", - "XYZ-1002", 4, "QTcF Int. (msec)", "Visit 2", "2016-03-06T09:53", 407, "Active 20mg", - "XYZ-1002", 5, "QTcF Int. (msec)", "Visit 2", "2016-03-06T09:56", 400, "Active 20mg", - "XYZ-1002", 6, "QTcF Int. (msec)", "Visit 3", "2016-03-24T10:53", 414, "Active 20mg", - "XYZ-1002", 7, "QTcF Int. (msec)", "Visit 3", "2016-03-24T10:56", 402, "Active 20mg", + ~USUBJID, ~EGSEQ, ~PARAM, ~AVISIT, ~EGDTC, ~AVAL, ~TRTA, + "XYZ-1001", 1, "QTcF Int. (msec)", "Baseline", "2016-02-24T07:50", 385, NA_character_, + "XYZ-1001", 2, "QTcF Int. (msec)", "Baseline", "2016-02-24T07:52", 399, NA_character_, + "XYZ-1001", 3, "QTcF Int. (msec)", "Baseline", "2016-02-24T07:56", 396, NA_character_, + "XYZ-1001", 4, "QTcF Int. (msec)", "Visit 2", "2016-03-08T09:48", 393, "Placebo", + "XYZ-1001", 5, "QTcF Int. (msec)", "Visit 2", "2016-03-08T09:51", 388, "Placebo", + "XYZ-1001", 6, "QTcF Int. (msec)", "Visit 3", "2016-03-22T10:48", 394, "Placebo", + "XYZ-1001", 7, "QTcF Int. (msec)", "Visit 3", "2016-03-22T10:51", 402, "Placebo", + "XYZ-1002", 1, "QTcF Int. (msec)", "Baseline", "2016-02-22T07:58", 399, NA_character_, + "XYZ-1002", 2, "QTcF Int. (msec)", "Baseline", "2016-02-22T07:58", 410, NA_character_, + "XYZ-1002", 3, "QTcF Int. (msec)", "Baseline", "2016-02-22T08:01", 392, NA_character_, + "XYZ-1002", 4, "QTcF Int. (msec)", "Visit 2", "2016-03-06T09:53", 407, "Active 20mg", + "XYZ-1002", 5, "QTcF Int. (msec)", "Visit 2", "2016-03-06T09:56", 400, "Active 20mg", + "XYZ-1002", 6, "QTcF Int. (msec)", "Visit 3", "2016-03-24T10:53", 414, "Active 20mg", + "XYZ-1002", 7, "QTcF Int. (msec)", "Visit 3", "2016-03-24T10:56", 402, "Active 20mg" ) # Compute the average of AVAL only if there are more than 2 records within the @@ -152,13 +161,15 @@ derive_summary_records( adeg, by_vars = exprs(USUBJID, PARAM, AVISIT), filter = n() > 2, - analysis_var = AVAL, - summary_fun = function(x) mean(x, na.rm = TRUE), - set_values_to = exprs(DTYPE = "AVERAGE") -) + set_values_to = exprs( + AVAL = mean(AVAL, na.rm = TRUE), + DTYPE = "AVERAGE" + ) +) \%>\% + arrange(USUBJID, AVISIT) } \seealso{ -\code{get_summary_records()} +\code{\link[=get_summary_records]{get_summary_records()}}, \code{\link[=derive_var_merged_summary]{derive_var_merged_summary()}} BDS-Findings Functions for adding Parameters/Records: \code{\link{default_qtc_paramcd}()}, diff --git a/man/derive_var_age_years.Rd b/man/derive_var_age_years.Rd index cee141541c..2f0361f722 100644 --- a/man/derive_var_age_years.Rd +++ b/man/derive_var_age_years.Rd @@ -7,9 +7,9 @@ derive_var_age_years(dataset, age_var, age_unit = NULL, new_var) } \arguments{ -\item{dataset}{Input dataset. +\item{dataset}{Input dataset -The column specified by the \code{age_var} argument is expected.} +The variables specified by the \code{age_var} argument(s) to be expected.} \item{age_var}{Age variable. diff --git a/man/derive_var_analysis_ratio.Rd b/man/derive_var_analysis_ratio.Rd index 6272963e46..d7b3059558 100644 --- a/man/derive_var_analysis_ratio.Rd +++ b/man/derive_var_analysis_ratio.Rd @@ -7,7 +7,9 @@ derive_var_analysis_ratio(dataset, numer_var, denom_var, new_var = NULL) } \arguments{ -\item{dataset}{Input dataset} +\item{dataset}{Input dataset + +The variables specified by the \code{numer_var} and \code{denom_var} argument(s) to be expected.} \item{numer_var}{Variable containing numeric values to be used in the numerator of the ratio calculation.} diff --git a/man/derive_var_anrind.Rd b/man/derive_var_anrind.Rd index 6329f74bc4..b7a0999c7f 100644 --- a/man/derive_var_anrind.Rd +++ b/man/derive_var_anrind.Rd @@ -7,7 +7,9 @@ derive_var_anrind(dataset, use_a1hia1lo = FALSE) } \arguments{ -\item{dataset}{The input dataset} +\item{dataset}{Input dataset +\code{ANRLO}, \code{ANRHI}, and \code{AVAL} are expected and if \code{use_a1hia1lo} is set to \code{TRUE}, +\code{A1LO} and \code{A1H1} are expected as well.} \item{use_a1hia1lo}{A logical value indicating whether to use \code{A1H1} and \code{A1LO} in the derivation of \code{ANRIND}.} diff --git a/man/derive_var_atoxgr.Rd b/man/derive_var_atoxgr.Rd index dab904a4e0..66fc8051ad 100644 --- a/man/derive_var_atoxgr.Rd +++ b/man/derive_var_atoxgr.Rd @@ -11,10 +11,10 @@ derive_var_atoxgr( ) } \arguments{ -\item{dataset}{Input data set +\item{dataset}{Input dataset -The columns \code{ATOXGRL}, \code{ATOXGRH} and specified by \code{lotox_description_var}, -and \code{hitox_description_var} parameters are expected.} +The variables specified by the \code{lotox_description_var} and \code{hitox_description_var} argument(s) to be expected. +\code{ATOXGRL}, and \code{ATOXGRH} are expected as well.} \item{lotox_description_var}{Variable containing the toxicity grade description for low values, eg. "Anemia"} diff --git a/man/derive_var_atoxgr_dir.Rd b/man/derive_var_atoxgr_dir.Rd index ed8e9b40d3..d9b2d5719b 100644 --- a/man/derive_var_atoxgr_dir.Rd +++ b/man/derive_var_atoxgr_dir.Rd @@ -15,9 +15,9 @@ derive_var_atoxgr_dir( ) } \arguments{ -\item{dataset}{Input data set +\item{dataset}{Input dataset -The columns specified by \code{tox_description_var} parameter is expected.} +The variables specified by the \code{tox_description_var} argument(s) to be expected.} \item{new_var}{Name of the character grade variable to create, for example, \code{ATOXGRH} or \code{ATOXGRL}.} diff --git a/man/derive_var_base.Rd b/man/derive_var_base.Rd index 807057db36..aa4e90c893 100644 --- a/man/derive_var_base.Rd +++ b/man/derive_var_base.Rd @@ -13,7 +13,9 @@ derive_var_base( ) } \arguments{ -\item{dataset}{The input dataset} +\item{dataset}{Input dataset + +The variables specified by the \code{by_vars} and \code{source_var} argument(s) to be expected.} \item{by_vars}{Grouping variables uniquely identifying a set of records for which to calculate \code{new_var}} diff --git a/man/derive_var_chg.Rd b/man/derive_var_chg.Rd index 5a0b8de486..8a8df5a60b 100644 --- a/man/derive_var_chg.Rd +++ b/man/derive_var_chg.Rd @@ -7,8 +7,7 @@ derive_var_chg(dataset) } \arguments{ -\item{dataset}{The input dataset. Required variables are \code{AVAL} and -\code{BASE}.} +\item{dataset}{Input dataset \code{AVAL} and \code{BASE} are expected.} } \value{ The input dataset with an additional column named \code{CHG} diff --git a/man/derive_var_dthcaus.Rd b/man/derive_var_dthcaus.Rd index b94ba192d9..f4959dc96d 100644 --- a/man/derive_var_dthcaus.Rd +++ b/man/derive_var_dthcaus.Rd @@ -12,9 +12,9 @@ derive_var_dthcaus( ) } \arguments{ -\item{dataset}{Input dataset. +\item{dataset}{Input dataset -The variables specified by \code{subject_keys} are required.} +The variables specified by the \code{subject_keys} argument(s) to be expected.} \item{...}{Objects of class "dthcaus_source" created by \code{\link[=dthcaus_source]{dthcaus_source()}}.} diff --git a/man/derive_var_extreme_dt.Rd b/man/derive_var_extreme_dt.Rd index 33eca0f7de..e9052f35eb 100644 --- a/man/derive_var_extreme_dt.Rd +++ b/man/derive_var_extreme_dt.Rd @@ -16,7 +16,7 @@ derive_var_extreme_dt( \arguments{ \item{dataset}{Input dataset -The variables specified by \code{subject_keys} are required.} +The variables specified by the \code{subject_keys} argument(s) to be expected.} \item{new_var}{Name of variable to create} diff --git a/man/derive_var_extreme_dtm.Rd b/man/derive_var_extreme_dtm.Rd index 2a891d5d13..309e593770 100644 --- a/man/derive_var_extreme_dtm.Rd +++ b/man/derive_var_extreme_dtm.Rd @@ -16,7 +16,7 @@ derive_var_extreme_dtm( \arguments{ \item{dataset}{Input dataset -The variables specified by \code{subject_keys} are required.} +The variables specified by the \code{subject_keys} argument(s) to be expected.} \item{new_var}{Name of variable to create} diff --git a/man/derive_var_extreme_flag.Rd b/man/derive_var_extreme_flag.Rd index f96efd75c0..0375ef0309 100644 --- a/man/derive_var_extreme_flag.Rd +++ b/man/derive_var_extreme_flag.Rd @@ -19,7 +19,7 @@ derive_var_extreme_flag( \arguments{ \item{dataset}{Input dataset -The variables specified by the \code{by_vars} parameter are expected.} +The variables specified by the \code{by_vars} argument(s) to be expected.} \item{by_vars}{Grouping variables diff --git a/man/derive_var_joined_exist_flag.Rd b/man/derive_var_joined_exist_flag.Rd index 21321c43dd..b1f6f4455d 100644 --- a/man/derive_var_joined_exist_flag.Rd +++ b/man/derive_var_joined_exist_flag.Rd @@ -22,8 +22,7 @@ derive_var_joined_exist_flag( \arguments{ \item{dataset}{Input dataset -The variables specified by the \code{by_vars} and \code{join_vars} parameter are -expected.} +The variables specified by the \code{by_vars} and \code{join_vars} argument(s) to be expected.} \item{by_vars}{By variables diff --git a/man/derive_var_merged_exist_flag.Rd b/man/derive_var_merged_exist_flag.Rd index b86c0ef87b..ae0728a4bd 100644 --- a/man/derive_var_merged_exist_flag.Rd +++ b/man/derive_var_merged_exist_flag.Rd @@ -19,7 +19,7 @@ derive_var_merged_exist_flag( \arguments{ \item{dataset}{Input dataset -The variables specified by the \code{by_vars} argument are expected.} +The variables specified by the \code{by_vars} argument(s) to be expected.} \item{dataset_add}{Additional dataset diff --git a/man/derive_var_merged_summary.Rd b/man/derive_var_merged_summary.Rd index 5a7ff2fd0f..08220316cb 100644 --- a/man/derive_var_merged_summary.Rd +++ b/man/derive_var_merged_summary.Rd @@ -2,12 +2,13 @@ % Please edit documentation in R/derive_merged.R \name{derive_var_merged_summary} \alias{derive_var_merged_summary} -\title{Merge a Summary Variable} +\title{Merge Summary Variables} \usage{ derive_var_merged_summary( dataset, dataset_add, by_vars, + new_vars = NULL, new_var, filter_add = NULL, analysis_var, @@ -17,23 +18,45 @@ derive_var_merged_summary( \arguments{ \item{dataset}{Input dataset -The variables specified by the \code{by_vars} argument are expected.} +The variables specified by the \code{by_vars} argument(s) to be expected.} \item{dataset_add}{Additional dataset -The variables specified by the \code{by_vars} and the \code{analysis_var} arguments -are expected.} +The variables specified by the \code{by_vars} and the variables used on the left +hand sides of the \code{new_vars} arguments are expected.} \item{by_vars}{Grouping variables -The values of \code{analysis_var} are summarized by the specified variables. The -summarized values are merged to the input dataset (\code{dataset}) by the -specified by variables. +The expressions on the left hand sides of \code{new_vars} are evaluated by the +specified \emph{variables}. Then the resulting values are merged to the input +dataset (\code{dataset}) by the specified \emph{variables}. \emph{Permitted Values}: list of variables created by \code{exprs()}} +\item{new_vars}{New variables to add + +The specified variables are added to the input dataset. + +A named list of expressions is expected: +\itemize{ +\item LHS refer to a variable. +\item RHS refers to the values to set to the variable. This can be a string, a +symbol, a numeric value, an expression or NA. If summary functions are +used, the values are summarized by the variables specified for \code{by_vars}. +} + +For example: + +\if{html}{\out{
}}\preformatted{ new_vars = exprs( + DOSESUM = sum(AVAL), + DOSEMEAN = mean(AVAL) + ) +}\if{html}{\out{
}}} + \item{new_var}{Variable to add +\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Please use \code{new_vars} instead. + The specified variable is added to the input dataset (\code{dataset}) and set to the summarized values.} @@ -47,36 +70,37 @@ considered. \item{analysis_var}{Analysis variable +\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Please use \code{new_vars} instead. + The values of the specified variable are summarized by the function specified for \code{summary_fun}.} \item{summary_fun}{Summary function +\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Please use \code{new_vars} instead. + The specified function that takes as input \code{analysis_var} and performs the calculation. This can include built-in functions as well as user defined functions, for example \code{mean} or \code{function(x) mean(x, na.rm = TRUE)}.} } \value{ The output dataset contains all observations and variables of the -input dataset and additionally the variable specified for \code{new_var}. +input dataset and additionally the variables specified for \code{new_vars}. } \description{ Merge a summary variable from a dataset to the input dataset. - -\strong{Note:} This is a wrapper function for the more generic \code{derive_vars_merged}. } \details{ \enumerate{ \item The records from the additional dataset (\code{dataset_add}) are restricted to those matching the \code{filter_add} condition. -\item The values of the analysis variable (\code{analysis_var}) are summarized by -the summary function (\code{summary_fun}) for each by group (\code{by_vars}) in the -additional dataset (\code{dataset_add}). -\item The summarized values are merged to the input dataset as a new variable -(\code{new_var}). For observations without a matching observation in the -additional dataset the new variable is set to \code{NA}. Observations in the -additional dataset which have no matching observation in the input dataset -are ignored. +\item The new variables (\code{new_vars}) are created for each by group (\code{by_vars}) +in the additional dataset (\code{dataset_add}) by calling \code{summarize()}. I.e., +all observations of a by group are summarized to a single observation. +\item The new variables are merged to the input dataset. For observations +without a matching observation in the additional dataset the new variables +are set to \code{NA}. Observations in the additional dataset which have no +matching observation in the input dataset are ignored. } } \examples{ @@ -100,9 +124,10 @@ 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) + new_vars = exprs( + MEANVIS = mean(AVAL, na.rm = TRUE), + MAXVIS = max(AVAL, na.rm = TRUE) + ) ) # Add a variable listing the lesion ids at baseline @@ -134,9 +159,7 @@ derive_var_merged_summary( dataset_add = adtr, by_vars = exprs(USUBJID), filter_add = AVISIT == "BASELINE", - new_var = LESIONSBL, - analysis_var = LESIONID, - summary_fun = function(x) paste(x, collapse = ", ") + new_vars = exprs(LESIONSBL = paste(LESIONID, collapse = ", ")) ) } diff --git a/man/derive_var_obs_number.Rd b/man/derive_var_obs_number.Rd index f9fae3a7ee..d4c54e6881 100644 --- a/man/derive_var_obs_number.Rd +++ b/man/derive_var_obs_number.Rd @@ -15,8 +15,7 @@ derive_var_obs_number( \arguments{ \item{dataset}{Input dataset -The variables specified by the \code{order} and the \code{by_vars} parameter are -expected.} +The variables specified by the \code{by_vars} and \code{order} argument(s) to be expected.} \item{by_vars}{Grouping variables diff --git a/man/derive_var_ontrtfl.Rd b/man/derive_var_ontrtfl.Rd index be267b1b11..530c7c42a2 100644 --- a/man/derive_var_ontrtfl.Rd +++ b/man/derive_var_ontrtfl.Rd @@ -18,7 +18,7 @@ derive_var_ontrtfl( ) } \arguments{ -\item{dataset}{Input dataset. +\item{dataset}{Input dataset Required columns are \code{start_date}, \code{end_date}, \code{ref_start_date} and \code{ref_end_date}.} diff --git a/man/derive_var_pchg.Rd b/man/derive_var_pchg.Rd index 428950b05a..70b6749fcb 100644 --- a/man/derive_var_pchg.Rd +++ b/man/derive_var_pchg.Rd @@ -7,8 +7,8 @@ derive_var_pchg(dataset) } \arguments{ -\item{dataset}{The input dataset. Required variables are \code{AVAL} and -\code{BASE}.} +\item{dataset}{Input dataset +\code{AVAL} and \code{BASE} are expected.} } \value{ The input dataset with an additional column named \code{PCHG} diff --git a/man/derive_var_relative_flag.Rd b/man/derive_var_relative_flag.Rd index 9d07da3360..ac017c896d 100644 --- a/man/derive_var_relative_flag.Rd +++ b/man/derive_var_relative_flag.Rd @@ -20,8 +20,7 @@ derive_var_relative_flag( \arguments{ \item{dataset}{Input dataset -The variables specified by the \code{order} and the \code{by_vars} argument are -expected.} +The variables specified by the \code{by_vars} and \code{order} argument(s) to be expected.} \item{by_vars}{Grouping variables diff --git a/man/derive_var_shift.Rd b/man/derive_var_shift.Rd index ac4ff9fdfd..9a46f1e001 100644 --- a/man/derive_var_shift.Rd +++ b/man/derive_var_shift.Rd @@ -17,7 +17,7 @@ derive_var_shift( \arguments{ \item{dataset}{Input dataset -The columns specified by \code{from_var} and the \code{to_var} parameters are expected.} +The variables specified by the \code{from_var} and \code{to_var} argument(s) to be expected.} \item{new_var}{Name of the character shift variable to create.} diff --git a/man/derive_var_trtdurd.Rd b/man/derive_var_trtdurd.Rd index 81707b483b..940a28240e 100644 --- a/man/derive_var_trtdurd.Rd +++ b/man/derive_var_trtdurd.Rd @@ -9,8 +9,7 @@ derive_var_trtdurd(dataset, start_date = TRTSDT, end_date = TRTEDT) \arguments{ \item{dataset}{Input dataset -The columns specified by the \code{start_date} and the \code{end_date} parameter are -expected.} +The variables specified by the \code{start_date} and \code{end_date} argument(s) to be expected.} \item{start_date}{The start date diff --git a/man/derive_vars_aage.Rd b/man/derive_vars_aage.Rd index 189334d6ac..eebd490340 100644 --- a/man/derive_vars_aage.Rd +++ b/man/derive_vars_aage.Rd @@ -16,8 +16,7 @@ derive_vars_aage( \arguments{ \item{dataset}{Input dataset -The columns specified by the \code{start_date} and the \code{end_date} parameter are -expected.} +The variables specified by the \code{start_date} and \code{end_date} argument(s) to be expected.} \item{start_date}{The start date diff --git a/man/derive_vars_atc.Rd b/man/derive_vars_atc.Rd index 0f9e8f8bde..a289247569 100644 --- a/man/derive_vars_atc.Rd +++ b/man/derive_vars_atc.Rd @@ -14,7 +14,7 @@ derive_vars_atc( \arguments{ \item{dataset}{Input dataset -The variables specified by the \code{by_vars} parameter are required} +The variables specified by the \code{by_vars} argument(s) to be expected.} \item{dataset_facm}{FACM dataset diff --git a/man/derive_vars_dt.Rd b/man/derive_vars_dt.Rd index 176dc48bef..1dbc3fb6b4 100644 --- a/man/derive_vars_dt.Rd +++ b/man/derive_vars_dt.Rd @@ -17,9 +17,9 @@ derive_vars_dt( ) } \arguments{ -\item{dataset}{Input dataset. +\item{dataset}{Input dataset -The date character vector (\code{dtc}) must be present.} +The variables specified by the \code{dtc} argument(s) to be expected.} \item{new_vars_prefix}{Prefix used for the output variable(s). diff --git a/man/derive_vars_dtm.Rd b/man/derive_vars_dtm.Rd index 32ca6c207e..f8bbd4f8c0 100644 --- a/man/derive_vars_dtm.Rd +++ b/man/derive_vars_dtm.Rd @@ -21,7 +21,7 @@ derive_vars_dtm( \arguments{ \item{dataset}{Input dataset -The date character vector (\code{dtc}) must be present.} +The variables specified by the \code{dtc} argument(s) to be expected.} \item{new_vars_prefix}{Prefix used for the output variable(s). diff --git a/man/derive_vars_dtm_to_dt.Rd b/man/derive_vars_dtm_to_dt.Rd index 0efcdcb227..769f3f93fe 100644 --- a/man/derive_vars_dtm_to_dt.Rd +++ b/man/derive_vars_dtm_to_dt.Rd @@ -7,7 +7,9 @@ derive_vars_dtm_to_dt(dataset, source_vars) } \arguments{ -\item{dataset}{Input dataset} +\item{dataset}{Input dataset + +The variables specified by the \code{source_vars} argument(s) to be expected.} \item{source_vars}{A list of datetime variables created using \code{exprs()} from which dates are to be extracted} diff --git a/man/derive_vars_dtm_to_tm.Rd b/man/derive_vars_dtm_to_tm.Rd index 1f3c7be482..9d107f2f2c 100644 --- a/man/derive_vars_dtm_to_tm.Rd +++ b/man/derive_vars_dtm_to_tm.Rd @@ -7,7 +7,9 @@ derive_vars_dtm_to_tm(dataset, source_vars) } \arguments{ -\item{dataset}{Input dataset} +\item{dataset}{Input dataset + +The variables specified by the \code{source_vars} argument(s) to be expected.} \item{source_vars}{A list of datetime variables created using \code{exprs()} from which time is to be extracted} diff --git a/man/derive_vars_duration.Rd b/man/derive_vars_duration.Rd index 0dcee21daa..cb6676ab84 100644 --- a/man/derive_vars_duration.Rd +++ b/man/derive_vars_duration.Rd @@ -21,8 +21,7 @@ derive_vars_duration( \arguments{ \item{dataset}{Input dataset -The variables specified by the \code{start_date} and the \code{end_date} parameter are -expected.} +The variables specified by the \code{start_date} and \code{end_date} argument(s) to be expected.} \item{new_var}{Name of variable to create} diff --git a/man/derive_vars_dy.Rd b/man/derive_vars_dy.Rd index cc2de470cf..c0e3ddac4b 100644 --- a/man/derive_vars_dy.Rd +++ b/man/derive_vars_dy.Rd @@ -9,8 +9,7 @@ derive_vars_dy(dataset, reference_date, source_vars) \arguments{ \item{dataset}{Input dataset -The columns specified by the \code{reference_date} and the \code{source_vars} -parameter are expected.} +The variables specified by the \code{reference_date} and \code{source_vars} argument(s) to be expected.} \item{reference_date}{A date or date-time column, e.g., date of first treatment or date-time of last exposure to treatment. diff --git a/man/derive_vars_joined.Rd b/man/derive_vars_joined.Rd index 0073930145..1b3452d615 100644 --- a/man/derive_vars_joined.Rd +++ b/man/derive_vars_joined.Rd @@ -22,7 +22,7 @@ derive_vars_joined( \arguments{ \item{dataset}{Input dataset -The variables specified by \code{by_vars} are expected.} +The variables specified by the \code{by_vars} argument(s) to be expected.} \item{dataset_add}{Additional dataset diff --git a/man/derive_vars_merged.Rd b/man/derive_vars_merged.Rd index 528ae29337..2e04872e3c 100644 --- a/man/derive_vars_merged.Rd +++ b/man/derive_vars_merged.Rd @@ -25,7 +25,7 @@ derive_vars_merged( \arguments{ \item{dataset}{Input dataset -The variables specified by the \code{by_vars} argument are expected.} +The variables specified by the \code{by_vars} argument(s) to be expected.} \item{dataset_add}{Additional dataset diff --git a/man/derive_vars_merged_lookup.Rd b/man/derive_vars_merged_lookup.Rd index 80761151a2..3024d10083 100644 --- a/man/derive_vars_merged_lookup.Rd +++ b/man/derive_vars_merged_lookup.Rd @@ -20,7 +20,7 @@ derive_vars_merged_lookup( \arguments{ \item{dataset}{Input dataset -The variables specified by the \code{by_vars} argument are expected.} +The variables specified by the \code{by_vars} argument(s) to be expected.} \item{dataset_add}{Lookup table diff --git a/man/derive_vars_period.Rd b/man/derive_vars_period.Rd index 05dd4dc48b..2d00f227b3 100644 --- a/man/derive_vars_period.Rd +++ b/man/derive_vars_period.Rd @@ -12,9 +12,9 @@ derive_vars_period( ) } \arguments{ -\item{dataset}{ADSL dataset +\item{dataset}{Input dataset -The variables specified by \code{subject_keys} are expected.} +The variables specified by the \code{subject_keys} argument(s) to be expected.} \item{dataset_ref}{Period reference dataset diff --git a/man/derive_vars_query.Rd b/man/derive_vars_query.Rd index 16a91bd87c..33452967df 100644 --- a/man/derive_vars_query.Rd +++ b/man/derive_vars_query.Rd @@ -7,7 +7,7 @@ derive_vars_query(dataset, dataset_queries) } \arguments{ -\item{dataset}{Input dataset.} +\item{dataset}{Input dataset} \item{dataset_queries}{A dataset containing required columns \code{PREFIX}, \code{GRPNAME}, \code{SRCVAR}, \code{TERMNAME}, \code{TERMID}, and optional columns diff --git a/man/derive_vars_transposed.Rd b/man/derive_vars_transposed.Rd index effa25f80c..8195dd1166 100644 --- a/man/derive_vars_transposed.Rd +++ b/man/derive_vars_transposed.Rd @@ -16,7 +16,7 @@ derive_vars_transposed( \arguments{ \item{dataset}{Input dataset -The variables specified by the \code{by_vars} parameter are required} +The variables specified by the \code{by_vars} argument(s) to be expected.} \item{dataset_merge}{Dataset to transpose and merge diff --git a/man/extract_duplicate_records.Rd b/man/extract_duplicate_records.Rd index 6c29348703..3a1f4213e9 100644 --- a/man/extract_duplicate_records.Rd +++ b/man/extract_duplicate_records.Rd @@ -7,7 +7,9 @@ extract_duplicate_records(dataset, by_vars) } \arguments{ -\item{dataset}{A data frame} +\item{dataset}{Input dataset + +The variables specified by the \code{by_vars} argument(s) to be expected.} \item{by_vars}{A list of expressions created using \code{exprs()} identifying groups of records in which to look for duplicates} diff --git a/man/filter_exist.Rd b/man/filter_exist.Rd index 20697b3916..cc176c23ce 100644 --- a/man/filter_exist.Rd +++ b/man/filter_exist.Rd @@ -9,7 +9,7 @@ filter_exist(dataset, dataset_add, by_vars, filter_add = NULL) \arguments{ \item{dataset}{Input dataset -The variables specified in the \code{by_vars} parameter are expected in this dataset.} +The variables specified by the \code{by_vars} argument(s) to be expected.} \item{dataset_add}{Source dataset diff --git a/man/filter_extreme.Rd b/man/filter_extreme.Rd index 6842ff97e6..0e7d5bbc3b 100644 --- a/man/filter_extreme.Rd +++ b/man/filter_extreme.Rd @@ -9,8 +9,7 @@ filter_extreme(dataset, by_vars = NULL, order, mode, check_type = "warning") \arguments{ \item{dataset}{Input dataset -The variables specified by the \code{order} and the \code{by_vars} parameter are -expected.} +The variables specified by the \code{by_vars} and \code{order} argument(s) to be expected.} \item{by_vars}{Grouping variables diff --git a/man/filter_joined.Rd b/man/filter_joined.Rd index 8361945017..09c6b5f660 100644 --- a/man/filter_joined.Rd +++ b/man/filter_joined.Rd @@ -19,8 +19,7 @@ filter_joined( \arguments{ \item{dataset}{Input dataset -The variables specified for \code{by_vars}, \code{join_vars}, and \code{order} are -expected.} +The variables specified by the \code{by_vars}, \code{order} and \code{join_vars} argument(s) to be expected.} \item{by_vars}{By variables diff --git a/man/filter_not_exist.Rd b/man/filter_not_exist.Rd index ae8c3d1f0c..57f0065aff 100644 --- a/man/filter_not_exist.Rd +++ b/man/filter_not_exist.Rd @@ -9,7 +9,7 @@ filter_not_exist(dataset, dataset_add, by_vars, filter_add = NULL) \arguments{ \item{dataset}{Input dataset -The variables specified in the \code{by_vars} parameter are expected in this dataset.} +The variables specified by the \code{by_vars} argument(s) to be expected.} \item{dataset_add}{Source dataset diff --git a/man/filter_relative.Rd b/man/filter_relative.Rd index 220ce39caf..dd0f532da7 100644 --- a/man/filter_relative.Rd +++ b/man/filter_relative.Rd @@ -19,8 +19,7 @@ filter_relative( \arguments{ \item{dataset}{Input dataset -The variables specified by the \code{order} and the \code{by_vars} parameter are -expected.} +The variables specified by the \code{by_vars} and \code{order} argument(s) to be expected.} \item{by_vars}{Grouping variables diff --git a/man/get_hori_data.Rd b/man/get_hori_data.Rd index e416b453b9..9be797f41b 100644 --- a/man/get_hori_data.Rd +++ b/man/get_hori_data.Rd @@ -7,7 +7,9 @@ get_hori_data(dataset, by_vars, parameters, set_values_to, filter) } \arguments{ -\item{dataset}{Input dataset} +\item{dataset}{Input dataset + +The variables specified by the \code{by_vars} argument(s) to be expected.} \item{by_vars}{By variables} diff --git a/man/get_summary_records.Rd b/man/get_summary_records.Rd index ba0f3786d9..e63f9d477e 100644 --- a/man/get_summary_records.Rd +++ b/man/get_summary_records.Rd @@ -10,11 +10,13 @@ get_summary_records( filter = NULL, analysis_var, summary_fun, - set_values_to = NULL + set_values_to ) } \arguments{ -\item{dataset}{A data frame.} +\item{dataset}{Input dataset + +The variables specified by the \code{by_vars} and \code{analysis_var} argument(s) to be expected.} \item{by_vars}{Variables to consider for generation of groupwise summary records. Providing the names of variables in \code{\link[=exprs]{exprs()}} will create a @@ -33,23 +35,39 @@ values greater than mean of AVAL with in \code{by_vars}. than 2. }} -\item{analysis_var}{Analysis variable.} +\item{analysis_var}{Analysis variable. + +\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Please use \code{set_values_to} instead.} \item{summary_fun}{Function that takes as an input the \code{analysis_var} and performs the calculation. + +\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} Please use \code{set_values_to} instead. + This can include built-in functions as well as user defined functions, for example \code{mean} or \code{function(x) mean(x, na.rm = TRUE)}.} -\item{set_values_to}{A list of variable name-value pairs. Use this argument -if you need to change the values of any newly derived records. +\item{set_values_to}{Variables to be set + +The specified variables are set to the specified values for the new +observations. -Set a list of variables to some specified value for the new observation(s) +Set a list of variables to some specified value for the new records \itemize{ \item LHS refer to a variable. -\item RHS refers to the values to set to the variable. This can be a string, a symbol, a numeric -value, an expression or NA. -(e.g. \code{exprs(PARAMCD = "TDOSE",PARCAT1 = "OVERALL")}). -}} +\item RHS refers to the values to set to the variable. This can be a string, a +symbol, a numeric value, an expression or NA. If summary functions are +used, the values are summarized by the variables specified for \code{by_vars}. +} + +For example: + +\if{html}{\out{
}}\preformatted{ set_values_to = exprs( + AVAL = sum(AVAL), + PARAMCD = "TDOSE", + PARCAT1 = "OVERALL" + ) +}\if{html}{\out{
}}} } \value{ A data frame of derived records. @@ -67,82 +85,68 @@ see the \code{derive_summary_records()} function. } \examples{ library(tibble) -library(dplyr, warn.conflicts = FALSE) adeg <- tribble( - ~USUBJID, ~EGSEQ, ~PARAM, ~AVISIT, ~EGDTC, ~AVAL, ~TRTA, - "XYZ-1001", 1, "QTcF Int. (msec)", "Baseline", "2016-02-24T07:50", 385, "", - "XYZ-1001", 2, "QTcF Int. (msec)", "Baseline", "2016-02-24T07:52", 399, "", - "XYZ-1001", 3, "QTcF Int. (msec)", "Baseline", "2016-02-24T07:56", 396, "", - "XYZ-1001", 4, "QTcF Int. (msec)", "Visit 2", "2016-03-08T09:45", 384, "Placebo", - "XYZ-1001", 5, "QTcF Int. (msec)", "Visit 2", "2016-03-08T09:48", 393, "Placebo", - "XYZ-1001", 6, "QTcF Int. (msec)", "Visit 2", "2016-03-08T09:51", 388, "Placebo", - "XYZ-1001", 7, "QTcF Int. (msec)", "Visit 3", "2016-03-22T10:45", 385, "Placebo", - "XYZ-1001", 8, "QTcF Int. (msec)", "Visit 3", "2016-03-22T10:48", 394, "Placebo", - "XYZ-1001", 9, "QTcF Int. (msec)", "Visit 3", "2016-03-22T10:51", 402, "Placebo", - "XYZ-1002", 1, "QTcF Int. (msec)", "Baseline", "2016-02-22T07:58", 399, "", - "XYZ-1002", 2, "QTcF Int. (msec)", "Baseline", "2016-02-22T07:58", 410, "", - "XYZ-1002", 3, "QTcF Int. (msec)", "Baseline", "2016-02-22T08:01", 392, "", - "XYZ-1002", 4, "QTcF Int. (msec)", "Visit 2", "2016-03-06T09:50", 401, "Active 20mg", - "XYZ-1002", 5, "QTcF Int. (msec)", "Visit 2", "2016-03-06T09:53", 407, "Active 20mg", - "XYZ-1002", 6, "QTcF Int. (msec)", "Visit 2", "2016-03-06T09:56", 400, "Active 20mg", - "XYZ-1002", 7, "QTcF Int. (msec)", "Visit 3", "2016-03-24T10:50", 412, "Active 20mg", - "XYZ-1002", 8, "QTcF Int. (msec)", "Visit 3", "2016-03-24T10:53", 414, "Active 20mg", - "XYZ-1002", 9, "QTcF Int. (msec)", "Visit 3", "2016-03-24T10:56", 402, "Active 20mg", + ~USUBJID, ~EGSEQ, ~PARAM, ~AVISIT, ~EGDTC, ~AVAL, ~TRTA, + "XYZ-1001", 1, "QTcF Int. (msec)", "Baseline", "2016-02-24T07:50", 385, NA_character_, + "XYZ-1001", 2, "QTcF Int. (msec)", "Baseline", "2016-02-24T07:52", 399, NA_character_, + "XYZ-1001", 3, "QTcF Int. (msec)", "Baseline", "2016-02-24T07:56", 396, NA_character_, + "XYZ-1001", 4, "QTcF Int. (msec)", "Visit 2", "2016-03-08T09:45", 384, "Placebo", + "XYZ-1001", 5, "QTcF Int. (msec)", "Visit 2", "2016-03-08T09:48", 393, "Placebo", + "XYZ-1001", 6, "QTcF Int. (msec)", "Visit 2", "2016-03-08T09:51", 388, "Placebo", + "XYZ-1001", 7, "QTcF Int. (msec)", "Visit 3", "2016-03-22T10:45", 385, "Placebo", + "XYZ-1001", 8, "QTcF Int. (msec)", "Visit 3", "2016-03-22T10:48", 394, "Placebo", + "XYZ-1001", 9, "QTcF Int. (msec)", "Visit 3", "2016-03-22T10:51", 402, "Placebo", + "XYZ-1002", 1, "QTcF Int. (msec)", "Baseline", "2016-02-22T07:58", 399, NA_character_, + "XYZ-1002", 2, "QTcF Int. (msec)", "Baseline", "2016-02-22T07:58", 410, NA_character_, + "XYZ-1002", 3, "QTcF Int. (msec)", "Baseline", "2016-02-22T08:01", 392, NA_character_, + "XYZ-1002", 4, "QTcF Int. (msec)", "Visit 2", "2016-03-06T09:50", 401, "Active 20mg", + "XYZ-1002", 5, "QTcF Int. (msec)", "Visit 2", "2016-03-06T09:53", 407, "Active 20mg", + "XYZ-1002", 6, "QTcF Int. (msec)", "Visit 2", "2016-03-06T09:56", 400, "Active 20mg", + "XYZ-1002", 7, "QTcF Int. (msec)", "Visit 3", "2016-03-24T10:50", 412, "Active 20mg", + "XYZ-1002", 8, "QTcF Int. (msec)", "Visit 3", "2016-03-24T10:53", 414, "Active 20mg", + "XYZ-1002", 9, "QTcF Int. (msec)", "Visit 3", "2016-03-24T10:56", 402, "Active 20mg" ) # Summarize the average of the triplicate ECG interval values (AVAL) get_summary_records( adeg, by_vars = exprs(USUBJID, PARAM, AVISIT), - analysis_var = AVAL, - summary_fun = function(x) mean(x, na.rm = TRUE), - set_values_to = exprs(DTYPE = "AVERAGE") -) - -advs <- tribble( - ~USUBJID, ~VSSEQ, ~PARAM, ~AVAL, ~VSSTRESU, ~VISIT, ~VSDTC, - "XYZ-001-001", 1164, "Weight", 99, "kg", "Screening", "2018-03-19", - "XYZ-001-001", 1165, "Weight", 101, "kg", "Run-In", "2018-03-26", - "XYZ-001-001", 1166, "Weight", 100, "kg", "Baseline", "2018-04-16", - "XYZ-001-001", 1167, "Weight", 94, "kg", "Week 24", "2018-09-30", - "XYZ-001-001", 1168, "Weight", 92, "kg", "Week 48", "2019-03-17", - "XYZ-001-001", 1169, "Weight", 95, "kg", "Week 52", "2019-04-14", + set_values_to = exprs( + AVAL = mean(AVAL, na.rm = TRUE), + DTYPE = "AVERAGE" + ) ) -# Set new values to any variable. Here, `DTYPE = MAXIMUM` refers to `max()` records -# and `DTYPE = AVERAGE` refers to `mean()` records. +# Derive more than one summary variable get_summary_records( - advs, - by_vars = exprs(USUBJID, PARAM), - analysis_var = AVAL, - summary_fun = max, - set_values_to = exprs(DTYPE = "MAXIMUM") -) \%>\% - get_summary_records( - by_vars = exprs(USUBJID, PARAM), - analysis_var = AVAL, - summary_fun = mean, - set_values_to = exprs(DTYPE = "AVERAGE") + adeg, + by_vars = exprs(USUBJID, PARAM, AVISIT), + set_values_to = exprs( + AVAL = mean(AVAL), + ASTDTM = min(convert_dtc_to_dtm(EGDTC)), + AENDTM = max(convert_dtc_to_dtm(EGDTC)), + DTYPE = "AVERAGE" ) +) # Sample ADEG dataset with triplicate record for only AVISIT = 'Baseline' adeg <- tribble( - ~USUBJID, ~EGSEQ, ~PARAM, ~AVISIT, ~EGDTC, ~AVAL, ~TRTA, - "XYZ-1001", 1, "QTcF Int. (msec)", "Baseline", "2016-02-24T07:50", 385, "", - "XYZ-1001", 2, "QTcF Int. (msec)", "Baseline", "2016-02-24T07:52", 399, "", - "XYZ-1001", 3, "QTcF Int. (msec)", "Baseline", "2016-02-24T07:56", 396, "", - "XYZ-1001", 4, "QTcF Int. (msec)", "Visit 2", "2016-03-08T09:48", 393, "Placebo", - "XYZ-1001", 5, "QTcF Int. (msec)", "Visit 2", "2016-03-08T09:51", 388, "Placebo", - "XYZ-1001", 6, "QTcF Int. (msec)", "Visit 3", "2016-03-22T10:48", 394, "Placebo", - "XYZ-1001", 7, "QTcF Int. (msec)", "Visit 3", "2016-03-22T10:51", 402, "Placebo", - "XYZ-1002", 1, "QTcF Int. (msec)", "Baseline", "2016-02-22T07:58", 399, "", - "XYZ-1002", 2, "QTcF Int. (msec)", "Baseline", "2016-02-22T07:58", 410, "", - "XYZ-1002", 3, "QTcF Int. (msec)", "Baseline", "2016-02-22T08:01", 392, "", - "XYZ-1002", 4, "QTcF Int. (msec)", "Visit 2", "2016-03-06T09:53", 407, "Active 20mg", - "XYZ-1002", 5, "QTcF Int. (msec)", "Visit 2", "2016-03-06T09:56", 400, "Active 20mg", - "XYZ-1002", 6, "QTcF Int. (msec)", "Visit 3", "2016-03-24T10:53", 414, "Active 20mg", - "XYZ-1002", 7, "QTcF Int. (msec)", "Visit 3", "2016-03-24T10:56", 402, "Active 20mg", + ~USUBJID, ~EGSEQ, ~PARAM, ~AVISIT, ~EGDTC, ~AVAL, ~TRTA, + "XYZ-1001", 1, "QTcF Int. (msec)", "Baseline", "2016-02-24T07:50", 385, NA_character_, + "XYZ-1001", 2, "QTcF Int. (msec)", "Baseline", "2016-02-24T07:52", 399, NA_character_, + "XYZ-1001", 3, "QTcF Int. (msec)", "Baseline", "2016-02-24T07:56", 396, NA_character_, + "XYZ-1001", 4, "QTcF Int. (msec)", "Visit 2", "2016-03-08T09:48", 393, "Placebo", + "XYZ-1001", 5, "QTcF Int. (msec)", "Visit 2", "2016-03-08T09:51", 388, "Placebo", + "XYZ-1001", 6, "QTcF Int. (msec)", "Visit 3", "2016-03-22T10:48", 394, "Placebo", + "XYZ-1001", 7, "QTcF Int. (msec)", "Visit 3", "2016-03-22T10:51", 402, "Placebo", + "XYZ-1002", 1, "QTcF Int. (msec)", "Baseline", "2016-02-22T07:58", 399, NA_character_, + "XYZ-1002", 2, "QTcF Int. (msec)", "Baseline", "2016-02-22T07:58", 410, NA_character_, + "XYZ-1002", 3, "QTcF Int. (msec)", "Baseline", "2016-02-22T08:01", 392, NA_character_, + "XYZ-1002", 4, "QTcF Int. (msec)", "Visit 2", "2016-03-06T09:53", 407, "Active 20mg", + "XYZ-1002", 5, "QTcF Int. (msec)", "Visit 2", "2016-03-06T09:56", 400, "Active 20mg", + "XYZ-1002", 6, "QTcF Int. (msec)", "Visit 3", "2016-03-24T10:53", 414, "Active 20mg", + "XYZ-1002", 7, "QTcF Int. (msec)", "Visit 3", "2016-03-24T10:56", 402, "Active 20mg" ) # Compute the average of AVAL only if there are more than 2 records within the @@ -151,13 +155,14 @@ get_summary_records( adeg, by_vars = exprs(USUBJID, PARAM, AVISIT), filter = n() > 2, - analysis_var = AVAL, - summary_fun = function(x) mean(x, na.rm = TRUE), - set_values_to = exprs(DTYPE = "AVERAGE") + set_values_to = exprs( + AVAL = mean(AVAL, na.rm = TRUE), + DTYPE = "AVERAGE" + ) ) } \seealso{ -\code{derive_summary_records()} +\code{\link[=derive_summary_records]{derive_summary_records()}}, \code{\link[=derive_var_merged_summary]{derive_var_merged_summary()}} General Derivation Functions for all ADaMs that returns variable appended to dataset: \code{\link{derive_var_extreme_flag}()}, diff --git a/man/signal_duplicate_records.Rd b/man/signal_duplicate_records.Rd index 1076de7329..04e06cdb66 100644 --- a/man/signal_duplicate_records.Rd +++ b/man/signal_duplicate_records.Rd @@ -13,7 +13,9 @@ signal_duplicate_records( ) } \arguments{ -\item{dataset}{A data frame} +\item{dataset}{Input dataset + +The variables specified by the \code{by_vars} argument(s) to be expected.} \item{by_vars}{A list of expressions created using \code{exprs()} identifying groups of records in which to look for duplicates} diff --git a/renv/profiles/4.1/renv/settings.json b/renv/profiles/4.1/renv/settings.json index 4922677e15..0c8943c5c8 100644 --- a/renv/profiles/4.1/renv/settings.json +++ b/renv/profiles/4.1/renv/settings.json @@ -4,7 +4,6 @@ "ignored.packages": [ "admiral", "admiraldev", - "admiral.test", "admiralci", "pharmaversesdtm" ], diff --git a/renv/profiles/4.2/renv/settings.json b/renv/profiles/4.2/renv/settings.json index 4922677e15..0c8943c5c8 100644 --- a/renv/profiles/4.2/renv/settings.json +++ b/renv/profiles/4.2/renv/settings.json @@ -4,7 +4,6 @@ "ignored.packages": [ "admiral", "admiraldev", - "admiral.test", "admiralci", "pharmaversesdtm" ], diff --git a/renv/profiles/4.3/renv/settings.json b/renv/profiles/4.3/renv/settings.json index 4922677e15..0c8943c5c8 100644 --- a/renv/profiles/4.3/renv/settings.json +++ b/renv/profiles/4.3/renv/settings.json @@ -4,7 +4,6 @@ "ignored.packages": [ "admiral", "admiraldev", - "admiral.test", "admiralci", "pharmaversesdtm" ], diff --git a/renv/settings.json b/renv/settings.json index 3462f3b093..0c8943c5c8 100644 --- a/renv/settings.json +++ b/renv/settings.json @@ -4,8 +4,8 @@ "ignored.packages": [ "admiral", "admiraldev", - "admiral.test", - "admiralci" + "admiralci", + "pharmaversesdtm" ], "package.dependency.fields": [ "Imports", diff --git a/tests/testthat/test-call_derivation.R b/tests/testthat/test-call_derivation.R index 3fedf501fc..c5e9e10abc 100644 --- a/tests/testthat/test-call_derivation.R +++ b/tests/testthat/test-call_derivation.R @@ -6,23 +6,26 @@ test_that("call_derivation Test 1: Test that call_derivation generates expected expected_output <- input %>% derive_summary_records( by_vars = exprs(USUBJID, VSTESTCD), - analysis_var = VSSTRESN, - summary_fun = function(x) mean(x, na.rm = TRUE), - set_values_to = exprs(DTYPE = "AVERAGE"), + set_values_to = exprs( + VSSTRESN = mean(VSSTRESN, na.rm = TRUE), + DTYPE = "AVERAGE" + ), filter = dplyr::n() >= 2L ) %>% derive_summary_records( by_vars = exprs(USUBJID, VSTESTCD), - analysis_var = VSSTRESN, - summary_fun = function(x) max(x, na.rm = TRUE), - set_values_to = exprs(DTYPE = "MAXIMUM"), + set_values_to = exprs( + VSSTRESN = max(VSSTRESN, na.rm = TRUE), + DTYPE = "MAXIMUM" + ), filter = dplyr::n() >= 2L ) %>% derive_summary_records( by_vars = exprs(USUBJID, VSTESTCD), - analysis_var = VSSTRESN, - summary_fun = function(x) min(x, na.rm = TRUE), - set_values_to = exprs(DTYPE = "MINIMUM"), + set_values_to = exprs( + VSSTRESN = min(VSSTRESN, na.rm = TRUE), + DTYPE = "MINIMUM" + ), filter = dplyr::n() >= 2L ) @@ -31,20 +34,25 @@ test_that("call_derivation Test 1: Test that call_derivation generates expected derivation = derive_summary_records, variable_params = list( params( - summary_fun = function(x) mean(x, na.rm = TRUE), - set_values_to = exprs(DTYPE = "AVERAGE") + set_values_to = exprs( + VSSTRESN = mean(VSSTRESN, na.rm = TRUE), + DTYPE = "AVERAGE" + ) ), params( - summary_fun = function(x) max(x, na.rm = TRUE), - set_values_to = exprs(DTYPE = "MAXIMUM") + set_values_to = exprs( + VSSTRESN = max(VSSTRESN, na.rm = TRUE), + DTYPE = "MAXIMUM" + ) ), params( - summary_fun = function(x) min(x, na.rm = TRUE), - set_values_to = exprs(DTYPE = "MINIMUM") + set_values_to = exprs( + VSSTRESN = min(VSSTRESN, na.rm = TRUE), + DTYPE = "MINIMUM" + ) ) ), by_vars = exprs(USUBJID, VSTESTCD), - analysis_var = VSSTRESN, filter = dplyr::n() >= 2L ) diff --git a/tests/testthat/test-compute_scale.R b/tests/testthat/test-compute_scale.R index b4bb4dc6bb..afb20f819f 100644 --- a/tests/testthat/test-compute_scale.R +++ b/tests/testthat/test-compute_scale.R @@ -97,11 +97,10 @@ test_that("compute_scale Test 5: compute_scale() works as expected within input, by_vars = exprs(STUDYID, USUBJID, AVISIT, AVISITN), filter = (PARAMCD %in% c("ITEM1", "ITEM2", "ITEM3")), - analysis_var = AVAL, - summary_fun = function(x) { - compute_scale(x, c(1, 5), c(0, 100), flip_direction = TRUE, min_n = 3) - }, - set_values_to = exprs(PARAMCD = "ITEMAVG") + set_values_to = exprs( + AVAL = compute_scale(AVAL, c(1, 5), c(0, 100), flip_direction = TRUE, min_n = 3), + PARAMCD = "ITEMAVG" + ) ), expected_output ) diff --git a/tests/testthat/test-derive_merged.R b/tests/testthat/test-derive_merged.R index 1e3c921f7f..337a2fc3ef 100644 --- a/tests/testthat/test-derive_merged.R +++ b/tests/testthat/test-derive_merged.R @@ -493,9 +493,7 @@ test_that("derive_var_merged_summary Test 17: dataset == dataset_add, no filter" adbds, dataset_add = adbds, by_vars = exprs(AVISIT), - new_var = MEANVIS, - analysis_var = AVAL, - summary_fun = function(x) mean(x, na.rm = TRUE) + new_vars = exprs(MEANVIS = mean(AVAL, na.rm = TRUE)) ), keys = c("AVISIT", "ASEQ") ) @@ -526,10 +524,8 @@ test_that("derive_var_merged_summary Test 18: dataset != dataset_add, filter", { adsl, dataset_add = adbds, by_vars = exprs(USUBJID), - new_var = MEANPBL, - filter_add = ADY > 0, - analysis_var = AVAL, - summary_fun = function(x) mean(x, na.rm = TRUE) + new_vars = exprs(MEANPBL = mean(AVAL, na.rm = TRUE)), + filter_add = ADY > 0 ), keys = c("USUBJID") ) @@ -557,10 +553,41 @@ test_that("derive_var_merged_summary Test 19: by_vars with rename", { adbds, dataset_add = adbds1, by_vars = exprs(AVISIT = VISIT), + new_vars = exprs(MEANVIS = mean(AVAL, na.rm = TRUE)) + ), + keys = c("AVISIT", "ASEQ") + ) +}) + +test_that("derive_var_merged_summary Test 19: deprecation warning", { + expected <- tibble::tribble( + ~AVISIT, ~ASEQ, ~AVAL, ~MEANVIS, + "WEEK 1", 1, 10, 10, + "WEEK 1", 2, NA, 10, + "WEEK 2", 3, NA, NA, + "WEEK 3", 4, 42, 42, + "WEEK 4", 5, 12, 13, + "WEEK 4", 6, 12, 13, + "WEEK 4", 7, 15, 13 + ) + + adbds <- select(expected, -MEANVIS) + + expect_warning( + actual <- derive_var_merged_summary( + adbds, + dataset_add = adbds, + by_vars = exprs(AVISIT), new_var = MEANVIS, analysis_var = AVAL, summary_fun = function(x) mean(x, na.rm = TRUE) ), + class = "lifecycle_warning_deprecated" + ) + + expect_dfs_equal( + base = expected, + compare = actual, keys = c("AVISIT", "ASEQ") ) }) diff --git a/tests/testthat/test-derive_summary_records.R b/tests/testthat/test-derive_summary_records.R index b61b82790f..c7b26c927e 100644 --- a/tests/testthat/test-derive_summary_records.R +++ b/tests/testthat/test-derive_summary_records.R @@ -1,142 +1,92 @@ ## Test 1: creates new record per group and groups are retained ---- test_that("derive_summary_records Test 1: creates new record per group and groups are retained", { - # group --> 4 - input <- tibble::tibble(x = rep(1:4, each = 4), y = rep(1:2, each = 8), z = runif(16)) + input <- tibble::tribble( + ~subj, ~visit, ~val, ~seq, + "1", 1, 10, 1, + "1", 1, 14, 2, + "1", 1, 9, 3, + "1", 2, 11, 4, + "2", 2, NA_real_, 1 + ) + actual_output <- input %>% derive_summary_records( - by_vars = exprs(x, y), - analysis_var = z, - summary_fun = mean + by_vars = exprs(subj, visit), + set_values_to = exprs( + val = mean(val), + seq = max(seq), + type = "AVERAGE" + ) ) - expect_equal(nrow(actual_output), nrow(input) + 4) - expect_equal(dplyr::group_vars(actual_output), dplyr::group_vars(input)) -}) - -## Test 2: `fns` as inlined ---- -test_that("derive_summary_records Test 2: `fns` as inlined", { - input <- tibble::tibble(x = rep(1:2, each = 2), y = 9:12, z = 101:104) - actual_output <- derive_summary_records( + expected_output <- bind_rows( input, - by_vars = exprs(x), - analysis_var = y, - summary_fun = function(x) mean(x, na.rm = TRUE) - ) - expected_output <- tibble::tibble( - x = rep(1:2, each = 3), - y = c(9:10, 9.5, 11:12, 11.5), - z = c(101:102, NA, 103:104, NA) + tibble::tribble( + ~subj, ~visit, ~val, ~seq, + "1", 1, 11, 3, + "1", 2, 11, 4, + "2", 2, NA_real_, 1 + ) %>% + mutate(type = "AVERAGE") ) - expect_dfs_equal(actual_output, expected_output, keys = c("x", "y", "z")) -}) - -## Test 3: set new value to a derived record ---- -test_that("derive_summary_records Test 3: set new value to a derived record", { - input <- tibble::tibble(x = rep(1:2, each = 2), y = 9:12) - actual_output <- derive_summary_records( - input, - by_vars = exprs(x), - analysis_var = y, - summary_fun = mean, - set_values_to = exprs(z = "MEAN") - ) - expected_output <- tibble::tibble( - x = rep(1:2, each = 3), - y = c(9:10, 9.5, 11:12, 11.5), - z = c(NA, NA, "MEAN", NA, NA, "MEAN") + expect_dfs_equal( + base = expected_output, + compare = actual_output, + keys = c("subj", "visit", "seq", "type") ) - - expect_dfs_equal(actual_output, expected_output, keys = c("x", "y", "z")) }) -## Test 4: check `set_values_to` mapping ---- -test_that("derive_summary_records Test 4: check `set_values_to` mapping", { - input <- tibble::tibble(x = rep(1:4, each = 4), y = rep(1:2, each = 8), z = runif(16)) - actual_output <- input %>% - derive_summary_records( - by_vars = exprs(x, y), - analysis_var = z, - summary_fun = mean, - set_values_to = exprs(d = "MEAN") - ) %>% - derive_summary_records( - by_vars = exprs(x, y), - analysis_var = z, - summary_fun = sum, - set_values_to = exprs(d = "SUM") - ) - tf <- rep(c(NA, "MEAN", "SUM"), c(16, 4, 4)) - - expect_equal(actual_output$d, tf) +## Test 2: Filter record within `by_vars` ---- +test_that("derive_summary_records Test 2: Filter record within `by_vars`", { + input <- tibble::tribble( + ~subj, ~visit, ~val, ~seq, + "1", 1, 10, 1, + "1", 1, 14, 2, + "1", 1, 9, 3, + "1", 2, 11, 4, + "2", 2, NA_real_, 1 + ) actual_output <- input %>% derive_summary_records( - by_vars = exprs(x, y), - analysis_var = z, - summary_fun = mean, - set_values_to = exprs(d = "MEAN", p1 = "PARAM1", p2 = "PARAM2") + by_vars = exprs(subj, visit), + filter = n() > 2, + set_values_to = exprs( + val = mean(val), + seq = max(seq), + type = "AVERAGE" + ) ) - tf <- rep(c(NA, "MEAN"), c(16, 4)) - tp1 <- rep(c(NA, "PARAM1"), c(16, 4)) - tp2 <- rep(c(NA, "PARAM2"), c(16, 4)) - - expect_equal(actual_output$d, tf) - expect_equal(actual_output$p1, tp1) - expect_equal(actual_output$p2, tp2) -}) - -## Test 5: Filter record within `by_vars` ---- -test_that("derive_summary_records Test 5: Filter record within `by_vars`", { - input <- tibble::tibble(x = c(rep(1:2, each = 2), 2), y = 9:13, z = c(1, 1, 2, 1, 1)) - actual_output <- derive_summary_records( + expected_output <- bind_rows( input, - by_vars = exprs(x), - analysis_var = y, - summary_fun = mean, - filter = n() > 2, - set_values_to = exprs(d = "MEAN") - ) - expected_output <- tibble::tibble( - x = c(rep(1, 2), rep(2, 4)), - y = c(9:13, 12), - z = c(1, 1, 2, 1, 1, NA), - d = c(rep(NA, 5), "MEAN") + tibble::tribble( + ~subj, ~visit, ~val, ~seq, + "1", 1, 11, 3, + ) %>% + mutate(type = "AVERAGE") ) - expect_dfs_equal(actual_output, expected_output, keys = c("x", "y", "z")) - - actual_output <- derive_summary_records( - input, - by_vars = exprs(x), - analysis_var = y, - summary_fun = mean, - filter = z == 1, - set_values_to = exprs(d = "MEAN") - ) - expected_output <- tibble::tibble( - x = c(rep(1, 3), rep(2, 4)), - y = c(9:10, 9.5, 11:13, 12.5), - z = c(1, 1, NA, 2, 1, 1, NA), - d = c(rep(NA, 2), "MEAN", rep(NA, 3), "MEAN") + expect_dfs_equal( + base = expected_output, + compare = actual_output, + keys = c("subj", "visit", "seq", "type") ) - - expect_dfs_equal(actual_output, expected_output, keys = c("x", "y", "z")) }) - -## Test 6: Errors ---- -test_that("derive_summary_records Test 6: Errors", { +## Test 3: Errors ---- +test_that("derive_summary_records Test 3: Errors", { input <- tibble::tibble(x = rep(1:4, each = 4), y = rep(1:2, each = 8), z = runif(16)) - # Is by_vars quosures/`exprs()` object? + # Is by_vars `exprs()` object? expect_error( derive_summary_records( input, by_vars = "x", - analysis_var = z, - summary_fun = mean + set_values_to = exprs( + z = mean(z) + ) ), regexp = "`arg` must be an object of class 'list' but is `\"x\"`" ) @@ -146,34 +96,50 @@ test_that("derive_summary_records Test 6: Errors", { derive_summary_records( input, by_vars = exprs(a), - analysis_var = z, - summary_fun = mean + set_values_to = exprs( + z = mean(z) + ) ), regexp = "Required variable `a` is missing" ) +}) - # summary_fun must be a single function - expect_error( - derive_summary_records( - input, - by_vars = exprs(x), - analysis_var = y, - summary_fun = list(mean, sum) - ), - regexp = "`summary_fun` must be an object of class 'function' but is a list" +## Test 4: deprecation warning for analysis_var and summary_fun ---- +test_that("derive_summary_records Test 4: deprecation warning for analysis_var and summary_fun", { + input <- tibble::tribble( + ~subj, ~visit, ~val, ~seq, + "1", 1, 10, 1, + "1", 1, 14, 2, + "1", 1, 9, 3, + "1", 2, 11, 4, + "2", 2, NA_real_, 1 ) - # summary_fun must be a single function - expect_error( - derive_summary_records( - input, - by_vars = exprs(x), - analysis_var = z, - summary_fun = ~mean - ), - regexp = paste( - "`summary_fun` must be an object of class 'function'", - "but is an object of class 'formula'" - ) + expected_output <- bind_rows( + input, + tibble::tribble( + ~subj, ~visit, ~val, + "1", 1, 11, + "1", 2, 11, + "2", 2, NA_real_ + ) %>% + mutate(type = "AVERAGE") + ) + + expect_warning( + actual_output <- input %>% + derive_summary_records( + by_vars = exprs(subj, visit), + analysis_var = val, + summary_fun = mean, + set_values_to = exprs(type = "AVERAGE") + ), + class = "lifecycle_warning_deprecated" + ) + + expect_dfs_equal( + base = expected_output, + compare = actual_output, + keys = c("subj", "visit", "seq", "type") ) }) diff --git a/tests/testthat/test-roxygen2.R b/tests/testthat/test-roxygen2.R new file mode 100644 index 0000000000..a0b31eb094 --- /dev/null +++ b/tests/testthat/test-roxygen2.R @@ -0,0 +1,16 @@ +# roxygen_param_dataset ---- +## Test 1: Input dataset standardized text works ---- +test_that("roxygen_param_dataset Test 1: Input dataset standardized text works", { + expect_equal("Input dataset", roxygen_param_dataset(expected_vars = NULL)) +}) + +## Test 2: Input dataset standardized text works ---- +test_that("roxygen_param_dataset Test 2: Input dataset standardized text works", { + expect_equal( + paste0( + "Input dataset \n \n", + "The variables specified by the `by_vars` argument(s) to be expected." + ), + roxygen_param_dataset(expected_vars = c("by_vars")) + ) +}) diff --git a/vignettes/adsl.Rmd b/vignettes/adsl.Rmd index 00ff322785..0af1f414f0 100644 --- a/vignettes/adsl.Rmd +++ b/vignettes/adsl.Rmd @@ -751,7 +751,7 @@ The following functions are helpful for many ADSL derivations: - `derive_vars_merged()` - Merge Variables from a Dataset to the Input Dataset - `derive_var_merged_exist_flag()` - Merge an Existence Flag - - `derive_var_merged_summary()` - Merge a Summary Variable + - `derive_var_merged_summary()` - Merge Summary Variables See also [Generic Functions](generic.html). diff --git a/vignettes/bds_finding.Rmd b/vignettes/bds_finding.Rmd index ed8e715ece..20e2fbdf62 100644 --- a/vignettes/bds_finding.Rmd +++ b/vignettes/bds_finding.Rmd @@ -990,9 +990,10 @@ Set `DTYPE` to `AVERAGE`. advs_ex2 <- derive_summary_records( advs, by_vars = exprs(STUDYID, USUBJID, PARAMCD, VISITNUM, ADT), - analysis_var = AVAL, - summary_fun = mean, - set_values_to = exprs(DTYPE = "AVERAGE") + set_values_to = exprs( + AVAL = mean(AVAL), + DTYPE = "AVERAGE" + ) ) ``` diff --git a/vignettes/questionnaires.Rmd b/vignettes/questionnaires.Rmd index 242f42a0f5..12415d00ae 100644 --- a/vignettes/questionnaires.Rmd +++ b/vignettes/questionnaires.Rmd @@ -142,11 +142,10 @@ adgad7 <- adqs %>% filter(PARCAT1 == "GAD-7 V2") %>% derive_summary_records( by_vars = exprs(STUDYID, USUBJID, AVISIT, ADT, ADY, TRTSDT, DTHCAUS), - analysis_var = AVAL, - summary_fun = function(x) sum(x, na.rm = TRUE), # Select records contributing to total score filter = str_detect(PARAMCD, "GAD020[1-7]"), set_values_to = exprs( + AVAL = sum(AVAL, na.rm = TRUE), PARAMCD = "GAD02TS", PARAM = "GAD02-Total Score - Analysis" ) @@ -171,19 +170,16 @@ adgdssf <- adqs %>% filter(PARCAT1 == "GDS SHORT FORM") %>% derive_summary_records( by_vars = exprs(STUDYID, USUBJID, AVISIT, ADT, ADY, TRTSDT, DTHCAUS), - analysis_var = AVAL, - summary_fun = function(x) { - compute_scale( - x, + # Select records contributing to total score + filter = str_detect(PARAMCD, "GDS02[01][0-9]"), + set_values_to = exprs( + AVAL = compute_scale( + AVAL, source_range = c(0, 1), target_range = c(0, 15), min_n = 10 ) %>% - ceiling() - }, - # Select records contributing to total score - filter = str_detect(PARAMCD, "GDS02[01][0-9]"), - set_values_to = exprs( + ceiling(), PARAMCD = "GDS02TS", PARAM = "GDS02- Total Score - Analysis" ) @@ -523,9 +519,8 @@ adgdssf <- adgdssf %>% derive_summary_records( filter = str_detect(PARAMCD, "GDS02[01][0-9]"), by_vars = exprs(USUBJID, AVISIT), - analysis_var = AVAL, - summary_fun = function(x) sum(!is.na(x)) / 15 >= 0.9, set_values_to = exprs( + AVAL = sum(!is.na(AVAL)) / 15 >= 0.9, PARAMCD = "COMPL90P", PARAM = "Completed at least 90% of questions?", AVALC = if_else(AVAL == 1, "YES", "NO") @@ -573,9 +568,8 @@ adgdssf <- adgdssf %>% derive_summary_records( filter = str_detect(PARAMCD, "GDS02[01][0-9]"), by_vars = exprs(USUBJID, AVISIT), - analysis_var = AVAL, - summary_fun = function(x) all(!is.na(x)), set_values_to = exprs( + AVAL = all(!is.na(AVAL)), PARAMCD = "COMPLALL", PARAM = "Completed all questions?", AVALC = if_else(AVAL == 1, "YES", "NO")