From 52edc04f25a70ecfb4480f5fe0241c5147682965 Mon Sep 17 00:00:00 2001 From: Andrii Yurovskyi Date: Sun, 29 Sep 2024 00:46:36 +0200 Subject: [PATCH 01/28] (#31): wrapper functions for waist/hip and waist/height ratio --- DESCRIPTION | 3 +- NAMESPACE | 15 ++ R/admiralmetabolic-package.R | 7 +- R/derive_advs_params.R | 241 ++++++++++++++++++++++++++++ R/derive_bds_params.R | 236 +++++++++++++++++++++++++++ man/compute_ratio.Rd | 41 +++++ man/derive_param_ratio.Rd | 175 ++++++++++++++++++++ man/derive_param_waisthgt.Rd | 152 ++++++++++++++++++ man/derive_param_waisthip.Rd | 110 +++++++++++++ tests/testthat/test-compute_ratio.R | 39 +++++ 10 files changed, 1017 insertions(+), 2 deletions(-) create mode 100644 R/derive_advs_params.R create mode 100644 R/derive_bds_params.R create mode 100644 man/compute_ratio.Rd create mode 100644 man/derive_param_ratio.Rd create mode 100644 man/derive_param_waisthgt.Rd create mode 100644 man/derive_param_waisthip.Rd create mode 100644 tests/testthat/test-compute_ratio.R diff --git a/DESCRIPTION b/DESCRIPTION index 67fa74f..dbe32e3 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -30,7 +30,8 @@ Imports: lubridate (>= 1.7.4), magrittr (>= 1.5), rlang (>= 0.4.4), - tidyselect (>= 1.0.0) + tidyselect (>= 1.0.0), + checkmate Suggests: diffdf, DT, diff --git a/NAMESPACE b/NAMESPACE index 7c6e527..f52bb68 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -1,6 +1,20 @@ # Generated by roxygen2: do not edit by hand +export(compute_ratio) +export(derive_param_ratio) +export(derive_param_waisthgt) +export(derive_param_waisthip) export(hello_admiral) +importFrom(admiral,derive_param_computed) +importFrom(admiraldev,assert_character_scalar) +importFrom(admiraldev,assert_data_frame) +importFrom(admiraldev,assert_filter_cond) +importFrom(admiraldev,assert_logical_scalar) +importFrom(admiraldev,assert_numeric_vector) +importFrom(admiraldev,assert_param_does_not_exist) +importFrom(admiraldev,assert_vars) +importFrom(admiraldev,assert_varval_list) +importFrom(checkmate,assert_true) importFrom(dplyr,arrange) importFrom(dplyr,bind_cols) importFrom(dplyr,bind_rows) @@ -70,6 +84,7 @@ importFrom(rlang,eval_tidy) importFrom(rlang,expr) importFrom(rlang,expr_interp) importFrom(rlang,expr_label) +importFrom(rlang,exprs) importFrom(rlang,f_lhs) importFrom(rlang,f_rhs) importFrom(rlang,inform) diff --git a/R/admiralmetabolic-package.R b/R/admiralmetabolic-package.R index 233141f..19aef39 100644 --- a/R/admiralmetabolic-package.R +++ b/R/admiralmetabolic-package.R @@ -7,7 +7,7 @@ #' @importFrom magrittr %>% #' @importFrom rlang := abort arg_match as_function as_string call2 caller_env #' call_name current_env .data enexpr enquo eval_bare eval_tidy expr -#' expr_interp expr_label f_lhs f_rhs inform +#' exprs expr_interp expr_label f_lhs f_rhs inform #' is_bare_formula is_call is_character is_formula is_integerish #' is_logical is_quosure is_quosures is_symbol new_formula #' parse_expr parse_exprs quo quo_get_expr quo_is_call @@ -20,4 +20,9 @@ #' time_length %--% ymd ymd_hms weeks years hours minutes #' @importFrom tidyselect all_of contains vars_select #' @importFrom lifecycle deprecate_warn deprecated deprecate_stop +#' @importFrom checkmate assert_true +#' @importFrom admiraldev assert_numeric_vector assert_character_scalar assert_logical_scalar +#' assert_data_frame assert_vars assert_varval_list assert_filter_cond +#' assert_param_does_not_exist +#' @importFrom admiral derive_param_computed "_PACKAGE" diff --git a/R/derive_advs_params.R b/R/derive_advs_params.R new file mode 100644 index 0000000..9ec5a49 --- /dev/null +++ b/R/derive_advs_params.R @@ -0,0 +1,241 @@ +#' Adds a Parameter for Waist-to-Hip Ratio +#' +#' @description Adds a record for Waist-to-Hip Ratio using Waist Circumference and Hip Circumference each by group +#' (e.g., subject and visit) where the source parameters are available. +#' +#' **Note:** This is a wrapper function for the more generic \code{derive_param_ratio()}. +#' +#' @param dataset Input dataset +#' +#' The variables specified by the \code{by_vars} argument are expected to be in the dataset. +#' \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} +#' parameter) and to the parameters specified by \code{wstcir_code} and \code{hipcir_code}. +#' +#' @param wstcir_code Waist Circumference parameter code +#' +#' The observations where \code{PARAMCD} equals the specified value are considered +#' as the Waist Circumference +#' +#' *Permitted Values:* character value +#' +#' @param hipcir_code Hip Circumference parameter code +#' +#' The observations where \code{PARAMCD} equals the specified value are considered +#' as the Hip Circumference +#' +#' *Permitted Values:* character value +#' +#' @inheritParams derive_param_ratio +#' +#' @details +#' The analysis value of the new parameter is derived as +#' \deqn{WAISTHIP = \frac{WSTCIR}{HIPCIR}} +#' +#' +#' @return The input dataset with the new parameter added. Note, a variable will only +#' be populated in the new parameter rows if it is specified in \code{by_vars}. +#' +#' @export +#' +#' @seealso \code{\link[=derive_param_ratio]{derive_param_ratio()}}, \code{\link[=compute_ratio]{compute_ratio()}} +#' +#' @examples +#' +#' advs <- tribble( +#' ~USUBJID, ~PARAMCD, ~PARAM, ~AVAL, ~AVALU, ~VISIT, +#' "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 110, "cm", "SCREENING", +#' "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 108, "cm", "WEEK 2", +#' "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 107, "cm", "WEEK 3", +#' "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 125, "cm", "SCREENING", +#' "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 124, "cm", "WEEK 2", +#' "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 123, "cm", "WEEK 3", +#' "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 120, "cm", "SCREENING", +#' "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 118, "cm", "WEEK 2", +#' "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 117, "cm", "WEEK 3", +#' "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 135, "cm", "SCREENING", +#' "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 133, "cm", "WEEK 2", +#' "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 132, "cm", "WEEK 3" +#' ) +#' +#' derive_param_waisthip( +#' advs, +#' by_vars = exprs(USUBJID, VISIT), +#' wstcir_code = "WSTCIR", +#' hipcir_code = "HIPCIR", +#' set_values_to = exprs( +#' PARAMCD = "WAISTHIP", +#' PARAM = "Waist-to-Hip Ratio" +#' ) +#' ) + +derive_param_waisthip <- function(dataset, + by_vars, + wstcir_code = "WSTCIR", + hipcir_code = "HIPCIR", + set_values_to = exprs(PARAMCD = "WAISTHIP"), + filter = NULL) { + + assert_vars(by_vars) + assert_data_frame(dataset, required_vars = exprs(!!!by_vars, PARAMCD, AVAL)) + assert_character_scalar(wstcir_code) + assert_character_scalar(hipcir_code) + assert_varval_list(set_values_to, required_elements = "PARAMCD") + assert_param_does_not_exist(dataset, set_values_to$PARAMCD) + filter <- assert_filter_cond(enexpr(filter), optional = TRUE) + + derive_param_ratio( + dataset, + filter = !!filter, + dividend_code = wstcir_code, + divisor_code = hipcir_code, + by_vars = by_vars, + set_values_to = set_values_to + ) +} + +#' Adds a Parameter for Waist-to-Height Ratio +#' +#' @description Adds a record for Waist-to-Height Ratio using Waist Circumference and Height each by group +#' (e.g., subject and visit) where the source parameters are available. +#' +#' **Note:** This is a wrapper function for the more generic \code{derive_param_ratio()}. +#' +#' @param dataset Input dataset +#' +#' The variables specified by the \code{by_vars} argument are expected to be in the dataset. +#' \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} +#' parameter) and to the parameters specified by \code{wstcir_code} and \code{height_code}. +#' +#' @param wstcir_code Waist Circumference parameter code +#' +#' The observations where \code{PARAMCD} equals the specified value are considered +#' as the Waist Circumference +#' +#' *Permitted Values:* character value +#' +#' @param height_code Height parameter code +#' +#' The observations where \code{PARAMCD} equals the specified value are considered +#' as the Height. It is expected that Height is measured in cm +#' +#' *Permitted Values:* character value +#' +#' @param constant_by_vars By variables for when Height is constant +#' +#' When Height is constant, the Height parameters (measured only once) are merged +#' to the other parameters using the specified variables. +#' +#' If Height is constant (e.g. only measured once at screening or baseline) then +#' use \code{constant_by_vars} to select the subject-level variable to merge on (e.g. \code{USUBJID}). +#' This will produce Waist-to-Height Ratio at all visits where Waist Circumference is measured. +#' Otherwise it will only be calculated at visits with both Height and Waist Circumference collected. +#' +#' *Permitted Values*: list of variables created by \code{exprs()} +#' e.g. \code{exprs(USUBJID, VISIT)} +#' +#' @inheritParams derive_param_ratio +#' +#' @details +#' The analysis value of the new parameter is derived as +#' \deqn{WAISTHGT = \frac{WSTCIR}{HEIGHT}} +#' +#' +#' @return The input dataset with the new parameter added. Note, a variable will only +#' be populated in the new parameter rows if it is specified in \code{by_vars}. +#' +#' @export +#' +#' @seealso \code{\link[=derive_param_ratio]{derive_param_ratio()}}, \code{\link[=compute_ratio]{compute_ratio()}} +#' +#' @examples +#' +#' # Example 1: Derive Waist-to-Height Ratio where Height is measured only once +#' +#' advs <- tribble( +#' ~USUBJID, ~PARAMCD, ~PARAM, ~AVAL, ~AVALU, ~VISIT, +#' "01-101-1001", "HEIGHT", "Height (cm)", 147, "cm", "SCREENING", +#' "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 110, "cm", "SCREENING", +#' "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 108, "cm", "WEEK 2", +#' "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 107, "cm", "WEEK 3", +#' "01-101-1002", "HEIGHT", "Height (cm)", 163, "cm", "SCREENING", +#' "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 120, "cm", "SCREENING", +#' "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 118, "cm", "WEEK 2", +#' "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 117, "cm", "WEEK 3", +#' ) +#' +#' derive_param_waisthgt( +#' advs, +#' by_vars = exprs(USUBJID, VISIT), +#' wstcir_code = "WSTCIR", +#' height_code = "HEIGHT", +#' set_values_to = exprs( +#' PARAMCD = "WAISTHGT", +#' PARAM = "Waist-to-Height Ratio" +#' ), +#' constant_by_vars = exprs(USUBJID) +#' ) +#' +#' # Example 2: Pediatric study where Height and Waist Circumference are measured multiple times +#' +#' advs <- tribble( +#' ~USUBJID, ~PARAMCD, ~PARAM, ~AVAL, ~AVALU, ~VISIT, +#' "01-101-1001", "HEIGHT", "Height (cm)", 147, "cm", "SCREENING", +#' "01-101-1001", "HEIGHT", "Height (cm)", 148, "cm", "WEEK 2", +#' "01-101-1001", "HEIGHT", "Height (cm)", 149, "cm", "WEEK 3", +#' "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 100, "cm", "SCREENING", +#' "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 99, "cm", "WEEK 2", +#' "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 98, "cm", "WEEK 3", +#' "01-101-1002", "HEIGHT", "Height (cm)", 163, "cm", "SCREENING", +#' "01-101-1002", "HEIGHT", "Height (cm)", 164, "cm", "WEEK 2", +#' "01-101-1002", "HEIGHT", "Height (cm)", 165, "cm", "WEEK 3", +#' "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 110, "cm", "SCREENING", +#' "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 109, "cm", "WEEK 2", +#' "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 108, "cm", "WEEK 3" +#' ) +#' +#' derive_param_waisthgt( +#' advs, +#' by_vars = exprs(USUBJID, VISIT), +#' wstcir_code = "WSTCIR", +#' height_code = "HEIGHT", +#' set_values_to = exprs( +#' PARAMCD = "WAISTHGT", +#' PARAM = "Waist-to-Height Ratio" +#' ) +#' ) + +derive_param_waisthgt <- function(dataset, + by_vars, + wstcir_code = "WSTCIR", + height_code = "HGHT", + set_values_to = exprs(PARAMCD = "WAISTHGT"), + filter = NULL, + constant_by_vars = NULL) { + + assert_vars(by_vars) + assert_data_frame(dataset, required_vars = exprs(!!!by_vars, PARAMCD, AVAL)) + assert_character_scalar(wstcir_code) + assert_character_scalar(height_code) + assert_varval_list(set_values_to, required_elements = "PARAMCD") + assert_param_does_not_exist(dataset, set_values_to$PARAMCD) + filter <- assert_filter_cond(enexpr(filter), optional = TRUE) + assert_vars(constant_by_vars, optional = TRUE) + + derive_param_ratio( + dataset, + filter = !!filter, + dividend_code = wstcir_code, + divisor_code = height_code, + by_vars = by_vars, + set_values_to = set_values_to, + constant_dividend = FALSE, + constant_divisor = !is.null(constant_by_vars), + constant_by_vars = constant_by_vars + ) +} diff --git a/R/derive_bds_params.R b/R/derive_bds_params.R new file mode 100644 index 0000000..bdbc9b7 --- /dev/null +++ b/R/derive_bds_params.R @@ -0,0 +1,236 @@ +#' Adds a Ratio Parameter Computed from the Analysis Value of Other Parameters +#' +#' @description Adds a record for a generic Ratio parameter using two existing parameter +#' (dividend and divisor) each by group (e.g., subject and visit) where the source parameters are available. +#' +#' **Note:** This is a wrapper function for the more generic \code{admiral::derive_param_computed()}. +#' +#' @param dataset Input dataset +#' +#' The variables specified by the \code{by_vars} argument are expected to be in the dataset. +#' \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} +#' parameter) and to the parameters specified by \code{dividend_code} and \code{divisor_code}. +#' +#' @param dividend_code Dividend parameter code +#' +#' The observations where \code{PARAMCD} equals the specified value are considered +#' as the dividend +#' +#' *Permitted Values:* character value +#' +#' @param divisor_code Divisor parameter code +#' +#' The observations where \code{PARAMCD} equals the specified value are considered +#' as the divisor +#' +#' *Permitted Values:* character value +#' +#' @param constant_dividend Is dividend parameter constant? +#' +#' It is expected that the parameter code (PARAMCD) specified in \code{dividend_code} +#' which is required to derive the new parameter is measured only once. For example, +#' if Height-to-Weight Ratio should be derived and height is measured only once +#' while Weight is measured at each visit. Height could be specified +#' in the \code{dividend_code} argument and \code{constant_dividend} is to be set to \code{TRUE}. +#' +#' *Permitted Values:* logical scalar +#' +#' @param constant_divisor Is divisor parameter constant? +#' +#' It is expected that the parameter code (PARAMCD) specified in \code{dividend_code} +#' which is required to derive the new parameter is measured only once. For example, +#' if Waist-to-Height Ratio should be derived and height is measured only once +#' while Waist Circumference is measured at each visit. Height could be specified +#' in the \code{divisor_code} argument and \code{constant_divisor} is to be set to \code{TRUE}. +#' +#' *Permitted Values:* logical scalar +#' +#' @param constant_by_vars By variables for when dividend and/or divisor is constant +#' +#' When dividend and/or divisor is constant, the parameters (measured only once) are merged +#' to the other parameters using the specified variables. +#' +#' If dividend and/or divisor is constant (e.g. only measured once at screening or baseline) then +#' use \code{constant_by_vars} to select the subject-level variable to merge on (e.g. \code{USUBJID}). +#' This will produce a generic Ratio parameter at all visits where dividend and/or divisor is measured. +#' Otherwise it will only be calculated at visits with both dividend and divisor parameters collected. +#' +#' *Permitted Values*: list of variables created by \code{exprs()} +#' e.g. \code{exprs(USUBJID, VISIT)} +#' +#' @inheritParams admiral::derive_param_bmi +#' +#' @details +#' The analysis value of the new parameter is derived as +#' \deqn{RATIO = \frac{DIVIDENT}{DIVISOR}} +#' +#' +#' @return The input dataset with the new parameter added. Note, a variable will only +#' be populated in the new parameter rows if it is specified in \code{by_vars}. +#' +#' @export +#' +#' @seealso \code{\link[=compute_ratio]{compute_ratio()}} +#' +#' @examples +#' +#' # Example 1: Derive Waist-to-Hip Ratio where both source parameters are measured multiple times +#' +#' advs <- tribble( +#' ~USUBJID, ~PARAMCD, ~PARAM, ~AVAL, ~AVALU, ~VISIT, +#' "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 125, "cm", "SCREENING", +#' "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 124, "cm", "WEEK 2", +#' "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 123, "cm", "WEEK 3", +#' "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 110, "cm", "SCREENING", +#' "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 108, "cm", "WEEK 2", +#' "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 107, "cm", "WEEK 3", +#' "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 135, "cm", "SCREENING", +#' "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 133, "cm", "WEEK 2", +#' "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 132, "cm", "WEEK 3", +#' "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 120, "cm", "SCREENING", +#' "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 118, "cm", "WEEK 2", +#' "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 117, "cm", "WEEK 3" +#' ) +#' +#' derive_param_ratio( +#' advs, +#' by_vars = exprs(USUBJID, VISIT), +#' dividend_code = "WSTCIR", +#' divisor_code = "HIPCIR", +#' set_values_to = exprs( +#' PARAMCD = "WAISTHIP", +#' PARAM = "Waist-to-Hip Ratio" +#' ) +#' ) +#' +#' # Example 2: Derive Waist-to-Height Ratio where Height is measured only once +#' +#' advs <- tribble( +#' ~USUBJID, ~PARAMCD, ~PARAM, ~AVAL, ~AVALU, ~VISIT, +#' "01-101-1001", "HEIGHT", "Height (cm)", 147, "cm", "SCREENING", +#' "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 110, "cm", "SCREENING", +#' "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 108, "cm", "WEEK 2", +#' "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 107, "cm", "WEEK 3", +#' "01-101-1002", "HEIGHT", "Height (cm)", 163, "cm", "SCREENING", +#' "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 120, "cm", "SCREENING", +#' "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 118, "cm", "WEEK 2", +#' "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 117, "cm", "WEEK 3", +#' ) +#' +#' derive_param_ratio( +#' advs, +#' by_vars = exprs(USUBJID, VISIT), +#' dividend_code = "WSTCIR", +#' divisor_code = "HEIGHT", +#' set_values_to = exprs( +#' PARAMCD = "WAISTHGT", +#' PARAM = "Waist-to-Height Ratio" +#' ), +#' constant_divisor = TRUE, +#' constant_by_vars = exprs(USUBJID) +#' ) + +derive_param_ratio <- function(dataset, + by_vars, + dividend_code, + divisor_code, + set_values_to, + constant_dividend = FALSE, + constant_divisor = FALSE, + filter = NULL, + constant_by_vars = NULL) { + + assert_vars(by_vars) + assert_data_frame(dataset, required_vars = exprs(!!!by_vars, PARAMCD, AVAL)) + assert_character_scalar(dividend_code) + assert_character_scalar(divisor_code) + assert_varval_list(set_values_to, required_elements = "PARAMCD") + assert_param_does_not_exist(dataset, set_values_to$PARAMCD) + filter <- assert_filter_cond(enexpr(filter), optional = TRUE) + assert_logical_scalar(constant_dividend) + assert_logical_scalar(constant_divisor) + assert_vars(constant_by_vars, optional = TRUE) + + ratio_formula <- expr( + compute_ratio( + x = !!sym(paste0("AVAL.", dividend_code)), + y = !!sym(paste0("AVAL.", divisor_code)) + ) + ) + + parameters <- c(dividend_code, divisor_code) + constant_parameters <- NULL + + if (constant_dividend) { + constant_parameters <- c(constant_parameters, dividend_code) + + parameters <- parameters %>% + .[!. == dividend_code] + } + + if (constant_divisor) { + constant_parameters <- c(constant_parameters, divisor_code) + + parameters <- parameters %>% + .[!. == divisor_code] %>% + ifelse(length(.) == 0, NULL, .) + } + + derive_param_computed( + dataset, + filter = !!filter, + parameters = parameters, + by_vars = by_vars, + set_values_to = exprs( + AVAL = !!ratio_formula, + !!!set_values_to + ), + constant_parameters = constant_parameters, + constant_by_vars = constant_by_vars + ) +} + +#' Compute ratio +#' +#' Computes ratio as dividend (x) divided by divisor (y) +#' +#' @param x Dividend +#' +#' *Permitted Values:* numeric vector +#' +#' @param y Divisor +#' +#' *Permitted Values:* numeric vector +#' +#' +#' @details +#' \code{x} and \code{y} must be of the same length. +#' +#' If the divisor equals 0, the result will be NA. +#' +#' Usually this computation function can not be used with \code{%>%}. +#' +#' @return The ratio computed as x / y. +#' +#' @export +#' +#' @seealso \code{\link[=derive_param_ratio]{derive_param_ratio()}}, \code{\link[=derive_param_waisthip]{derive_param_waisthip()}}, \code{\link[=derive_param_waisthgt]{derive_param_waisthgt()}} +#' +#' @examples +#' +#' # Example of Waist-to-Height Ratio where +#' # Waist Circumference is 120 cm +#' # and Height is 163 cm +#' +#' compute_ratio(x = 120, y = 163) + +compute_ratio <- function(x, y) { + assert_numeric_vector(x) + assert_numeric_vector(y) + assert_true(length(x) == length(y)) + + if_else(y == 0, NA_real_, x / y) +} diff --git a/man/compute_ratio.Rd b/man/compute_ratio.Rd new file mode 100644 index 0000000..ce9ce2c --- /dev/null +++ b/man/compute_ratio.Rd @@ -0,0 +1,41 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/derive_bds_params.R +\name{compute_ratio} +\alias{compute_ratio} +\title{Compute ratio} +\usage{ +compute_ratio(x, y) +} +\arguments{ +\item{x}{Dividend + +\emph{Permitted Values:} numeric vector} + +\item{y}{Divisor + +\emph{Permitted Values:} numeric vector} +} +\value{ +The ratio computed as x / y. +} +\description{ +Computes ratio as dividend (x) divided by divisor (y) +} +\details{ +\code{x} and \code{y} must be of the same length. + +If the divisor equals 0, the result will be NA. + +Usually this computation function can not be used with \code{\%>\%}. +} +\examples{ + +# Example of Waist-to-Height Ratio where +# Waist Circumference is 120 cm +# and Height is 163 cm + +compute_ratio(x = 120, y = 163) +} +\seealso{ +\code{\link[=derive_param_ratio]{derive_param_ratio()}}, \code{\link[=derive_param_waisthip]{derive_param_waisthip()}}, \code{\link[=derive_param_waisthgt]{derive_param_waisthgt()}} +} diff --git a/man/derive_param_ratio.Rd b/man/derive_param_ratio.Rd new file mode 100644 index 0000000..47aef98 --- /dev/null +++ b/man/derive_param_ratio.Rd @@ -0,0 +1,175 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/derive_bds_params.R +\name{derive_param_ratio} +\alias{derive_param_ratio} +\title{Adds a Ratio Parameter Computed from the Analysis Value of Other Parameters} +\usage{ +derive_param_ratio( + dataset, + by_vars, + dividend_code, + divisor_code, + set_values_to, + constant_dividend = FALSE, + constant_divisor = FALSE, + filter = NULL, + constant_by_vars = NULL +) +} +\arguments{ +\item{dataset}{Input dataset + +The variables specified by the \code{by_vars} argument are expected to be in the dataset. +\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} +parameter) and to the parameters specified by \code{dividend_code} and \code{divisor_code}.} + +\item{by_vars}{Grouping variables + +For each group defined by \code{by_vars} an observation is added to the output +dataset. Only variables specified in \code{by_vars} will be populated +in the newly created records. + +\emph{Permitted Values}: list of variables created by \code{exprs()} +e.g. \code{exprs(USUBJID, VISIT)}} + +\item{dividend_code}{Dividend parameter code + +The observations where \code{PARAMCD} equals the specified value are considered +as the dividend + +\emph{Permitted Values:} character value} + +\item{divisor_code}{Divisor parameter code + +The observations where \code{PARAMCD} equals the specified value are considered +as the divisor + +\emph{Permitted Values:} character value} + +\item{set_values_to}{Variables to be set + +The specified variables are set to the specified values for the new +observations. For example \code{exprs(PARAMCD = "MAP")} defines the parameter code +for the new parameter. + +\emph{Permitted Values}: List of variable-value pairs} + +\item{constant_dividend}{Is dividend parameter constant? + +It is expected that the parameter code (PARAMCD) specified in \code{dividend_code} +which is required to derive the new parameter is measured only once. For example, +if Height-to-Weight Ratio should be derived and height is measured only once +while Weight is measured at each visit. Height could be specified +in the \code{dividend_code} argument and \code{constant_dividend} is to be set to \code{TRUE}. + +\emph{Permitted Values:} logical scalar} + +\item{constant_divisor}{Is divisor parameter constant? + +It is expected that the parameter code (PARAMCD) specified in \code{dividend_code} +which is required to derive the new parameter is measured only once. For example, +if Waist-to-Height Ratio should be derived and height is measured only once +while Waist Circumference is measured at each visit. Height could be specified +in the \code{divisor_code} argument and \code{constant_divisor} is to be set to \code{TRUE}. + +\emph{Permitted Values:} logical scalar} + +\item{filter}{Filter condition + +The specified condition is applied to the input dataset before deriving the +new parameter, i.e., only observations fulfilling the condition are taken +into account. + +\emph{Permitted Values:} a condition} + +\item{constant_by_vars}{By variables for when dividend and/or divisor is constant + +When dividend and/or divisor is constant, the parameters (measured only once) are merged +to the other parameters using the specified variables. + +If dividend and/or divisor is constant (e.g. only measured once at screening or baseline) then +use \code{constant_by_vars} to select the subject-level variable to merge on (e.g. \code{USUBJID}). +This will produce a generic Ratio parameter at all visits where dividend and/or divisor is measured. +Otherwise it will only be calculated at visits with both dividend and divisor parameters collected. + +\emph{Permitted Values}: list of variables created by \code{exprs()} +e.g. \code{exprs(USUBJID, VISIT)}} +} +\value{ +The input dataset with the new parameter added. Note, a variable will only +be populated in the new parameter rows if it is specified in \code{by_vars}. +} +\description{ +Adds a record for a generic Ratio parameter using two existing parameter +(dividend and divisor) each by group (e.g., subject and visit) where the source parameters are available. + +\strong{Note:} This is a wrapper function for the more generic \code{admiral::derive_param_computed()}. +} +\details{ +The analysis value of the new parameter is derived as +\deqn{RATIO = \frac{DIVIDENT}{DIVISOR}} +} +\examples{ + +# Example 1: Derive Waist-to-Hip Ratio where both source parameters are measured multiple times + +advs <- tribble( + ~USUBJID, ~PARAMCD, ~PARAM, ~AVAL, ~AVALU, ~VISIT, + "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 125, "cm", "SCREENING", + "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 124, "cm", "WEEK 2", + "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 123, "cm", "WEEK 3", + "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 110, "cm", "SCREENING", + "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 108, "cm", "WEEK 2", + "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 107, "cm", "WEEK 3", + "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 135, "cm", "SCREENING", + "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 133, "cm", "WEEK 2", + "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 132, "cm", "WEEK 3", + "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 120, "cm", "SCREENING", + "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 118, "cm", "WEEK 2", + "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 117, "cm", "WEEK 3" +) + +derive_param_ratio( + advs, + by_vars = exprs(USUBJID, VISIT), + dividend_code = "WSTCIR", + divisor_code = "HIPCIR", + set_values_to = exprs( + PARAMCD = "WAISTHIP", + PARAM = "Waist-to-Hip Ratio" + ) +) + +# Example 2: Derive Waist-to-Height Ratio where Height is measured only once + +advs <- tribble( + ~USUBJID, ~PARAMCD, ~PARAM, ~AVAL, ~AVALU, ~VISIT, + "01-101-1001", "HEIGHT", "Height (cm)", 147, "cm", "SCREENING", + "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 110, "cm", "SCREENING", + "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 108, "cm", "WEEK 2", + "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 107, "cm", "WEEK 3", + "01-101-1002", "HEIGHT", "Height (cm)", 163, "cm", "SCREENING", + "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 120, "cm", "SCREENING", + "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 118, "cm", "WEEK 2", + "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 117, "cm", "WEEK 3", +) + +derive_param_ratio( + advs, + by_vars = exprs(USUBJID, VISIT), + dividend_code = "WSTCIR", + divisor_code = "HEIGHT", + set_values_to = exprs( + PARAMCD = "WAISTHGT", + PARAM = "Waist-to-Height Ratio" + ), + constant_divisor = TRUE, + constant_by_vars = exprs(USUBJID) +) +} +\seealso{ +\code{\link[=compute_ratio]{compute_ratio()}} +} diff --git a/man/derive_param_waisthgt.Rd b/man/derive_param_waisthgt.Rd new file mode 100644 index 0000000..7bba85b --- /dev/null +++ b/man/derive_param_waisthgt.Rd @@ -0,0 +1,152 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/derive_advs_params.R +\name{derive_param_waisthgt} +\alias{derive_param_waisthgt} +\title{Adds a Parameter for Waist-to-Height Ratio} +\usage{ +derive_param_waisthgt( + dataset, + by_vars, + wstcir_code = "WSTCIR", + height_code = "HGHT", + set_values_to = exprs(PARAMCD = "WAISTHGT"), + filter = NULL, + constant_by_vars = NULL +) +} +\arguments{ +\item{dataset}{Input dataset + +The variables specified by the \code{by_vars} argument are expected to be in the dataset. +\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} +parameter) and to the parameters specified by \code{wstcir_code} and \code{height_code}.} + +\item{by_vars}{Grouping variables + +For each group defined by \code{by_vars} an observation is added to the output +dataset. Only variables specified in \code{by_vars} will be populated +in the newly created records. + +\emph{Permitted Values}: list of variables created by \code{exprs()} +e.g. \code{exprs(USUBJID, VISIT)}} + +\item{wstcir_code}{Waist Circumference parameter code + +The observations where \code{PARAMCD} equals the specified value are considered +as the Waist Circumference + +\emph{Permitted Values:} character value} + +\item{height_code}{Height parameter code + +The observations where \code{PARAMCD} equals the specified value are considered +as the Height. It is expected that Height is measured in cm + +\emph{Permitted Values:} character value} + +\item{set_values_to}{Variables to be set + +The specified variables are set to the specified values for the new +observations. For example \code{exprs(PARAMCD = "MAP")} defines the parameter code +for the new parameter. + +\emph{Permitted Values}: List of variable-value pairs} + +\item{filter}{Filter condition + +The specified condition is applied to the input dataset before deriving the +new parameter, i.e., only observations fulfilling the condition are taken +into account. + +\emph{Permitted Values:} a condition} + +\item{constant_by_vars}{By variables for when Height is constant + +When Height is constant, the Height parameters (measured only once) are merged +to the other parameters using the specified variables. + +If Height is constant (e.g. only measured once at screening or baseline) then +use \code{constant_by_vars} to select the subject-level variable to merge on (e.g. \code{USUBJID}). +This will produce Waist-to-Height Ratio at all visits where Waist Circumference is measured. +Otherwise it will only be calculated at visits with both Height and Waist Circumference collected. + +\emph{Permitted Values}: list of variables created by \code{exprs()} +e.g. \code{exprs(USUBJID, VISIT)}} +} +\value{ +The input dataset with the new parameter added. Note, a variable will only +be populated in the new parameter rows if it is specified in \code{by_vars}. +} +\description{ +Adds a record for Waist-to-Height Ratio using Waist Circumference and Height each by group +(e.g., subject and visit) where the source parameters are available. + +\strong{Note:} This is a wrapper function for the more generic \code{derive_param_ratio()}. +} +\details{ +The analysis value of the new parameter is derived as +\deqn{WAISTHGT = \frac{WSTCIR}{HEIGHT}} +} +\examples{ + +# Example 1: Derive Waist-to-Height Ratio where Height is measured only once + +advs <- tribble( + ~USUBJID, ~PARAMCD, ~PARAM, ~AVAL, ~AVALU, ~VISIT, + "01-101-1001", "HEIGHT", "Height (cm)", 147, "cm", "SCREENING", + "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 110, "cm", "SCREENING", + "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 108, "cm", "WEEK 2", + "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 107, "cm", "WEEK 3", + "01-101-1002", "HEIGHT", "Height (cm)", 163, "cm", "SCREENING", + "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 120, "cm", "SCREENING", + "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 118, "cm", "WEEK 2", + "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 117, "cm", "WEEK 3", +) + +derive_param_waisthgt( + advs, + by_vars = exprs(USUBJID, VISIT), + wstcir_code = "WSTCIR", + height_code = "HEIGHT", + set_values_to = exprs( + PARAMCD = "WAISTHGT", + PARAM = "Waist-to-Height Ratio" + ), + constant_by_vars = exprs(USUBJID) +) + +# Example 2: Pediatric study where Height and Waist Circumference are measured multiple times + +advs <- tribble( + ~USUBJID, ~PARAMCD, ~PARAM, ~AVAL, ~AVALU, ~VISIT, + "01-101-1001", "HEIGHT", "Height (cm)", 147, "cm", "SCREENING", + "01-101-1001", "HEIGHT", "Height (cm)", 148, "cm", "WEEK 2", + "01-101-1001", "HEIGHT", "Height (cm)", 149, "cm", "WEEK 3", + "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 100, "cm", "SCREENING", + "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 99, "cm", "WEEK 2", + "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 98, "cm", "WEEK 3", + "01-101-1002", "HEIGHT", "Height (cm)", 163, "cm", "SCREENING", + "01-101-1002", "HEIGHT", "Height (cm)", 164, "cm", "WEEK 2", + "01-101-1002", "HEIGHT", "Height (cm)", 165, "cm", "WEEK 3", + "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 110, "cm", "SCREENING", + "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 109, "cm", "WEEK 2", + "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 108, "cm", "WEEK 3" +) + +derive_param_waisthgt( + advs, + by_vars = exprs(USUBJID, VISIT), + wstcir_code = "WSTCIR", + height_code = "HEIGHT", + set_values_to = exprs( + PARAMCD = "WAISTHGT", + PARAM = "Waist-to-Height Ratio" + ) +) +} +\seealso{ +\code{\link[=derive_param_ratio]{derive_param_ratio()}}, \code{\link[=compute_ratio]{compute_ratio()}} +} diff --git a/man/derive_param_waisthip.Rd b/man/derive_param_waisthip.Rd new file mode 100644 index 0000000..d8e9b03 --- /dev/null +++ b/man/derive_param_waisthip.Rd @@ -0,0 +1,110 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/derive_advs_params.R +\name{derive_param_waisthip} +\alias{derive_param_waisthip} +\title{Adds a Parameter for Waist-to-Hip Ratio} +\usage{ +derive_param_waisthip( + dataset, + by_vars, + wstcir_code = "WSTCIR", + hipcir_code = "HIPCIR", + set_values_to = exprs(PARAMCD = "WAISTHIP"), + filter = NULL +) +} +\arguments{ +\item{dataset}{Input dataset + +The variables specified by the \code{by_vars} argument are expected to be in the dataset. +\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} +parameter) and to the parameters specified by \code{wstcir_code} and \code{hipcir_code}.} + +\item{by_vars}{Grouping variables + +For each group defined by \code{by_vars} an observation is added to the output +dataset. Only variables specified in \code{by_vars} will be populated +in the newly created records. + +\emph{Permitted Values}: list of variables created by \code{exprs()} +e.g. \code{exprs(USUBJID, VISIT)}} + +\item{wstcir_code}{Waist Circumference parameter code + +The observations where \code{PARAMCD} equals the specified value are considered +as the Waist Circumference + +\emph{Permitted Values:} character value} + +\item{hipcir_code}{Hip Circumference parameter code + +The observations where \code{PARAMCD} equals the specified value are considered +as the Hip Circumference + +\emph{Permitted Values:} character value} + +\item{set_values_to}{Variables to be set + +The specified variables are set to the specified values for the new +observations. For example \code{exprs(PARAMCD = "MAP")} defines the parameter code +for the new parameter. + +\emph{Permitted Values}: List of variable-value pairs} + +\item{filter}{Filter condition + +The specified condition is applied to the input dataset before deriving the +new parameter, i.e., only observations fulfilling the condition are taken +into account. + +\emph{Permitted Values:} a condition} +} +\value{ +The input dataset with the new parameter added. Note, a variable will only +be populated in the new parameter rows if it is specified in \code{by_vars}. +} +\description{ +Adds a record for Waist-to-Hip Ratio using Waist Circumference and Hip Circumference each by group +(e.g., subject and visit) where the source parameters are available. + +\strong{Note:} This is a wrapper function for the more generic \code{derive_param_ratio()}. +} +\details{ +The analysis value of the new parameter is derived as +\deqn{WAISTHIP = \frac{WSTCIR}{HIPCIR}} +} +\examples{ + +advs <- tribble( + ~USUBJID, ~PARAMCD, ~PARAM, ~AVAL, ~AVALU, ~VISIT, + "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 110, "cm", "SCREENING", + "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 108, "cm", "WEEK 2", + "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 107, "cm", "WEEK 3", + "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 125, "cm", "SCREENING", + "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 124, "cm", "WEEK 2", + "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 123, "cm", "WEEK 3", + "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 120, "cm", "SCREENING", + "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 118, "cm", "WEEK 2", + "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 117, "cm", "WEEK 3", + "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 135, "cm", "SCREENING", + "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 133, "cm", "WEEK 2", + "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 132, "cm", "WEEK 3" +) + +derive_param_waisthip( + advs, + by_vars = exprs(USUBJID, VISIT), + wstcir_code = "WSTCIR", + hipcir_code = "HIPCIR", + set_values_to = exprs( + PARAMCD = "WAISTHIP", + PARAM = "Waist-to-Hip Ratio" + ) +) +} +\seealso{ +\code{\link[=derive_param_ratio]{derive_param_ratio()}}, \code{\link[=compute_ratio]{compute_ratio()}} +} diff --git a/tests/testthat/test-compute_ratio.R b/tests/testthat/test-compute_ratio.R new file mode 100644 index 0000000..7877dba --- /dev/null +++ b/tests/testthat/test-compute_ratio.R @@ -0,0 +1,39 @@ +test_that("compute_ratio Test 1: Basic", { + expect_equal( + compute_ratio( + x = c(182, 50.25), + y = c(91, 201) + ), + c(2, 0.25) + ) +}) + +test_that("compute_ratio Test 2: Negatives", { + expect_equal( + compute_ratio( + x = c(-63.9, 100), + y = c(21.3, -40) + ), + c(-3, -2.5) + ) +}) + +test_that("compute_ratio Test 3: Zeros", { + expect_equal( + compute_ratio( + x = c(0, 95, 0), + y = c(75, 0, 0) + ), + c(0, NA_real_, NA_real_) + ) +}) + +test_that("compute_ratio Test 4: NAs", { + expect_equal( + compute_ratio( + x = c(44, NA, NA), + y = c(NA, 140, NA) + ), + c(NA_real_, NA_real_, NA_real_) + ) +}) From 91f76c3746eb74dceeba8742c2236604394ebefc Mon Sep 17 00:00:00 2001 From: Andrii Yurovskyi Date: Sun, 29 Sep 2024 01:32:16 +0200 Subject: [PATCH 02/28] (#31): Apply styler::style_file() to R-files --- R/derive_advs_params.R | 36 ++++++++++++++++-------------------- R/derive_bds_params.R | 19 ++++++++----------- 2 files changed, 24 insertions(+), 31 deletions(-) diff --git a/R/derive_advs_params.R b/R/derive_advs_params.R index 9ec5a49..ebfaf15 100644 --- a/R/derive_advs_params.R +++ b/R/derive_advs_params.R @@ -49,15 +49,15 @@ #' "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 110, "cm", "SCREENING", #' "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 108, "cm", "WEEK 2", #' "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 107, "cm", "WEEK 3", -#' "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 125, "cm", "SCREENING", -#' "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 124, "cm", "WEEK 2", -#' "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 123, "cm", "WEEK 3", +#' "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 125, "cm", "SCREENING", +#' "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 124, "cm", "WEEK 2", +#' "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 123, "cm", "WEEK 3", #' "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 120, "cm", "SCREENING", #' "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 118, "cm", "WEEK 2", #' "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 117, "cm", "WEEK 3", -#' "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 135, "cm", "SCREENING", -#' "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 133, "cm", "WEEK 2", -#' "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 132, "cm", "WEEK 3" +#' "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 135, "cm", "SCREENING", +#' "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 133, "cm", "WEEK 2", +#' "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 132, "cm", "WEEK 3" #' ) #' #' derive_param_waisthip( @@ -70,14 +70,12 @@ #' PARAM = "Waist-to-Hip Ratio" #' ) #' ) - derive_param_waisthip <- function(dataset, by_vars, wstcir_code = "WSTCIR", hipcir_code = "HIPCIR", set_values_to = exprs(PARAMCD = "WAISTHIP"), filter = NULL) { - assert_vars(by_vars) assert_data_frame(dataset, required_vars = exprs(!!!by_vars, PARAMCD, AVAL)) assert_character_scalar(wstcir_code) @@ -159,11 +157,11 @@ derive_param_waisthip <- function(dataset, #' #' advs <- tribble( #' ~USUBJID, ~PARAMCD, ~PARAM, ~AVAL, ~AVALU, ~VISIT, -#' "01-101-1001", "HEIGHT", "Height (cm)", 147, "cm", "SCREENING", +#' "01-101-1001", "HEIGHT", "Height (cm)", 147, "cm", "SCREENING", #' "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 110, "cm", "SCREENING", #' "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 108, "cm", "WEEK 2", #' "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 107, "cm", "WEEK 3", -#' "01-101-1002", "HEIGHT", "Height (cm)", 163, "cm", "SCREENING", +#' "01-101-1002", "HEIGHT", "Height (cm)", 163, "cm", "SCREENING", #' "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 120, "cm", "SCREENING", #' "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 118, "cm", "WEEK 2", #' "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 117, "cm", "WEEK 3", @@ -185,15 +183,15 @@ derive_param_waisthip <- function(dataset, #' #' advs <- tribble( #' ~USUBJID, ~PARAMCD, ~PARAM, ~AVAL, ~AVALU, ~VISIT, -#' "01-101-1001", "HEIGHT", "Height (cm)", 147, "cm", "SCREENING", -#' "01-101-1001", "HEIGHT", "Height (cm)", 148, "cm", "WEEK 2", -#' "01-101-1001", "HEIGHT", "Height (cm)", 149, "cm", "WEEK 3", +#' "01-101-1001", "HEIGHT", "Height (cm)", 147, "cm", "SCREENING", +#' "01-101-1001", "HEIGHT", "Height (cm)", 148, "cm", "WEEK 2", +#' "01-101-1001", "HEIGHT", "Height (cm)", 149, "cm", "WEEK 3", #' "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 100, "cm", "SCREENING", -#' "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 99, "cm", "WEEK 2", -#' "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 98, "cm", "WEEK 3", -#' "01-101-1002", "HEIGHT", "Height (cm)", 163, "cm", "SCREENING", -#' "01-101-1002", "HEIGHT", "Height (cm)", 164, "cm", "WEEK 2", -#' "01-101-1002", "HEIGHT", "Height (cm)", 165, "cm", "WEEK 3", +#' "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 99, "cm", "WEEK 2", +#' "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 98, "cm", "WEEK 3", +#' "01-101-1002", "HEIGHT", "Height (cm)", 163, "cm", "SCREENING", +#' "01-101-1002", "HEIGHT", "Height (cm)", 164, "cm", "WEEK 2", +#' "01-101-1002", "HEIGHT", "Height (cm)", 165, "cm", "WEEK 3", #' "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 110, "cm", "SCREENING", #' "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 109, "cm", "WEEK 2", #' "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 108, "cm", "WEEK 3" @@ -209,7 +207,6 @@ derive_param_waisthip <- function(dataset, #' PARAM = "Waist-to-Height Ratio" #' ) #' ) - derive_param_waisthgt <- function(dataset, by_vars, wstcir_code = "WSTCIR", @@ -217,7 +214,6 @@ derive_param_waisthgt <- function(dataset, set_values_to = exprs(PARAMCD = "WAISTHGT"), filter = NULL, constant_by_vars = NULL) { - assert_vars(by_vars) assert_data_frame(dataset, required_vars = exprs(!!!by_vars, PARAMCD, AVAL)) assert_character_scalar(wstcir_code) diff --git a/R/derive_bds_params.R b/R/derive_bds_params.R index bdbc9b7..88198d5 100644 --- a/R/derive_bds_params.R +++ b/R/derive_bds_params.R @@ -81,15 +81,15 @@ #' #' advs <- tribble( #' ~USUBJID, ~PARAMCD, ~PARAM, ~AVAL, ~AVALU, ~VISIT, -#' "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 125, "cm", "SCREENING", -#' "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 124, "cm", "WEEK 2", -#' "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 123, "cm", "WEEK 3", +#' "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 125, "cm", "SCREENING", +#' "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 124, "cm", "WEEK 2", +#' "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 123, "cm", "WEEK 3", #' "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 110, "cm", "SCREENING", #' "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 108, "cm", "WEEK 2", #' "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 107, "cm", "WEEK 3", -#' "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 135, "cm", "SCREENING", -#' "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 133, "cm", "WEEK 2", -#' "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 132, "cm", "WEEK 3", +#' "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 135, "cm", "SCREENING", +#' "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 133, "cm", "WEEK 2", +#' "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 132, "cm", "WEEK 3", #' "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 120, "cm", "SCREENING", #' "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 118, "cm", "WEEK 2", #' "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 117, "cm", "WEEK 3" @@ -110,11 +110,11 @@ #' #' advs <- tribble( #' ~USUBJID, ~PARAMCD, ~PARAM, ~AVAL, ~AVALU, ~VISIT, -#' "01-101-1001", "HEIGHT", "Height (cm)", 147, "cm", "SCREENING", +#' "01-101-1001", "HEIGHT", "Height (cm)", 147, "cm", "SCREENING", #' "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 110, "cm", "SCREENING", #' "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 108, "cm", "WEEK 2", #' "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 107, "cm", "WEEK 3", -#' "01-101-1002", "HEIGHT", "Height (cm)", 163, "cm", "SCREENING", +#' "01-101-1002", "HEIGHT", "Height (cm)", 163, "cm", "SCREENING", #' "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 120, "cm", "SCREENING", #' "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 118, "cm", "WEEK 2", #' "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 117, "cm", "WEEK 3", @@ -132,7 +132,6 @@ #' constant_divisor = TRUE, #' constant_by_vars = exprs(USUBJID) #' ) - derive_param_ratio <- function(dataset, by_vars, dividend_code, @@ -142,7 +141,6 @@ derive_param_ratio <- function(dataset, constant_divisor = FALSE, filter = NULL, constant_by_vars = NULL) { - assert_vars(by_vars) assert_data_frame(dataset, required_vars = exprs(!!!by_vars, PARAMCD, AVAL)) assert_character_scalar(dividend_code) @@ -226,7 +224,6 @@ derive_param_ratio <- function(dataset, #' # and Height is 163 cm #' #' compute_ratio(x = 120, y = 163) - compute_ratio <- function(x, y) { assert_numeric_vector(x) assert_numeric_vector(y) From 2ce64363be7edbd313ea8032ef16ed26c3990808 Mon Sep 17 00:00:00 2001 From: Andrii Yurovskyi Date: Sun, 29 Sep 2024 01:46:34 +0200 Subject: [PATCH 03/28] (#31): Fix lintr warnings + Roxygenize --- R/derive_advs_params.R | 21 ++++++++++++--------- R/derive_bds_params.R | 18 +++++++++++------- man/compute_ratio.Rd | 4 +++- man/derive_param_ratio.Rd | 30 ++++++++++++++++-------------- man/derive_param_waisthgt.Rd | 34 ++++++++++++++++++---------------- man/derive_param_waisthip.Rd | 19 ++++++++++--------- 6 files changed, 70 insertions(+), 56 deletions(-) diff --git a/R/derive_advs_params.R b/R/derive_advs_params.R index ebfaf15..eaee1e6 100644 --- a/R/derive_advs_params.R +++ b/R/derive_advs_params.R @@ -1,7 +1,7 @@ #' Adds a Parameter for Waist-to-Hip Ratio #' -#' @description Adds a record for Waist-to-Hip Ratio using Waist Circumference and Hip Circumference each by group -#' (e.g., subject and visit) where the source parameters are available. +#' @description Adds a record for Waist-to-Hip Ratio using Waist Circumference and Hip Circumference +#' each by group (e.g., subject and visit) where the source parameters are available. #' #' **Note:** This is a wrapper function for the more generic \code{derive_param_ratio()}. #' @@ -40,7 +40,8 @@ #' #' @export #' -#' @seealso \code{\link[=derive_param_ratio]{derive_param_ratio()}}, \code{\link[=compute_ratio]{compute_ratio()}} +#' @seealso \code{\link[=derive_param_ratio]{derive_param_ratio()}}, +#' \code{\link[=compute_ratio]{compute_ratio()}} #' #' @examples #' @@ -96,8 +97,8 @@ derive_param_waisthip <- function(dataset, #' Adds a Parameter for Waist-to-Height Ratio #' -#' @description Adds a record for Waist-to-Height Ratio using Waist Circumference and Height each by group -#' (e.g., subject and visit) where the source parameters are available. +#' @description Adds a record for Waist-to-Height Ratio using Waist Circumference and Height +#' each by group (e.g., subject and visit) where the source parameters are available. #' #' **Note:** This is a wrapper function for the more generic \code{derive_param_ratio()}. #' @@ -129,10 +130,11 @@ derive_param_waisthip <- function(dataset, #' When Height is constant, the Height parameters (measured only once) are merged #' to the other parameters using the specified variables. #' -#' If Height is constant (e.g. only measured once at screening or baseline) then -#' use \code{constant_by_vars} to select the subject-level variable to merge on (e.g. \code{USUBJID}). +#' If Height is constant (e.g. only measured once at screening or baseline) then use +#' \code{constant_by_vars} to select the subject-level variable to merge on (e.g. \code{USUBJID}). #' This will produce Waist-to-Height Ratio at all visits where Waist Circumference is measured. -#' Otherwise it will only be calculated at visits with both Height and Waist Circumference collected. +#' Otherwise it will only be calculated at visits with both Height and Waist Circumference +#' collected. #' #' *Permitted Values*: list of variables created by \code{exprs()} #' e.g. \code{exprs(USUBJID, VISIT)} @@ -149,7 +151,8 @@ derive_param_waisthip <- function(dataset, #' #' @export #' -#' @seealso \code{\link[=derive_param_ratio]{derive_param_ratio()}}, \code{\link[=compute_ratio]{compute_ratio()}} +#' @seealso \code{\link[=derive_param_ratio]{derive_param_ratio()}}, +#' \code{\link[=compute_ratio]{compute_ratio()}} #' #' @examples #' diff --git a/R/derive_bds_params.R b/R/derive_bds_params.R index 88198d5..6e82a5c 100644 --- a/R/derive_bds_params.R +++ b/R/derive_bds_params.R @@ -1,9 +1,10 @@ #' Adds a Ratio Parameter Computed from the Analysis Value of Other Parameters #' #' @description Adds a record for a generic Ratio parameter using two existing parameter -#' (dividend and divisor) each by group (e.g., subject and visit) where the source parameters are available. +#' (dividend and divisor) each by group (e.g., subject and visit) where the source parameters +#' are available. #' -#' **Note:** This is a wrapper function for the more generic \code{admiral::derive_param_computed()}. +#' **Note:** This is a wrapper function for the more generic \code{admiral::derive_param_computed()} #' #' @param dataset Input dataset #' @@ -53,10 +54,11 @@ #' When dividend and/or divisor is constant, the parameters (measured only once) are merged #' to the other parameters using the specified variables. #' -#' If dividend and/or divisor is constant (e.g. only measured once at screening or baseline) then -#' use \code{constant_by_vars} to select the subject-level variable to merge on (e.g. \code{USUBJID}). -#' This will produce a generic Ratio parameter at all visits where dividend and/or divisor is measured. -#' Otherwise it will only be calculated at visits with both dividend and divisor parameters collected. +#' If dividend and/or divisor is constant (e.g. only measured once at screening or baseline) +#' then use \code{constant_by_vars} to select the subject-level variable to merge on +#' (e.g. \code{USUBJID}). This will produce a generic Ratio parameter at all visits where dividend +#' and/or divisor is measured. Otherwise it will only be calculated at visits with both dividend +#' and divisor parameters collected. #' #' *Permitted Values*: list of variables created by \code{exprs()} #' e.g. \code{exprs(USUBJID, VISIT)} @@ -215,7 +217,9 @@ derive_param_ratio <- function(dataset, #' #' @export #' -#' @seealso \code{\link[=derive_param_ratio]{derive_param_ratio()}}, \code{\link[=derive_param_waisthip]{derive_param_waisthip()}}, \code{\link[=derive_param_waisthgt]{derive_param_waisthgt()}} +#' @seealso \code{\link[=derive_param_ratio]{derive_param_ratio()}}, +#' \code{\link[=derive_param_waisthip]{derive_param_waisthip()}}, +#' \code{\link[=derive_param_waisthgt]{derive_param_waisthgt()}} #' #' @examples #' diff --git a/man/compute_ratio.Rd b/man/compute_ratio.Rd index ce9ce2c..2a44586 100644 --- a/man/compute_ratio.Rd +++ b/man/compute_ratio.Rd @@ -37,5 +37,7 @@ Usually this computation function can not be used with \code{\%>\%}. compute_ratio(x = 120, y = 163) } \seealso{ -\code{\link[=derive_param_ratio]{derive_param_ratio()}}, \code{\link[=derive_param_waisthip]{derive_param_waisthip()}}, \code{\link[=derive_param_waisthgt]{derive_param_waisthgt()}} +\code{\link[=derive_param_ratio]{derive_param_ratio()}}, +\code{\link[=derive_param_waisthip]{derive_param_waisthip()}}, +\code{\link[=derive_param_waisthgt]{derive_param_waisthgt()}} } diff --git a/man/derive_param_ratio.Rd b/man/derive_param_ratio.Rd index 47aef98..ea67813 100644 --- a/man/derive_param_ratio.Rd +++ b/man/derive_param_ratio.Rd @@ -90,10 +90,11 @@ into account. When dividend and/or divisor is constant, the parameters (measured only once) are merged to the other parameters using the specified variables. -If dividend and/or divisor is constant (e.g. only measured once at screening or baseline) then -use \code{constant_by_vars} to select the subject-level variable to merge on (e.g. \code{USUBJID}). -This will produce a generic Ratio parameter at all visits where dividend and/or divisor is measured. -Otherwise it will only be calculated at visits with both dividend and divisor parameters collected. +If dividend and/or divisor is constant (e.g. only measured once at screening or baseline) +then use \code{constant_by_vars} to select the subject-level variable to merge on +(e.g. \code{USUBJID}). This will produce a generic Ratio parameter at all visits where dividend +and/or divisor is measured. Otherwise it will only be calculated at visits with both dividend +and divisor parameters collected. \emph{Permitted Values}: list of variables created by \code{exprs()} e.g. \code{exprs(USUBJID, VISIT)}} @@ -104,9 +105,10 @@ be populated in the new parameter rows if it is specified in \code{by_vars}. } \description{ Adds a record for a generic Ratio parameter using two existing parameter -(dividend and divisor) each by group (e.g., subject and visit) where the source parameters are available. +(dividend and divisor) each by group (e.g., subject and visit) where the source parameters +are available. -\strong{Note:} This is a wrapper function for the more generic \code{admiral::derive_param_computed()}. +\strong{Note:} This is a wrapper function for the more generic \code{admiral::derive_param_computed()} } \details{ The analysis value of the new parameter is derived as @@ -118,15 +120,15 @@ The analysis value of the new parameter is derived as advs <- tribble( ~USUBJID, ~PARAMCD, ~PARAM, ~AVAL, ~AVALU, ~VISIT, - "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 125, "cm", "SCREENING", - "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 124, "cm", "WEEK 2", - "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 123, "cm", "WEEK 3", + "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 125, "cm", "SCREENING", + "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 124, "cm", "WEEK 2", + "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 123, "cm", "WEEK 3", "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 110, "cm", "SCREENING", "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 108, "cm", "WEEK 2", "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 107, "cm", "WEEK 3", - "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 135, "cm", "SCREENING", - "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 133, "cm", "WEEK 2", - "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 132, "cm", "WEEK 3", + "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 135, "cm", "SCREENING", + "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 133, "cm", "WEEK 2", + "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 132, "cm", "WEEK 3", "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 120, "cm", "SCREENING", "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 118, "cm", "WEEK 2", "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 117, "cm", "WEEK 3" @@ -147,11 +149,11 @@ derive_param_ratio( advs <- tribble( ~USUBJID, ~PARAMCD, ~PARAM, ~AVAL, ~AVALU, ~VISIT, - "01-101-1001", "HEIGHT", "Height (cm)", 147, "cm", "SCREENING", + "01-101-1001", "HEIGHT", "Height (cm)", 147, "cm", "SCREENING", "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 110, "cm", "SCREENING", "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 108, "cm", "WEEK 2", "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 107, "cm", "WEEK 3", - "01-101-1002", "HEIGHT", "Height (cm)", 163, "cm", "SCREENING", + "01-101-1002", "HEIGHT", "Height (cm)", 163, "cm", "SCREENING", "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 120, "cm", "SCREENING", "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 118, "cm", "WEEK 2", "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 117, "cm", "WEEK 3", diff --git a/man/derive_param_waisthgt.Rd b/man/derive_param_waisthgt.Rd index 7bba85b..069612e 100644 --- a/man/derive_param_waisthgt.Rd +++ b/man/derive_param_waisthgt.Rd @@ -68,10 +68,11 @@ into account. When Height is constant, the Height parameters (measured only once) are merged to the other parameters using the specified variables. -If Height is constant (e.g. only measured once at screening or baseline) then -use \code{constant_by_vars} to select the subject-level variable to merge on (e.g. \code{USUBJID}). +If Height is constant (e.g. only measured once at screening or baseline) then use +\code{constant_by_vars} to select the subject-level variable to merge on (e.g. \code{USUBJID}). This will produce Waist-to-Height Ratio at all visits where Waist Circumference is measured. -Otherwise it will only be calculated at visits with both Height and Waist Circumference collected. +Otherwise it will only be calculated at visits with both Height and Waist Circumference +collected. \emph{Permitted Values}: list of variables created by \code{exprs()} e.g. \code{exprs(USUBJID, VISIT)}} @@ -81,8 +82,8 @@ The input dataset with the new parameter added. Note, a variable will only be populated in the new parameter rows if it is specified in \code{by_vars}. } \description{ -Adds a record for Waist-to-Height Ratio using Waist Circumference and Height each by group -(e.g., subject and visit) where the source parameters are available. +Adds a record for Waist-to-Height Ratio using Waist Circumference and Height +each by group (e.g., subject and visit) where the source parameters are available. \strong{Note:} This is a wrapper function for the more generic \code{derive_param_ratio()}. } @@ -96,11 +97,11 @@ The analysis value of the new parameter is derived as advs <- tribble( ~USUBJID, ~PARAMCD, ~PARAM, ~AVAL, ~AVALU, ~VISIT, - "01-101-1001", "HEIGHT", "Height (cm)", 147, "cm", "SCREENING", + "01-101-1001", "HEIGHT", "Height (cm)", 147, "cm", "SCREENING", "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 110, "cm", "SCREENING", "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 108, "cm", "WEEK 2", "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 107, "cm", "WEEK 3", - "01-101-1002", "HEIGHT", "Height (cm)", 163, "cm", "SCREENING", + "01-101-1002", "HEIGHT", "Height (cm)", 163, "cm", "SCREENING", "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 120, "cm", "SCREENING", "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 118, "cm", "WEEK 2", "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 117, "cm", "WEEK 3", @@ -122,15 +123,15 @@ derive_param_waisthgt( advs <- tribble( ~USUBJID, ~PARAMCD, ~PARAM, ~AVAL, ~AVALU, ~VISIT, - "01-101-1001", "HEIGHT", "Height (cm)", 147, "cm", "SCREENING", - "01-101-1001", "HEIGHT", "Height (cm)", 148, "cm", "WEEK 2", - "01-101-1001", "HEIGHT", "Height (cm)", 149, "cm", "WEEK 3", + "01-101-1001", "HEIGHT", "Height (cm)", 147, "cm", "SCREENING", + "01-101-1001", "HEIGHT", "Height (cm)", 148, "cm", "WEEK 2", + "01-101-1001", "HEIGHT", "Height (cm)", 149, "cm", "WEEK 3", "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 100, "cm", "SCREENING", - "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 99, "cm", "WEEK 2", - "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 98, "cm", "WEEK 3", - "01-101-1002", "HEIGHT", "Height (cm)", 163, "cm", "SCREENING", - "01-101-1002", "HEIGHT", "Height (cm)", 164, "cm", "WEEK 2", - "01-101-1002", "HEIGHT", "Height (cm)", 165, "cm", "WEEK 3", + "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 99, "cm", "WEEK 2", + "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 98, "cm", "WEEK 3", + "01-101-1002", "HEIGHT", "Height (cm)", 163, "cm", "SCREENING", + "01-101-1002", "HEIGHT", "Height (cm)", 164, "cm", "WEEK 2", + "01-101-1002", "HEIGHT", "Height (cm)", 165, "cm", "WEEK 3", "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 110, "cm", "SCREENING", "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 109, "cm", "WEEK 2", "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 108, "cm", "WEEK 3" @@ -148,5 +149,6 @@ derive_param_waisthgt( ) } \seealso{ -\code{\link[=derive_param_ratio]{derive_param_ratio()}}, \code{\link[=compute_ratio]{compute_ratio()}} +\code{\link[=derive_param_ratio]{derive_param_ratio()}}, +\code{\link[=compute_ratio]{compute_ratio()}} } diff --git a/man/derive_param_waisthip.Rd b/man/derive_param_waisthip.Rd index d8e9b03..25ef238 100644 --- a/man/derive_param_waisthip.Rd +++ b/man/derive_param_waisthip.Rd @@ -67,8 +67,8 @@ The input dataset with the new parameter added. Note, a variable will only be populated in the new parameter rows if it is specified in \code{by_vars}. } \description{ -Adds a record for Waist-to-Hip Ratio using Waist Circumference and Hip Circumference each by group -(e.g., subject and visit) where the source parameters are available. +Adds a record for Waist-to-Hip Ratio using Waist Circumference and Hip Circumference +each by group (e.g., subject and visit) where the source parameters are available. \strong{Note:} This is a wrapper function for the more generic \code{derive_param_ratio()}. } @@ -83,15 +83,15 @@ advs <- tribble( "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 110, "cm", "SCREENING", "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 108, "cm", "WEEK 2", "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 107, "cm", "WEEK 3", - "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 125, "cm", "SCREENING", - "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 124, "cm", "WEEK 2", - "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 123, "cm", "WEEK 3", + "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 125, "cm", "SCREENING", + "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 124, "cm", "WEEK 2", + "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 123, "cm", "WEEK 3", "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 120, "cm", "SCREENING", "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 118, "cm", "WEEK 2", "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 117, "cm", "WEEK 3", - "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 135, "cm", "SCREENING", - "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 133, "cm", "WEEK 2", - "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 132, "cm", "WEEK 3" + "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 135, "cm", "SCREENING", + "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 133, "cm", "WEEK 2", + "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 132, "cm", "WEEK 3" ) derive_param_waisthip( @@ -106,5 +106,6 @@ derive_param_waisthip( ) } \seealso{ -\code{\link[=derive_param_ratio]{derive_param_ratio()}}, \code{\link[=compute_ratio]{compute_ratio()}} +\code{\link[=derive_param_ratio]{derive_param_ratio()}}, +\code{\link[=compute_ratio]{compute_ratio()}} } From be8ea17f6c568713cdab6999eb06c317b241eaca Mon Sep 17 00:00:00 2001 From: Andrii Yurovskyi Date: Tue, 1 Oct 2024 02:16:16 +0200 Subject: [PATCH 04/28] (#31): Move derive_param_ratio to {admiral} --- DESCRIPTION | 3 +- NAMESPACE | 5 +- R/admiralmetabolic-package.R | 3 +- R/derive_advs_params.R | 24 +-- R/derive_bds_params.R | 237 ---------------------------- man/compute_ratio.Rd | 43 ----- man/derive_param_ratio.Rd | 177 --------------------- man/derive_param_waisthgt.Rd | 8 +- man/derive_param_waisthip.Rd | 8 +- tests/testthat/test-compute_ratio.R | 39 ----- 10 files changed, 27 insertions(+), 520 deletions(-) delete mode 100644 R/derive_bds_params.R delete mode 100644 man/compute_ratio.Rd delete mode 100644 man/derive_param_ratio.Rd delete mode 100644 tests/testthat/test-compute_ratio.R diff --git a/DESCRIPTION b/DESCRIPTION index dbe32e3..67fa74f 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -30,8 +30,7 @@ Imports: lubridate (>= 1.7.4), magrittr (>= 1.5), rlang (>= 0.4.4), - tidyselect (>= 1.0.0), - checkmate + tidyselect (>= 1.0.0) Suggests: diffdf, DT, diff --git a/NAMESPACE b/NAMESPACE index f52bb68..ef87812 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -1,11 +1,9 @@ # Generated by roxygen2: do not edit by hand -export(compute_ratio) -export(derive_param_ratio) export(derive_param_waisthgt) export(derive_param_waisthip) export(hello_admiral) -importFrom(admiral,derive_param_computed) +importFrom(admiral,derive_param_ratio) importFrom(admiraldev,assert_character_scalar) importFrom(admiraldev,assert_data_frame) importFrom(admiraldev,assert_filter_cond) @@ -14,7 +12,6 @@ importFrom(admiraldev,assert_numeric_vector) importFrom(admiraldev,assert_param_does_not_exist) importFrom(admiraldev,assert_vars) importFrom(admiraldev,assert_varval_list) -importFrom(checkmate,assert_true) importFrom(dplyr,arrange) importFrom(dplyr,bind_cols) importFrom(dplyr,bind_rows) diff --git a/R/admiralmetabolic-package.R b/R/admiralmetabolic-package.R index 19aef39..ab492e5 100644 --- a/R/admiralmetabolic-package.R +++ b/R/admiralmetabolic-package.R @@ -20,9 +20,8 @@ #' time_length %--% ymd ymd_hms weeks years hours minutes #' @importFrom tidyselect all_of contains vars_select #' @importFrom lifecycle deprecate_warn deprecated deprecate_stop -#' @importFrom checkmate assert_true #' @importFrom admiraldev assert_numeric_vector assert_character_scalar assert_logical_scalar #' assert_data_frame assert_vars assert_varval_list assert_filter_cond #' assert_param_does_not_exist -#' @importFrom admiral derive_param_computed +#' @importFrom admiral derive_param_ratio "_PACKAGE" diff --git a/R/derive_advs_params.R b/R/derive_advs_params.R index eaee1e6..5435b50 100644 --- a/R/derive_advs_params.R +++ b/R/derive_advs_params.R @@ -3,7 +3,7 @@ #' @description Adds a record for Waist-to-Hip Ratio using Waist Circumference and Hip Circumference #' each by group (e.g., subject and visit) where the source parameters are available. #' -#' **Note:** This is a wrapper function for the more generic \code{derive_param_ratio()}. +#' **Note:** This is a wrapper function for the more generic \code{admiral::derive_param_ratio()}. #' #' @param dataset Input dataset #' @@ -28,7 +28,7 @@ #' #' *Permitted Values:* character value #' -#' @inheritParams derive_param_ratio +#' @inheritParams admiral::derive_param_ratio #' #' @details #' The analysis value of the new parameter is derived as @@ -40,11 +40,13 @@ #' #' @export #' -#' @seealso \code{\link[=derive_param_ratio]{derive_param_ratio()}}, -#' \code{\link[=compute_ratio]{compute_ratio()}} +#' @seealso \code{\link[=admiral::derive_param_ratio]{admiral::derive_param_ratio()}}, +#' \code{\link[=admiral::compute_ratio]{admiral::compute_ratio()}} #' #' @examples #' +#' library(tibble) +#' #' advs <- tribble( #' ~USUBJID, ~PARAMCD, ~PARAM, ~AVAL, ~AVALU, ~VISIT, #' "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 110, "cm", "SCREENING", @@ -85,7 +87,7 @@ derive_param_waisthip <- function(dataset, assert_param_does_not_exist(dataset, set_values_to$PARAMCD) filter <- assert_filter_cond(enexpr(filter), optional = TRUE) - derive_param_ratio( + admiral::derive_param_ratio( dataset, filter = !!filter, dividend_code = wstcir_code, @@ -100,7 +102,7 @@ derive_param_waisthip <- function(dataset, #' @description Adds a record for Waist-to-Height Ratio using Waist Circumference and Height #' each by group (e.g., subject and visit) where the source parameters are available. #' -#' **Note:** This is a wrapper function for the more generic \code{derive_param_ratio()}. +#' **Note:** This is a wrapper function for the more generic \code{admiral::derive_param_ratio()}. #' #' @param dataset Input dataset #' @@ -139,7 +141,7 @@ derive_param_waisthip <- function(dataset, #' *Permitted Values*: list of variables created by \code{exprs()} #' e.g. \code{exprs(USUBJID, VISIT)} #' -#' @inheritParams derive_param_ratio +#' @inheritParams admiral::derive_param_ratio #' #' @details #' The analysis value of the new parameter is derived as @@ -151,11 +153,13 @@ derive_param_waisthip <- function(dataset, #' #' @export #' -#' @seealso \code{\link[=derive_param_ratio]{derive_param_ratio()}}, -#' \code{\link[=compute_ratio]{compute_ratio()}} +#' @seealso \code{\link[=admiral::derive_param_ratio]{admiral::derive_param_ratio()}}, +#' \code{\link[=admiral::compute_ratio]{admiral::compute_ratio()}} #' #' @examples #' +#' library(tibble) +#' #' # Example 1: Derive Waist-to-Height Ratio where Height is measured only once #' #' advs <- tribble( @@ -226,7 +230,7 @@ derive_param_waisthgt <- function(dataset, filter <- assert_filter_cond(enexpr(filter), optional = TRUE) assert_vars(constant_by_vars, optional = TRUE) - derive_param_ratio( + admiral::derive_param_ratio( dataset, filter = !!filter, dividend_code = wstcir_code, diff --git a/R/derive_bds_params.R b/R/derive_bds_params.R deleted file mode 100644 index 6e82a5c..0000000 --- a/R/derive_bds_params.R +++ /dev/null @@ -1,237 +0,0 @@ -#' Adds a Ratio Parameter Computed from the Analysis Value of Other Parameters -#' -#' @description Adds a record for a generic Ratio parameter using two existing parameter -#' (dividend and divisor) each by group (e.g., subject and visit) where the source parameters -#' are available. -#' -#' **Note:** This is a wrapper function for the more generic \code{admiral::derive_param_computed()} -#' -#' @param dataset Input dataset -#' -#' The variables specified by the \code{by_vars} argument are expected to be in the dataset. -#' \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} -#' parameter) and to the parameters specified by \code{dividend_code} and \code{divisor_code}. -#' -#' @param dividend_code Dividend parameter code -#' -#' The observations where \code{PARAMCD} equals the specified value are considered -#' as the dividend -#' -#' *Permitted Values:* character value -#' -#' @param divisor_code Divisor parameter code -#' -#' The observations where \code{PARAMCD} equals the specified value are considered -#' as the divisor -#' -#' *Permitted Values:* character value -#' -#' @param constant_dividend Is dividend parameter constant? -#' -#' It is expected that the parameter code (PARAMCD) specified in \code{dividend_code} -#' which is required to derive the new parameter is measured only once. For example, -#' if Height-to-Weight Ratio should be derived and height is measured only once -#' while Weight is measured at each visit. Height could be specified -#' in the \code{dividend_code} argument and \code{constant_dividend} is to be set to \code{TRUE}. -#' -#' *Permitted Values:* logical scalar -#' -#' @param constant_divisor Is divisor parameter constant? -#' -#' It is expected that the parameter code (PARAMCD) specified in \code{dividend_code} -#' which is required to derive the new parameter is measured only once. For example, -#' if Waist-to-Height Ratio should be derived and height is measured only once -#' while Waist Circumference is measured at each visit. Height could be specified -#' in the \code{divisor_code} argument and \code{constant_divisor} is to be set to \code{TRUE}. -#' -#' *Permitted Values:* logical scalar -#' -#' @param constant_by_vars By variables for when dividend and/or divisor is constant -#' -#' When dividend and/or divisor is constant, the parameters (measured only once) are merged -#' to the other parameters using the specified variables. -#' -#' If dividend and/or divisor is constant (e.g. only measured once at screening or baseline) -#' then use \code{constant_by_vars} to select the subject-level variable to merge on -#' (e.g. \code{USUBJID}). This will produce a generic Ratio parameter at all visits where dividend -#' and/or divisor is measured. Otherwise it will only be calculated at visits with both dividend -#' and divisor parameters collected. -#' -#' *Permitted Values*: list of variables created by \code{exprs()} -#' e.g. \code{exprs(USUBJID, VISIT)} -#' -#' @inheritParams admiral::derive_param_bmi -#' -#' @details -#' The analysis value of the new parameter is derived as -#' \deqn{RATIO = \frac{DIVIDENT}{DIVISOR}} -#' -#' -#' @return The input dataset with the new parameter added. Note, a variable will only -#' be populated in the new parameter rows if it is specified in \code{by_vars}. -#' -#' @export -#' -#' @seealso \code{\link[=compute_ratio]{compute_ratio()}} -#' -#' @examples -#' -#' # Example 1: Derive Waist-to-Hip Ratio where both source parameters are measured multiple times -#' -#' advs <- tribble( -#' ~USUBJID, ~PARAMCD, ~PARAM, ~AVAL, ~AVALU, ~VISIT, -#' "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 125, "cm", "SCREENING", -#' "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 124, "cm", "WEEK 2", -#' "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 123, "cm", "WEEK 3", -#' "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 110, "cm", "SCREENING", -#' "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 108, "cm", "WEEK 2", -#' "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 107, "cm", "WEEK 3", -#' "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 135, "cm", "SCREENING", -#' "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 133, "cm", "WEEK 2", -#' "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 132, "cm", "WEEK 3", -#' "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 120, "cm", "SCREENING", -#' "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 118, "cm", "WEEK 2", -#' "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 117, "cm", "WEEK 3" -#' ) -#' -#' derive_param_ratio( -#' advs, -#' by_vars = exprs(USUBJID, VISIT), -#' dividend_code = "WSTCIR", -#' divisor_code = "HIPCIR", -#' set_values_to = exprs( -#' PARAMCD = "WAISTHIP", -#' PARAM = "Waist-to-Hip Ratio" -#' ) -#' ) -#' -#' # Example 2: Derive Waist-to-Height Ratio where Height is measured only once -#' -#' advs <- tribble( -#' ~USUBJID, ~PARAMCD, ~PARAM, ~AVAL, ~AVALU, ~VISIT, -#' "01-101-1001", "HEIGHT", "Height (cm)", 147, "cm", "SCREENING", -#' "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 110, "cm", "SCREENING", -#' "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 108, "cm", "WEEK 2", -#' "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 107, "cm", "WEEK 3", -#' "01-101-1002", "HEIGHT", "Height (cm)", 163, "cm", "SCREENING", -#' "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 120, "cm", "SCREENING", -#' "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 118, "cm", "WEEK 2", -#' "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 117, "cm", "WEEK 3", -#' ) -#' -#' derive_param_ratio( -#' advs, -#' by_vars = exprs(USUBJID, VISIT), -#' dividend_code = "WSTCIR", -#' divisor_code = "HEIGHT", -#' set_values_to = exprs( -#' PARAMCD = "WAISTHGT", -#' PARAM = "Waist-to-Height Ratio" -#' ), -#' constant_divisor = TRUE, -#' constant_by_vars = exprs(USUBJID) -#' ) -derive_param_ratio <- function(dataset, - by_vars, - dividend_code, - divisor_code, - set_values_to, - constant_dividend = FALSE, - constant_divisor = FALSE, - filter = NULL, - constant_by_vars = NULL) { - assert_vars(by_vars) - assert_data_frame(dataset, required_vars = exprs(!!!by_vars, PARAMCD, AVAL)) - assert_character_scalar(dividend_code) - assert_character_scalar(divisor_code) - assert_varval_list(set_values_to, required_elements = "PARAMCD") - assert_param_does_not_exist(dataset, set_values_to$PARAMCD) - filter <- assert_filter_cond(enexpr(filter), optional = TRUE) - assert_logical_scalar(constant_dividend) - assert_logical_scalar(constant_divisor) - assert_vars(constant_by_vars, optional = TRUE) - - ratio_formula <- expr( - compute_ratio( - x = !!sym(paste0("AVAL.", dividend_code)), - y = !!sym(paste0("AVAL.", divisor_code)) - ) - ) - - parameters <- c(dividend_code, divisor_code) - constant_parameters <- NULL - - if (constant_dividend) { - constant_parameters <- c(constant_parameters, dividend_code) - - parameters <- parameters %>% - .[!. == dividend_code] - } - - if (constant_divisor) { - constant_parameters <- c(constant_parameters, divisor_code) - - parameters <- parameters %>% - .[!. == divisor_code] %>% - ifelse(length(.) == 0, NULL, .) - } - - derive_param_computed( - dataset, - filter = !!filter, - parameters = parameters, - by_vars = by_vars, - set_values_to = exprs( - AVAL = !!ratio_formula, - !!!set_values_to - ), - constant_parameters = constant_parameters, - constant_by_vars = constant_by_vars - ) -} - -#' Compute ratio -#' -#' Computes ratio as dividend (x) divided by divisor (y) -#' -#' @param x Dividend -#' -#' *Permitted Values:* numeric vector -#' -#' @param y Divisor -#' -#' *Permitted Values:* numeric vector -#' -#' -#' @details -#' \code{x} and \code{y} must be of the same length. -#' -#' If the divisor equals 0, the result will be NA. -#' -#' Usually this computation function can not be used with \code{%>%}. -#' -#' @return The ratio computed as x / y. -#' -#' @export -#' -#' @seealso \code{\link[=derive_param_ratio]{derive_param_ratio()}}, -#' \code{\link[=derive_param_waisthip]{derive_param_waisthip()}}, -#' \code{\link[=derive_param_waisthgt]{derive_param_waisthgt()}} -#' -#' @examples -#' -#' # Example of Waist-to-Height Ratio where -#' # Waist Circumference is 120 cm -#' # and Height is 163 cm -#' -#' compute_ratio(x = 120, y = 163) -compute_ratio <- function(x, y) { - assert_numeric_vector(x) - assert_numeric_vector(y) - assert_true(length(x) == length(y)) - - if_else(y == 0, NA_real_, x / y) -} diff --git a/man/compute_ratio.Rd b/man/compute_ratio.Rd deleted file mode 100644 index 2a44586..0000000 --- a/man/compute_ratio.Rd +++ /dev/null @@ -1,43 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/derive_bds_params.R -\name{compute_ratio} -\alias{compute_ratio} -\title{Compute ratio} -\usage{ -compute_ratio(x, y) -} -\arguments{ -\item{x}{Dividend - -\emph{Permitted Values:} numeric vector} - -\item{y}{Divisor - -\emph{Permitted Values:} numeric vector} -} -\value{ -The ratio computed as x / y. -} -\description{ -Computes ratio as dividend (x) divided by divisor (y) -} -\details{ -\code{x} and \code{y} must be of the same length. - -If the divisor equals 0, the result will be NA. - -Usually this computation function can not be used with \code{\%>\%}. -} -\examples{ - -# Example of Waist-to-Height Ratio where -# Waist Circumference is 120 cm -# and Height is 163 cm - -compute_ratio(x = 120, y = 163) -} -\seealso{ -\code{\link[=derive_param_ratio]{derive_param_ratio()}}, -\code{\link[=derive_param_waisthip]{derive_param_waisthip()}}, -\code{\link[=derive_param_waisthgt]{derive_param_waisthgt()}} -} diff --git a/man/derive_param_ratio.Rd b/man/derive_param_ratio.Rd deleted file mode 100644 index ea67813..0000000 --- a/man/derive_param_ratio.Rd +++ /dev/null @@ -1,177 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/derive_bds_params.R -\name{derive_param_ratio} -\alias{derive_param_ratio} -\title{Adds a Ratio Parameter Computed from the Analysis Value of Other Parameters} -\usage{ -derive_param_ratio( - dataset, - by_vars, - dividend_code, - divisor_code, - set_values_to, - constant_dividend = FALSE, - constant_divisor = FALSE, - filter = NULL, - constant_by_vars = NULL -) -} -\arguments{ -\item{dataset}{Input dataset - -The variables specified by the \code{by_vars} argument are expected to be in the dataset. -\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} -parameter) and to the parameters specified by \code{dividend_code} and \code{divisor_code}.} - -\item{by_vars}{Grouping variables - -For each group defined by \code{by_vars} an observation is added to the output -dataset. Only variables specified in \code{by_vars} will be populated -in the newly created records. - -\emph{Permitted Values}: list of variables created by \code{exprs()} -e.g. \code{exprs(USUBJID, VISIT)}} - -\item{dividend_code}{Dividend parameter code - -The observations where \code{PARAMCD} equals the specified value are considered -as the dividend - -\emph{Permitted Values:} character value} - -\item{divisor_code}{Divisor parameter code - -The observations where \code{PARAMCD} equals the specified value are considered -as the divisor - -\emph{Permitted Values:} character value} - -\item{set_values_to}{Variables to be set - -The specified variables are set to the specified values for the new -observations. For example \code{exprs(PARAMCD = "MAP")} defines the parameter code -for the new parameter. - -\emph{Permitted Values}: List of variable-value pairs} - -\item{constant_dividend}{Is dividend parameter constant? - -It is expected that the parameter code (PARAMCD) specified in \code{dividend_code} -which is required to derive the new parameter is measured only once. For example, -if Height-to-Weight Ratio should be derived and height is measured only once -while Weight is measured at each visit. Height could be specified -in the \code{dividend_code} argument and \code{constant_dividend} is to be set to \code{TRUE}. - -\emph{Permitted Values:} logical scalar} - -\item{constant_divisor}{Is divisor parameter constant? - -It is expected that the parameter code (PARAMCD) specified in \code{dividend_code} -which is required to derive the new parameter is measured only once. For example, -if Waist-to-Height Ratio should be derived and height is measured only once -while Waist Circumference is measured at each visit. Height could be specified -in the \code{divisor_code} argument and \code{constant_divisor} is to be set to \code{TRUE}. - -\emph{Permitted Values:} logical scalar} - -\item{filter}{Filter condition - -The specified condition is applied to the input dataset before deriving the -new parameter, i.e., only observations fulfilling the condition are taken -into account. - -\emph{Permitted Values:} a condition} - -\item{constant_by_vars}{By variables for when dividend and/or divisor is constant - -When dividend and/or divisor is constant, the parameters (measured only once) are merged -to the other parameters using the specified variables. - -If dividend and/or divisor is constant (e.g. only measured once at screening or baseline) -then use \code{constant_by_vars} to select the subject-level variable to merge on -(e.g. \code{USUBJID}). This will produce a generic Ratio parameter at all visits where dividend -and/or divisor is measured. Otherwise it will only be calculated at visits with both dividend -and divisor parameters collected. - -\emph{Permitted Values}: list of variables created by \code{exprs()} -e.g. \code{exprs(USUBJID, VISIT)}} -} -\value{ -The input dataset with the new parameter added. Note, a variable will only -be populated in the new parameter rows if it is specified in \code{by_vars}. -} -\description{ -Adds a record for a generic Ratio parameter using two existing parameter -(dividend and divisor) each by group (e.g., subject and visit) where the source parameters -are available. - -\strong{Note:} This is a wrapper function for the more generic \code{admiral::derive_param_computed()} -} -\details{ -The analysis value of the new parameter is derived as -\deqn{RATIO = \frac{DIVIDENT}{DIVISOR}} -} -\examples{ - -# Example 1: Derive Waist-to-Hip Ratio where both source parameters are measured multiple times - -advs <- tribble( - ~USUBJID, ~PARAMCD, ~PARAM, ~AVAL, ~AVALU, ~VISIT, - "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 125, "cm", "SCREENING", - "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 124, "cm", "WEEK 2", - "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 123, "cm", "WEEK 3", - "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 110, "cm", "SCREENING", - "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 108, "cm", "WEEK 2", - "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 107, "cm", "WEEK 3", - "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 135, "cm", "SCREENING", - "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 133, "cm", "WEEK 2", - "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 132, "cm", "WEEK 3", - "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 120, "cm", "SCREENING", - "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 118, "cm", "WEEK 2", - "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 117, "cm", "WEEK 3" -) - -derive_param_ratio( - advs, - by_vars = exprs(USUBJID, VISIT), - dividend_code = "WSTCIR", - divisor_code = "HIPCIR", - set_values_to = exprs( - PARAMCD = "WAISTHIP", - PARAM = "Waist-to-Hip Ratio" - ) -) - -# Example 2: Derive Waist-to-Height Ratio where Height is measured only once - -advs <- tribble( - ~USUBJID, ~PARAMCD, ~PARAM, ~AVAL, ~AVALU, ~VISIT, - "01-101-1001", "HEIGHT", "Height (cm)", 147, "cm", "SCREENING", - "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 110, "cm", "SCREENING", - "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 108, "cm", "WEEK 2", - "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 107, "cm", "WEEK 3", - "01-101-1002", "HEIGHT", "Height (cm)", 163, "cm", "SCREENING", - "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 120, "cm", "SCREENING", - "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 118, "cm", "WEEK 2", - "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 117, "cm", "WEEK 3", -) - -derive_param_ratio( - advs, - by_vars = exprs(USUBJID, VISIT), - dividend_code = "WSTCIR", - divisor_code = "HEIGHT", - set_values_to = exprs( - PARAMCD = "WAISTHGT", - PARAM = "Waist-to-Height Ratio" - ), - constant_divisor = TRUE, - constant_by_vars = exprs(USUBJID) -) -} -\seealso{ -\code{\link[=compute_ratio]{compute_ratio()}} -} diff --git a/man/derive_param_waisthgt.Rd b/man/derive_param_waisthgt.Rd index 069612e..8fc7c8e 100644 --- a/man/derive_param_waisthgt.Rd +++ b/man/derive_param_waisthgt.Rd @@ -85,7 +85,7 @@ be populated in the new parameter rows if it is specified in \code{by_vars}. Adds a record for Waist-to-Height Ratio using Waist Circumference and Height each by group (e.g., subject and visit) where the source parameters are available. -\strong{Note:} This is a wrapper function for the more generic \code{derive_param_ratio()}. +\strong{Note:} This is a wrapper function for the more generic \code{admiral::derive_param_ratio()}. } \details{ The analysis value of the new parameter is derived as @@ -93,6 +93,8 @@ The analysis value of the new parameter is derived as } \examples{ +library(tibble) + # Example 1: Derive Waist-to-Height Ratio where Height is measured only once advs <- tribble( @@ -149,6 +151,6 @@ derive_param_waisthgt( ) } \seealso{ -\code{\link[=derive_param_ratio]{derive_param_ratio()}}, -\code{\link[=compute_ratio]{compute_ratio()}} +\code{\link[=admiral::derive_param_ratio]{admiral::derive_param_ratio()}}, +\code{\link[=admiral::compute_ratio]{admiral::compute_ratio()}} } diff --git a/man/derive_param_waisthip.Rd b/man/derive_param_waisthip.Rd index 25ef238..ab9037d 100644 --- a/man/derive_param_waisthip.Rd +++ b/man/derive_param_waisthip.Rd @@ -70,7 +70,7 @@ be populated in the new parameter rows if it is specified in \code{by_vars}. Adds a record for Waist-to-Hip Ratio using Waist Circumference and Hip Circumference each by group (e.g., subject and visit) where the source parameters are available. -\strong{Note:} This is a wrapper function for the more generic \code{derive_param_ratio()}. +\strong{Note:} This is a wrapper function for the more generic \code{admiral::derive_param_ratio()}. } \details{ The analysis value of the new parameter is derived as @@ -78,6 +78,8 @@ The analysis value of the new parameter is derived as } \examples{ +library(tibble) + advs <- tribble( ~USUBJID, ~PARAMCD, ~PARAM, ~AVAL, ~AVALU, ~VISIT, "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 110, "cm", "SCREENING", @@ -106,6 +108,6 @@ derive_param_waisthip( ) } \seealso{ -\code{\link[=derive_param_ratio]{derive_param_ratio()}}, -\code{\link[=compute_ratio]{compute_ratio()}} +\code{\link[=admiral::derive_param_ratio]{admiral::derive_param_ratio()}}, +\code{\link[=admiral::compute_ratio]{admiral::compute_ratio()}} } diff --git a/tests/testthat/test-compute_ratio.R b/tests/testthat/test-compute_ratio.R deleted file mode 100644 index 7877dba..0000000 --- a/tests/testthat/test-compute_ratio.R +++ /dev/null @@ -1,39 +0,0 @@ -test_that("compute_ratio Test 1: Basic", { - expect_equal( - compute_ratio( - x = c(182, 50.25), - y = c(91, 201) - ), - c(2, 0.25) - ) -}) - -test_that("compute_ratio Test 2: Negatives", { - expect_equal( - compute_ratio( - x = c(-63.9, 100), - y = c(21.3, -40) - ), - c(-3, -2.5) - ) -}) - -test_that("compute_ratio Test 3: Zeros", { - expect_equal( - compute_ratio( - x = c(0, 95, 0), - y = c(75, 0, 0) - ), - c(0, NA_real_, NA_real_) - ) -}) - -test_that("compute_ratio Test 4: NAs", { - expect_equal( - compute_ratio( - x = c(44, NA, NA), - y = c(NA, 140, NA) - ), - c(NA_real_, NA_real_, NA_real_) - ) -}) From 8753a7364d5d71d0b008b0f5f0e0d5767ae68eb1 Mon Sep 17 00:00:00 2001 From: Andrii Yurovskyi Date: Thu, 10 Oct 2024 01:49:47 +0200 Subject: [PATCH 05/28] #31 Get derive_param_ratio back as not exported --- DESCRIPTION | 1 + NAMESPACE | 6 +- R/admiralmetabolic-package.R | 13 +- R/derive_advs_params.R | 34 +++-- R/derive_bds_params.R | 132 ++++++++++++++++++++ _pkgdown.yml | 1 + man/admiralmetabolic-package.Rd | 3 + man/derive_param_ratio.Rd | 122 ++++++++++++++++++ man/derive_param_waisthgt.Rd | 16 ++- man/derive_param_waisthip.Rd | 14 ++- tests/testthat/test-derive_param_waisthgt.R | 94 ++++++++++++++ tests/testthat/test-derive_param_waisthip.R | 46 +++++++ 12 files changed, 453 insertions(+), 29 deletions(-) create mode 100644 R/derive_bds_params.R create mode 100644 man/derive_param_ratio.Rd create mode 100644 tests/testthat/test-derive_param_waisthgt.R create mode 100644 tests/testthat/test-derive_param_waisthip.R diff --git a/DESCRIPTION b/DESCRIPTION index 67fa74f..31ddf54 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -24,6 +24,7 @@ Depends: Imports: admiral (>= 1.1.1), admiraldev (>= 1.0.0), + cli (>= 3.6.2), dplyr (>= 0.8.4), stringr (>= 1.4.0), lifecycle (>= 0.1.0), diff --git a/NAMESPACE b/NAMESPACE index ef87812..55e3196 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -3,7 +3,7 @@ export(derive_param_waisthgt) export(derive_param_waisthip) export(hello_admiral) -importFrom(admiral,derive_param_ratio) +importFrom(admiral,derive_param_computed) importFrom(admiraldev,assert_character_scalar) importFrom(admiraldev,assert_data_frame) importFrom(admiraldev,assert_filter_cond) @@ -12,6 +12,8 @@ importFrom(admiraldev,assert_numeric_vector) importFrom(admiraldev,assert_param_does_not_exist) importFrom(admiraldev,assert_vars) importFrom(admiraldev,assert_varval_list) +importFrom(admiraldev,expect_dfs_equal) +importFrom(cli,cli_abort) importFrom(dplyr,arrange) importFrom(dplyr,bind_cols) importFrom(dplyr,bind_rows) @@ -41,6 +43,7 @@ importFrom(dplyr,summarise) importFrom(dplyr,summarise_at) importFrom(dplyr,tibble) importFrom(dplyr,transmute) +importFrom(dplyr,tribble) importFrom(dplyr,ungroup) importFrom(dplyr,union) importFrom(dplyr,vars) @@ -75,6 +78,7 @@ importFrom(rlang,call_name) importFrom(rlang,caller_env) importFrom(rlang,current_env) importFrom(rlang,enexpr) +importFrom(rlang,enexprs) importFrom(rlang,enquo) importFrom(rlang,eval_bare) importFrom(rlang,eval_tidy) diff --git a/R/admiralmetabolic-package.R b/R/admiralmetabolic-package.R index ab492e5..ec95354 100644 --- a/R/admiralmetabolic-package.R +++ b/R/admiralmetabolic-package.R @@ -1,12 +1,17 @@ #' @keywords internal #' @family internal +#' @importFrom admiraldev assert_numeric_vector assert_character_scalar assert_logical_scalar +#' assert_data_frame assert_vars assert_varval_list assert_filter_cond +#' assert_param_does_not_exist expect_dfs_equal +#' @importFrom admiral derive_param_computed +#' @importFrom cli cli_abort #' @importFrom dplyr arrange bind_rows case_when desc ends_with filter full_join group_by #' if_else mutate mutate_at mutate_if n pull rename rename_at row_number select slice #' starts_with transmute ungroup vars n_distinct union distinct -#' summarise_at summarise coalesce bind_cols na_if tibble +#' summarise_at summarise coalesce bind_cols na_if tibble tribble #' @importFrom magrittr %>% #' @importFrom rlang := abort arg_match as_function as_string call2 caller_env -#' call_name current_env .data enexpr enquo eval_bare eval_tidy expr +#' call_name current_env .data enexpr enexprs enquo eval_bare eval_tidy expr #' exprs expr_interp expr_label f_lhs f_rhs inform #' is_bare_formula is_call is_character is_formula is_integerish #' is_logical is_quosure is_quosures is_symbol new_formula @@ -20,8 +25,4 @@ #' time_length %--% ymd ymd_hms weeks years hours minutes #' @importFrom tidyselect all_of contains vars_select #' @importFrom lifecycle deprecate_warn deprecated deprecate_stop -#' @importFrom admiraldev assert_numeric_vector assert_character_scalar assert_logical_scalar -#' assert_data_frame assert_vars assert_varval_list assert_filter_cond -#' assert_param_does_not_exist -#' @importFrom admiral derive_param_ratio "_PACKAGE" diff --git a/R/derive_advs_params.R b/R/derive_advs_params.R index 5435b50..de81d48 100644 --- a/R/derive_advs_params.R +++ b/R/derive_advs_params.R @@ -3,7 +3,8 @@ #' @description Adds a record for Waist-to-Hip Ratio using Waist Circumference and Hip Circumference #' each by group (e.g., subject and visit) where the source parameters are available. #' -#' **Note:** This is a wrapper function for the more generic \code{admiral::derive_param_ratio()}. +#' **Note:** This is a wrapper function for the more generic +#' \code{admiral::derive_param_computed()}. #' #' @param dataset Input dataset #' @@ -28,24 +29,27 @@ #' #' *Permitted Values:* character value #' -#' @inheritParams admiral::derive_param_ratio +#' @inheritParams derive_param_ratio #' #' @details #' The analysis value of the new parameter is derived as -#' \deqn{WAISTHIP = \frac{WSTCIR}{HIPCIR}} +#' \deqn{WAISTHIP = \frac{WSTCIR}{HIPCIR}}{WAISTHIP = WSTCIR / HIPCIR} #' #' #' @return The input dataset with the new parameter added. Note, a variable will only #' be populated in the new parameter rows if it is specified in \code{by_vars}. #' +#' @family der_prm_adxx +#' @keywords der_prm_adxx +#' #' @export #' -#' @seealso \code{\link[=admiral::derive_param_ratio]{admiral::derive_param_ratio()}}, -#' \code{\link[=admiral::compute_ratio]{admiral::compute_ratio()}} +#' @seealso \code{\link[admiral:derive_param_computed]{admiral::derive_param_computed()}} #' #' @examples #' #' library(tibble) +#' library(rlang) #' #' advs <- tribble( #' ~USUBJID, ~PARAMCD, ~PARAM, ~AVAL, ~AVALU, ~VISIT, @@ -87,7 +91,7 @@ derive_param_waisthip <- function(dataset, assert_param_does_not_exist(dataset, set_values_to$PARAMCD) filter <- assert_filter_cond(enexpr(filter), optional = TRUE) - admiral::derive_param_ratio( + derive_param_ratio( dataset, filter = !!filter, dividend_code = wstcir_code, @@ -102,7 +106,8 @@ derive_param_waisthip <- function(dataset, #' @description Adds a record for Waist-to-Height Ratio using Waist Circumference and Height #' each by group (e.g., subject and visit) where the source parameters are available. #' -#' **Note:** This is a wrapper function for the more generic \code{admiral::derive_param_ratio()}. +#' **Note:** This is a wrapper function for the more generic +#' \code{admiral::derive_param_computed()}. #' #' @param dataset Input dataset #' @@ -141,24 +146,27 @@ derive_param_waisthip <- function(dataset, #' *Permitted Values*: list of variables created by \code{exprs()} #' e.g. \code{exprs(USUBJID, VISIT)} #' -#' @inheritParams admiral::derive_param_ratio +#' @inheritParams derive_param_ratio #' #' @details #' The analysis value of the new parameter is derived as -#' \deqn{WAISTHGT = \frac{WSTCIR}{HEIGHT}} +#' \deqn{WAISTHGT = \frac{WSTCIR}{HEIGHT}}{WAISTHGT = WSTCIR / HEIGHT} #' #' #' @return The input dataset with the new parameter added. Note, a variable will only #' be populated in the new parameter rows if it is specified in \code{by_vars}. #' +#' @family der_prm_adxx +#' @keywords der_prm_adxx +#' #' @export #' -#' @seealso \code{\link[=admiral::derive_param_ratio]{admiral::derive_param_ratio()}}, -#' \code{\link[=admiral::compute_ratio]{admiral::compute_ratio()}} +#' @seealso \code{\link[admiral:derive_param_computed]{admiral::derive_param_computed()}} #' #' @examples #' #' library(tibble) +#' library(rlang) #' #' # Example 1: Derive Waist-to-Height Ratio where Height is measured only once #' @@ -217,7 +225,7 @@ derive_param_waisthip <- function(dataset, derive_param_waisthgt <- function(dataset, by_vars, wstcir_code = "WSTCIR", - height_code = "HGHT", + height_code = "HEIGHT", set_values_to = exprs(PARAMCD = "WAISTHGT"), filter = NULL, constant_by_vars = NULL) { @@ -230,7 +238,7 @@ derive_param_waisthgt <- function(dataset, filter <- assert_filter_cond(enexpr(filter), optional = TRUE) assert_vars(constant_by_vars, optional = TRUE) - admiral::derive_param_ratio( + derive_param_ratio( dataset, filter = !!filter, dividend_code = wstcir_code, diff --git a/R/derive_bds_params.R b/R/derive_bds_params.R new file mode 100644 index 0000000..cb6eae9 --- /dev/null +++ b/R/derive_bds_params.R @@ -0,0 +1,132 @@ +#' Adds a Ratio Parameter Computed from the Analysis Value of Other Parameters +#' +#' @description Adds a record for a generic Ratio parameter using two existing parameter +#' (dividend and divisor) each by group (e.g., subject and visit) where the source parameters +#' are available. +#' +#' **Note:** This is a wrapper function for the more generic \code{derive_param_computed()} +#' +#' @param dataset Input dataset +#' +#' The variables specified by the \code{by_vars} argument are expected to be in the dataset. +#' \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} +#' parameter) and to the parameters specified by \code{dividend_code} and \code{divisor_code}. +#' +#' @param dividend_code Dividend parameter code +#' +#' The observations where \code{PARAMCD} equals the specified value are considered +#' as the dividend +#' +#' *Permitted Values:* character value +#' +#' @param divisor_code Divisor parameter code +#' +#' The observations where \code{PARAMCD} equals the specified value are considered +#' as the divisor +#' +#' *Permitted Values:* character value +#' +#' @param constant_dividend Is dividend parameter constant? +#' +#' It is expected that the parameter code (PARAMCD) specified in \code{dividend_code} +#' which is required to derive the new parameter is measured only once. For example, +#' if Height-to-Weight Ratio should be derived and height is measured only once +#' while Weight is measured at each visit. Height could be specified +#' in the \code{dividend_code} argument and \code{constant_dividend} is to be set to \code{TRUE}. +#' +#' *Permitted Values:* logical scalar +#' +#' @param constant_divisor Is divisor parameter constant? +#' +#' It is expected that the parameter code (PARAMCD) specified in \code{dividend_code} +#' which is required to derive the new parameter is measured only once. For example, +#' if Waist-to-Height Ratio should be derived and height is measured only once +#' while Waist Circumference is measured at each visit. Height could be specified +#' in the \code{divisor_code} argument and \code{constant_divisor} is to be set to \code{TRUE}. +#' +#' *Permitted Values:* logical scalar +#' +#' @param constant_by_vars By variables for when dividend and/or divisor is constant +#' +#' When dividend and/or divisor is constant, the parameters (measured only once) are merged +#' to the other parameters using the specified variables. +#' +#' If dividend and/or divisor is constant (e.g. only measured once at screening or baseline) +#' then use \code{constant_by_vars} to select the subject-level variable to merge on +#' (e.g. \code{USUBJID}). This will produce a generic Ratio parameter at all visits where dividend +#' and/or divisor is measured. Otherwise it will only be calculated at visits with both dividend +#' and divisor parameters collected. +#' +#' *Permitted Values*: list of variables created by \code{exprs()} +#' e.g. \code{exprs(USUBJID, VISIT)} +#' +#' @inheritParams admiral::derive_param_bmi +#' +#' @details +#' The analysis value of the new parameter is derived as +#' \deqn{RATIO = \frac{DIVIDENT}{DIVISOR}} +#' +#' +#' @return The input dataset with the new parameter added. Note, a variable will only +#' be populated in the new parameter rows if it is specified in \code{by_vars}. +#' +#' @family internal +#' @keywords internal +derive_param_ratio <- function(dataset, + by_vars, + dividend_code, + divisor_code, + set_values_to, + constant_dividend = FALSE, + constant_divisor = FALSE, + filter = NULL, + constant_by_vars = NULL) { + assert_vars(by_vars) + assert_data_frame(dataset, required_vars = exprs(!!!by_vars, PARAMCD, AVAL)) + assert_character_scalar(dividend_code) + assert_character_scalar(divisor_code) + assert_varval_list(set_values_to, required_elements = "PARAMCD") + assert_param_does_not_exist(dataset, set_values_to$PARAMCD) + filter <- assert_filter_cond(enexpr(filter), optional = TRUE) + assert_logical_scalar(constant_dividend) + assert_logical_scalar(constant_divisor) + assert_vars(constant_by_vars, optional = TRUE) + + ratio_formula <- expr( + !!sym(paste0("AVAL.", dividend_code)) / !!sym(paste0("AVAL.", divisor_code)) + ) + + parameters <- c(dividend_code, divisor_code) + constant_parameters <- NULL + + if (constant_dividend) { + constant_parameters <- c(constant_parameters, dividend_code) + + parameters <- parameters %>% + .[!. == dividend_code] + } + + if (constant_divisor) { + constant_parameters <- c(constant_parameters, divisor_code) + + parameters <- parameters %>% + .[!. == divisor_code] %>% + ifelse(length(.) == 0, NULL, .) + } + + derive_param_computed( + dataset, + filter = !!filter, + parameters = parameters, + by_vars = by_vars, + set_values_to = exprs( + AVAL = !!ratio_formula, + !!!set_values_to + ), + constant_parameters = constant_parameters, + constant_by_vars = constant_by_vars + ) +} diff --git a/_pkgdown.yml b/_pkgdown.yml index b409e9b..158aade 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -2,6 +2,7 @@ url: https://pharmaverse.github.io/admiralmetabolic template: bootstrap: 5 + math-rendering: mathjax params: bootswatch: flatly repo: diff --git a/man/admiralmetabolic-package.Rd b/man/admiralmetabolic-package.Rd index 8fc799c..804d819 100644 --- a/man/admiralmetabolic-package.Rd +++ b/man/admiralmetabolic-package.Rd @@ -17,6 +17,9 @@ Useful links: \item \url{https://github.com/pharmaverse/admiraltemplate} } + +Other internal: +\code{\link{derive_param_ratio}()} } \author{ \strong{Maintainer}: Edoardo Mancini \email{edoardo.mancini@roche.com} diff --git a/man/derive_param_ratio.Rd b/man/derive_param_ratio.Rd new file mode 100644 index 0000000..67f5387 --- /dev/null +++ b/man/derive_param_ratio.Rd @@ -0,0 +1,122 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/derive_bds_params.R +\name{derive_param_ratio} +\alias{derive_param_ratio} +\title{Adds a Ratio Parameter Computed from the Analysis Value of Other Parameters} +\usage{ +derive_param_ratio( + dataset, + by_vars, + dividend_code, + divisor_code, + set_values_to, + constant_dividend = FALSE, + constant_divisor = FALSE, + filter = NULL, + constant_by_vars = NULL +) +} +\arguments{ +\item{dataset}{Input dataset + +The variables specified by the \code{by_vars} argument are expected to be in the dataset. +\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} +parameter) and to the parameters specified by \code{dividend_code} and \code{divisor_code}.} + +\item{by_vars}{Grouping variables + +For each group defined by \code{by_vars} an observation is added to the output +dataset. Only variables specified in \code{by_vars} will be populated +in the newly created records. + +\emph{Permitted Values}: list of variables created by \code{exprs()} +e.g. \code{exprs(USUBJID, VISIT)}} + +\item{dividend_code}{Dividend parameter code + +The observations where \code{PARAMCD} equals the specified value are considered +as the dividend + +\emph{Permitted Values:} character value} + +\item{divisor_code}{Divisor parameter code + +The observations where \code{PARAMCD} equals the specified value are considered +as the divisor + +\emph{Permitted Values:} character value} + +\item{set_values_to}{Variables to be set + +The specified variables are set to the specified values for the new +observations. For example \code{exprs(PARAMCD = "MAP")} defines the parameter code +for the new parameter. + +\emph{Permitted Values}: List of variable-value pairs} + +\item{constant_dividend}{Is dividend parameter constant? + +It is expected that the parameter code (PARAMCD) specified in \code{dividend_code} +which is required to derive the new parameter is measured only once. For example, +if Height-to-Weight Ratio should be derived and height is measured only once +while Weight is measured at each visit. Height could be specified +in the \code{dividend_code} argument and \code{constant_dividend} is to be set to \code{TRUE}. + +\emph{Permitted Values:} logical scalar} + +\item{constant_divisor}{Is divisor parameter constant? + +It is expected that the parameter code (PARAMCD) specified in \code{dividend_code} +which is required to derive the new parameter is measured only once. For example, +if Waist-to-Height Ratio should be derived and height is measured only once +while Waist Circumference is measured at each visit. Height could be specified +in the \code{divisor_code} argument and \code{constant_divisor} is to be set to \code{TRUE}. + +\emph{Permitted Values:} logical scalar} + +\item{filter}{Filter condition + +The specified condition is applied to the input dataset before deriving the +new parameter, i.e., only observations fulfilling the condition are taken +into account. + +\emph{Permitted Values:} a condition} + +\item{constant_by_vars}{By variables for when dividend and/or divisor is constant + +When dividend and/or divisor is constant, the parameters (measured only once) are merged +to the other parameters using the specified variables. + +If dividend and/or divisor is constant (e.g. only measured once at screening or baseline) +then use \code{constant_by_vars} to select the subject-level variable to merge on +(e.g. \code{USUBJID}). This will produce a generic Ratio parameter at all visits where dividend +and/or divisor is measured. Otherwise it will only be calculated at visits with both dividend +and divisor parameters collected. + +\emph{Permitted Values}: list of variables created by \code{exprs()} +e.g. \code{exprs(USUBJID, VISIT)}} +} +\value{ +The input dataset with the new parameter added. Note, a variable will only +be populated in the new parameter rows if it is specified in \code{by_vars}. +} +\description{ +Adds a record for a generic Ratio parameter using two existing parameter +(dividend and divisor) each by group (e.g., subject and visit) where the source parameters +are available. + +\strong{Note:} This is a wrapper function for the more generic \code{derive_param_computed()} +} +\details{ +The analysis value of the new parameter is derived as +\deqn{RATIO = \frac{DIVIDENT}{DIVISOR}} +} +\seealso{ +Other internal: +\code{\link{admiralmetabolic-package}} +} +\concept{internal} +\keyword{internal} diff --git a/man/derive_param_waisthgt.Rd b/man/derive_param_waisthgt.Rd index 8fc7c8e..a1e261c 100644 --- a/man/derive_param_waisthgt.Rd +++ b/man/derive_param_waisthgt.Rd @@ -8,7 +8,7 @@ derive_param_waisthgt( dataset, by_vars, wstcir_code = "WSTCIR", - height_code = "HGHT", + height_code = "HEIGHT", set_values_to = exprs(PARAMCD = "WAISTHGT"), filter = NULL, constant_by_vars = NULL @@ -85,15 +85,17 @@ be populated in the new parameter rows if it is specified in \code{by_vars}. Adds a record for Waist-to-Height Ratio using Waist Circumference and Height each by group (e.g., subject and visit) where the source parameters are available. -\strong{Note:} This is a wrapper function for the more generic \code{admiral::derive_param_ratio()}. +\strong{Note:} This is a wrapper function for the more generic +\code{admiral::derive_param_computed()}. } \details{ The analysis value of the new parameter is derived as -\deqn{WAISTHGT = \frac{WSTCIR}{HEIGHT}} +\deqn{WAISTHGT = \frac{WSTCIR}{HEIGHT}}{WAISTHGT = WSTCIR / HEIGHT} } \examples{ library(tibble) +library(rlang) # Example 1: Derive Waist-to-Height Ratio where Height is measured only once @@ -151,6 +153,10 @@ derive_param_waisthgt( ) } \seealso{ -\code{\link[=admiral::derive_param_ratio]{admiral::derive_param_ratio()}}, -\code{\link[=admiral::compute_ratio]{admiral::compute_ratio()}} +\code{\link[admiral:derive_param_computed]{admiral::derive_param_computed()}} + +ADXX Functions for adding Parameters: +\code{\link{derive_param_waisthip}()} } +\concept{der_prm_adxx} +\keyword{der_prm_adxx} diff --git a/man/derive_param_waisthip.Rd b/man/derive_param_waisthip.Rd index ab9037d..64fd2f6 100644 --- a/man/derive_param_waisthip.Rd +++ b/man/derive_param_waisthip.Rd @@ -70,15 +70,17 @@ be populated in the new parameter rows if it is specified in \code{by_vars}. Adds a record for Waist-to-Hip Ratio using Waist Circumference and Hip Circumference each by group (e.g., subject and visit) where the source parameters are available. -\strong{Note:} This is a wrapper function for the more generic \code{admiral::derive_param_ratio()}. +\strong{Note:} This is a wrapper function for the more generic +\code{admiral::derive_param_computed()}. } \details{ The analysis value of the new parameter is derived as -\deqn{WAISTHIP = \frac{WSTCIR}{HIPCIR}} +\deqn{WAISTHIP = \frac{WSTCIR}{HIPCIR}}{WAISTHIP = WSTCIR / HIPCIR} } \examples{ library(tibble) +library(rlang) advs <- tribble( ~USUBJID, ~PARAMCD, ~PARAM, ~AVAL, ~AVALU, ~VISIT, @@ -108,6 +110,10 @@ derive_param_waisthip( ) } \seealso{ -\code{\link[=admiral::derive_param_ratio]{admiral::derive_param_ratio()}}, -\code{\link[=admiral::compute_ratio]{admiral::compute_ratio()}} +\code{\link[admiral:derive_param_computed]{admiral::derive_param_computed()}} + +ADXX Functions for adding Parameters: +\code{\link{derive_param_waisthgt}()} } +\concept{der_prm_adxx} +\keyword{der_prm_adxx} diff --git a/tests/testthat/test-derive_param_waisthgt.R b/tests/testthat/test-derive_param_waisthgt.R new file mode 100644 index 0000000..5af36d3 --- /dev/null +++ b/tests/testthat/test-derive_param_waisthgt.R @@ -0,0 +1,94 @@ +test_that( + "derive_param_waisthgt Test 1: Cross-check with admiral::derive_param_computed(), + new observations with constant Height", + { + input <- tribble( + ~USUBJID, ~PARAMCD, ~PARAM, ~AVAL, ~AVALU, ~VISIT, + "01-101-1001", "HEIGHT", "Height (cm)", 147, "cm", "SCREENING", + "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 110, "cm", "SCREENING", + "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 108, "cm", "WEEK 2", + "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 107, "cm", "WEEK 3", + "01-101-1002", "HEIGHT", "Height (cm)", 163, "cm", "SCREENING", + "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 120, "cm", "SCREENING", + "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 118, "cm", "WEEK 2", + "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 117, "cm", "WEEK 3", + ) + + wrapper_output <- derive_param_waisthgt( + input, + by_vars = exprs(USUBJID, VISIT), + set_values_to = exprs( + PARAMCD = "WAISTHGT", + PARAM = "Waist-to-Height Ratio" + ), + constant_by_vars = exprs(USUBJID) + ) + + expected_output <- derive_param_computed( + input, + parameters = "WSTCIR", + by_vars = exprs(USUBJID, VISIT), + set_values_to = exprs( + AVAL = AVAL.WSTCIR / AVAL.HEIGHT, + PARAMCD = "WAISTHGT", + PARAM = "Waist-to-Height Ratio" + ), + constant_parameters = "HEIGHT", + constant_by_vars = exprs(USUBJID) + ) + + expect_dfs_equal( + wrapper_output, + expected_output, + keys = c("USUBJID", "PARAMCD", "VISIT") + ) + } +) + +test_that( + "derive_param_waisthgt Test 2: Cross-check with admiral::derive_param_computed(), + pediatric study where Height is measured multiple times", + { + input <- tribble( + ~USUBJID, ~PARAMCD, ~PARAM, ~AVAL, ~AVALU, ~VISIT, + "01-101-1001", "HEIGHT", "Height (cm)", 147, "cm", "SCREENING", + "01-101-1001", "HEIGHT", "Height (cm)", 148, "cm", "WEEK 2", + "01-101-1001", "HEIGHT", "Height (cm)", 149, "cm", "WEEK 3", + "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 100, "cm", "SCREENING", + "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 99, "cm", "WEEK 2", + "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 98, "cm", "WEEK 3", + "01-101-1002", "HEIGHT", "Height (cm)", 163, "cm", "SCREENING", + "01-101-1002", "HEIGHT", "Height (cm)", 164, "cm", "WEEK 2", + "01-101-1002", "HEIGHT", "Height (cm)", 165, "cm", "WEEK 3", + "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 110, "cm", "SCREENING", + "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 109, "cm", "WEEK 2", + "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 108, "cm", "WEEK 3" + ) + + wrapper_output <- derive_param_waisthgt( + input, + by_vars = exprs(USUBJID, VISIT), + set_values_to = exprs( + PARAMCD = "WAISTHGT", + PARAM = "Waist-to-Height Ratio" + ) + ) + + expected_output <- derive_param_computed( + input, + parameters = c("WSTCIR", "HEIGHT"), + by_vars = exprs(USUBJID, VISIT), + set_values_to = exprs( + AVAL = AVAL.WSTCIR / AVAL.HEIGHT, + PARAMCD = "WAISTHGT", + PARAM = "Waist-to-Height Ratio" + ) + ) + + expect_dfs_equal( + wrapper_output, + expected_output, + keys = c("USUBJID", "PARAMCD", "VISIT") + ) + } +) diff --git a/tests/testthat/test-derive_param_waisthip.R b/tests/testthat/test-derive_param_waisthip.R new file mode 100644 index 0000000..74f728c --- /dev/null +++ b/tests/testthat/test-derive_param_waisthip.R @@ -0,0 +1,46 @@ +test_that( + "derive_param_waisthip Test 1: Cross-check with admiral::derive_param_computed()", + { + input <- tribble( + ~USUBJID, ~PARAMCD, ~PARAM, ~AVAL, ~AVALU, ~VISIT, + "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 125, "cm", "SCREENING", + "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 124, "cm", "WEEK 2", + "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 123, "cm", "WEEK 3", + "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 110, "cm", "SCREENING", + "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 108, "cm", "WEEK 2", + "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 107, "cm", "WEEK 3", + "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 135, "cm", "SCREENING", + "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 133, "cm", "WEEK 2", + "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 132, "cm", "WEEK 3", + "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 120, "cm", "SCREENING", + "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 118, "cm", "WEEK 2", + "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 117, "cm", "WEEK 3" + ) + + wrapper_output <- derive_param_waisthip( + input, + by_vars = exprs(USUBJID, VISIT), + set_values_to = exprs( + PARAMCD = "WAISTHIP", + PARAM = "Waist-to-Hip Ratio" + ) + ) + + expected_output <- derive_param_computed( + input, + parameters = c("WSTCIR", "HIPCIR"), + by_vars = exprs(USUBJID, VISIT), + set_values_to = exprs( + AVAL = AVAL.WSTCIR / AVAL.HIPCIR, + PARAMCD = "WAISTHIP", + PARAM = "Waist-to-Hip Ratio" + ) + ) + + expect_dfs_equal( + wrapper_output, + expected_output, + keys = c("USUBJID", "PARAMCD", "VISIT") + ) + } +) From fddb8c38f32920e1c7b7bd7d784a8e9994d2b6f9 Mon Sep 17 00:00:00 2001 From: Andrii Yurovskyi Date: Thu, 10 Oct 2024 02:00:17 +0200 Subject: [PATCH 06/28] #31 Fix style and update WORDLIST --- inst/WORDLIST | 2 ++ tests/testthat/test-derive_param_waisthgt.R | 4 ++-- 2 files changed, 4 insertions(+), 2 deletions(-) diff --git a/inst/WORDLIST b/inst/WORDLIST index d583e2b..e48ddf8 100644 --- a/inst/WORDLIST +++ b/inst/WORDLIST @@ -36,3 +36,5 @@ renv repo roxygen advs +PARAMCD +prm diff --git a/tests/testthat/test-derive_param_waisthgt.R b/tests/testthat/test-derive_param_waisthgt.R index 5af36d3..60e8256 100644 --- a/tests/testthat/test-derive_param_waisthgt.R +++ b/tests/testthat/test-derive_param_waisthgt.R @@ -55,8 +55,8 @@ test_that( "01-101-1001", "HEIGHT", "Height (cm)", 148, "cm", "WEEK 2", "01-101-1001", "HEIGHT", "Height (cm)", 149, "cm", "WEEK 3", "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 100, "cm", "SCREENING", - "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 99, "cm", "WEEK 2", - "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 98, "cm", "WEEK 3", + "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 99, "cm", "WEEK 2", + "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 98, "cm", "WEEK 3", "01-101-1002", "HEIGHT", "Height (cm)", 163, "cm", "SCREENING", "01-101-1002", "HEIGHT", "Height (cm)", 164, "cm", "WEEK 2", "01-101-1002", "HEIGHT", "Height (cm)", 165, "cm", "WEEK 3", From 16857612ea8175001e607d021ce462bca5ec5daa Mon Sep 17 00:00:00 2001 From: Andrii Yurovskyi Date: Fri, 11 Oct 2024 01:34:41 +0200 Subject: [PATCH 07/28] (#31): Units conversion on the fly --- DESCRIPTION | 3 +- NAMESPACE | 3 ++ R/admiralmetabolic-package.R | 3 +- R/derive_advs_params.R | 73 ++++++++++++++++++++++++++++++++-- R/derive_bds_params.R | 76 +++++++++++++++++++++++++++++------- man/derive_param_ratio.Rd | 14 ++++++- man/derive_param_waisthgt.Rd | 42 +++++++++++++++++++- man/derive_param_waisthip.Rd | 45 ++++++++++++++++++++- 8 files changed, 236 insertions(+), 23 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index 31ddf54..c47162c 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -31,7 +31,8 @@ Imports: lubridate (>= 1.7.4), magrittr (>= 1.5), rlang (>= 0.4.4), - tidyselect (>= 1.0.0) + tidyselect (>= 1.0.0), + units (>= 0.8-5) Suggests: diffdf, DT, diff --git a/NAMESPACE b/NAMESPACE index 55e3196..7378044 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -6,6 +6,7 @@ export(hello_admiral) importFrom(admiral,derive_param_computed) importFrom(admiraldev,assert_character_scalar) importFrom(admiraldev,assert_data_frame) +importFrom(admiraldev,assert_expr) importFrom(admiraldev,assert_filter_cond) importFrom(admiraldev,assert_logical_scalar) importFrom(admiraldev,assert_numeric_vector) @@ -131,5 +132,7 @@ importFrom(stringr,str_trim) importFrom(tidyselect,all_of) importFrom(tidyselect,contains) importFrom(tidyselect,vars_select) +importFrom(units,drop_units) +importFrom(units,mixed_units) importFrom(utils,capture.output) importFrom(utils,str) diff --git a/R/admiralmetabolic-package.R b/R/admiralmetabolic-package.R index ec95354..8c805dd 100644 --- a/R/admiralmetabolic-package.R +++ b/R/admiralmetabolic-package.R @@ -2,7 +2,7 @@ #' @family internal #' @importFrom admiraldev assert_numeric_vector assert_character_scalar assert_logical_scalar #' assert_data_frame assert_vars assert_varval_list assert_filter_cond -#' assert_param_does_not_exist expect_dfs_equal +#' assert_param_does_not_exist assert_expr expect_dfs_equal #' @importFrom admiral derive_param_computed #' @importFrom cli cli_abort #' @importFrom dplyr arrange bind_rows case_when desc ends_with filter full_join group_by @@ -25,4 +25,5 @@ #' time_length %--% ymd ymd_hms weeks years hours minutes #' @importFrom tidyselect all_of contains vars_select #' @importFrom lifecycle deprecate_warn deprecated deprecate_stop +#' @importFrom units mixed_units drop_units "_PACKAGE" diff --git a/R/derive_advs_params.R b/R/derive_advs_params.R index de81d48..8060f87 100644 --- a/R/derive_advs_params.R +++ b/R/derive_advs_params.R @@ -77,12 +77,44 @@ #' PARAM = "Waist-to-Hip Ratio" #' ) #' ) +#' +#' # Automatic conversion is performed when deriving the ratio +#' # if parameters are provided in different units +#' +#' advs <- tribble( +#' ~USUBJID, ~PARAMCD, ~PARAM, ~AVAL, ~AVALU, ~VISIT, +#' "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 125, "cm", "SCREENING", +#' "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 124, "cm", "WEEK 2", +#' "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 123, "cm", "WEEK 3", +#' "01-101-1001", "WSTCIR", "Waist Circumference (in)", 43.31, "in", "SCREENING", +#' "01-101-1001", "WSTCIR", "Waist Circumference (in)", 42.52, "in", "WEEK 2", +#' "01-101-1001", "WSTCIR", "Waist Circumference (in)", 42.13, "in", "WEEK 3", +#' "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 135, "cm", "SCREENING", +#' "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 133, "cm", "WEEK 2", +#' "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 132, "cm", "WEEK 3", +#' "01-101-1002", "WSTCIR", "Waist Circumference (in)", 47.24, "in", "SCREENING", +#' "01-101-1002", "WSTCIR", "Waist Circumference (in)", 46.46, "in", "WEEK 2", +#' "01-101-1002", "WSTCIR", "Waist Circumference (in)", 46.06, "in", "WEEK 3" +#' ) +#' +#' derive_param_waisthip( +#' advs, +#' by_vars = exprs(USUBJID, VISIT), +#' wstcir_code = "WSTCIR", +#' hipcir_code = "HIPCIR", +#' set_values_to = exprs( +#' PARAMCD = "WAISTHIP", +#' PARAM = "Waist-to-Hip Ratio" +#' ), +#' get_unit_expr = admiral::extract_unit(PARAM) +#' ) derive_param_waisthip <- function(dataset, by_vars, wstcir_code = "WSTCIR", hipcir_code = "HIPCIR", set_values_to = exprs(PARAMCD = "WAISTHIP"), - filter = NULL) { + filter = NULL, + get_unit_expr = NULL) { assert_vars(by_vars) assert_data_frame(dataset, required_vars = exprs(!!!by_vars, PARAMCD, AVAL)) assert_character_scalar(wstcir_code) @@ -90,6 +122,7 @@ derive_param_waisthip <- function(dataset, assert_varval_list(set_values_to, required_elements = "PARAMCD") assert_param_does_not_exist(dataset, set_values_to$PARAMCD) filter <- assert_filter_cond(enexpr(filter), optional = TRUE) + get_unit_expr <- assert_expr(enexpr(get_unit_expr), optional = TRUE) derive_param_ratio( dataset, @@ -97,7 +130,8 @@ derive_param_waisthip <- function(dataset, dividend_code = wstcir_code, divisor_code = hipcir_code, by_vars = by_vars, - set_values_to = set_values_to + set_values_to = set_values_to, + get_unit_expr = !!get_unit_expr ) } @@ -222,13 +256,42 @@ derive_param_waisthip <- function(dataset, #' PARAM = "Waist-to-Height Ratio" #' ) #' ) +#' +#' # Example 3: Automatic conversion is performed when deriving the ratio +#' # if parameters are provided in different units (e.g. centimeters and inches) +#' +#' advs <- tribble( +#' ~USUBJID, ~PARAMCD, ~PARAM, ~AVAL, ~AVALU, ~VISIT, +#' "01-101-1001", "HEIGHT", "Height (cm)", 147, "cm", "SCREENING", +#' "01-101-1001", "WSTCIR", "Waist Circumference (in)", 39.37, "in", "SCREENING", +#' "01-101-1001", "WSTCIR", "Waist Circumference (in)", 38.98, "in", "WEEK 2", +#' "01-101-1001", "WSTCIR", "Waist Circumference (in)", 38.58, "in", "WEEK 3", +#' "01-101-1002", "HEIGHT", "Height (cm)", 163, "cm", "SCREENING", +#' "01-101-1002", "WSTCIR", "Waist Circumference (in)", 43.31, "in", "SCREENING", +#' "01-101-1002", "WSTCIR", "Waist Circumference (in)", 42.91, "in", "WEEK 2", +#' "01-101-1002", "WSTCIR", "Waist Circumference (in)", 42.52, "in", "WEEK 3" +#' ) +#' +#' derive_param_waisthgt( +#' advs, +#' by_vars = exprs(USUBJID, VISIT), +#' wstcir_code = "WSTCIR", +#' height_code = "HEIGHT", +#' set_values_to = exprs( +#' PARAMCD = "WAISTHGT", +#' PARAM = "Waist-to-Height Ratio" +#' ), +#' constant_by_vars = exprs(USUBJID), +#' get_unit_expr = AVALU +#' ) derive_param_waisthgt <- function(dataset, by_vars, wstcir_code = "WSTCIR", height_code = "HEIGHT", set_values_to = exprs(PARAMCD = "WAISTHGT"), filter = NULL, - constant_by_vars = NULL) { + constant_by_vars = NULL, + get_unit_expr = NULL) { assert_vars(by_vars) assert_data_frame(dataset, required_vars = exprs(!!!by_vars, PARAMCD, AVAL)) assert_character_scalar(wstcir_code) @@ -237,6 +300,7 @@ derive_param_waisthgt <- function(dataset, assert_param_does_not_exist(dataset, set_values_to$PARAMCD) filter <- assert_filter_cond(enexpr(filter), optional = TRUE) assert_vars(constant_by_vars, optional = TRUE) + get_unit_expr <- assert_expr(enexpr(get_unit_expr), optional = TRUE) derive_param_ratio( dataset, @@ -247,6 +311,7 @@ derive_param_waisthgt <- function(dataset, set_values_to = set_values_to, constant_dividend = FALSE, constant_divisor = !is.null(constant_by_vars), - constant_by_vars = constant_by_vars + constant_by_vars = constant_by_vars, + get_unit_expr = !!get_unit_expr ) } diff --git a/R/derive_bds_params.R b/R/derive_bds_params.R index cb6eae9..e40ec3b 100644 --- a/R/derive_bds_params.R +++ b/R/derive_bds_params.R @@ -63,6 +63,17 @@ #' *Permitted Values*: list of variables created by \code{exprs()} #' e.g. \code{exprs(USUBJID, VISIT)} #' +#' @param get_unit_expr An expression providing the unit of the parameter +#' +#' The result is used to check the units of the input parameters. If the units are not consistent +#' within each parameter, an error will be thrown. +#' +#' Additionally, if the input parameters are measured in different units but are mutually +#' convertible (e.g., centimeters for one parameter and inches for another), an automatic +#' conversion will be performed in order to uniform the values before calculating the ratio. +#' +#' *Permitted Values:* A variable of the input dataset or a function call +#' #' @inheritParams admiral::derive_param_bmi #' #' @details @@ -83,17 +94,47 @@ derive_param_ratio <- function(dataset, constant_dividend = FALSE, constant_divisor = FALSE, filter = NULL, - constant_by_vars = NULL) { + constant_by_vars = NULL, + get_unit_expr = NULL) { assert_vars(by_vars) assert_data_frame(dataset, required_vars = exprs(!!!by_vars, PARAMCD, AVAL)) assert_character_scalar(dividend_code) assert_character_scalar(divisor_code) assert_varval_list(set_values_to, required_elements = "PARAMCD") assert_param_does_not_exist(dataset, set_values_to$PARAMCD) - filter <- assert_filter_cond(enexpr(filter), optional = TRUE) assert_logical_scalar(constant_dividend) assert_logical_scalar(constant_divisor) + filter <- assert_filter_cond(enexpr(filter), optional = TRUE) assert_vars(constant_by_vars, optional = TRUE) + get_unit_expr <- assert_expr(enexpr(get_unit_expr), optional = TRUE) + + if (!missing(get_unit_expr) && !is.null(get_unit_expr)) { + # Check if units are the same within each parameter + for (param in c(dividend_code, divisor_code)) { + units <- dataset %>% + mutate(`_unit` = !!get_unit_expr) %>% + filter(PARAMCD == param) %>% + pull(`_unit`) %>% + unique() + + if (length(units) != 1L) { + cli_abort( + "Multiple units {.val {units}} found for {.val {param}}. + Please review and update the units." + ) + } + } + + # Set units in AVAL context to enable automatic conversion when used in formula + dataset <- dataset %>% + mutate( + AVAL = mixed_units( + AVAL, + !!get_unit_expr %>% if_else(is.na(.), "", .), + mode = "standard" + ) + ) + } ratio_formula <- expr( !!sym(paste0("AVAL.", dividend_code)) / !!sym(paste0("AVAL.", divisor_code)) @@ -117,16 +158,23 @@ derive_param_ratio <- function(dataset, ifelse(length(.) == 0, NULL, .) } - derive_param_computed( - dataset, - filter = !!filter, - parameters = parameters, - by_vars = by_vars, - set_values_to = exprs( - AVAL = !!ratio_formula, - !!!set_values_to - ), - constant_parameters = constant_parameters, - constant_by_vars = constant_by_vars - ) + result <- dataset %>% + derive_param_computed( + filter = !!filter, + parameters = parameters, + by_vars = by_vars, + set_values_to = exprs( + AVAL = !!ratio_formula, + !!!set_values_to + ), + constant_parameters = constant_parameters, + constant_by_vars = constant_by_vars + ) + + if ("mixed_units" %in% class(result$AVAL)) { + # Drop units from AVAL context + result$AVAL <- drop_units(result$AVAL) + } + + result } diff --git a/man/derive_param_ratio.Rd b/man/derive_param_ratio.Rd index 67f5387..059f282 100644 --- a/man/derive_param_ratio.Rd +++ b/man/derive_param_ratio.Rd @@ -13,7 +13,8 @@ derive_param_ratio( constant_dividend = FALSE, constant_divisor = FALSE, filter = NULL, - constant_by_vars = NULL + constant_by_vars = NULL, + get_unit_expr = NULL ) } \arguments{ @@ -98,6 +99,17 @@ and divisor parameters collected. \emph{Permitted Values}: list of variables created by \code{exprs()} e.g. \code{exprs(USUBJID, VISIT)}} + +\item{get_unit_expr}{An expression providing the unit of the parameter + +The result is used to check the units of the input parameters. If the units are not consistent +within each parameter, an error will be thrown. + +Additionally, if the input parameters are measured in different units but are mutually +convertible (e.g., centimeters for one parameter and inches for another), an automatic +conversion will be performed in order to uniform the values before calculating the ratio. + +\emph{Permitted Values:} A variable of the input dataset or a function call} } \value{ The input dataset with the new parameter added. Note, a variable will only diff --git a/man/derive_param_waisthgt.Rd b/man/derive_param_waisthgt.Rd index a1e261c..ce9069a 100644 --- a/man/derive_param_waisthgt.Rd +++ b/man/derive_param_waisthgt.Rd @@ -11,7 +11,8 @@ derive_param_waisthgt( height_code = "HEIGHT", set_values_to = exprs(PARAMCD = "WAISTHGT"), filter = NULL, - constant_by_vars = NULL + constant_by_vars = NULL, + get_unit_expr = NULL ) } \arguments{ @@ -76,6 +77,17 @@ collected. \emph{Permitted Values}: list of variables created by \code{exprs()} e.g. \code{exprs(USUBJID, VISIT)}} + +\item{get_unit_expr}{An expression providing the unit of the parameter + +The result is used to check the units of the input parameters. If the units are not consistent +within each parameter, an error will be thrown. + +Additionally, if the input parameters are measured in different units but are mutually +convertible (e.g., centimeters for one parameter and inches for another), an automatic +conversion will be performed in order to uniform the values before calculating the ratio. + +\emph{Permitted Values:} A variable of the input dataset or a function call} } \value{ The input dataset with the new parameter added. Note, a variable will only @@ -151,6 +163,34 @@ derive_param_waisthgt( PARAM = "Waist-to-Height Ratio" ) ) + +# Example 3: Automatic conversion is performed when deriving the ratio +# if parameters are provided in different units (e.g. centimeters and inches) + +advs <- tribble( + ~USUBJID, ~PARAMCD, ~PARAM, ~AVAL, ~AVALU, ~VISIT, + "01-101-1001", "HEIGHT", "Height (cm)", 147, "cm", "SCREENING", + "01-101-1001", "WSTCIR", "Waist Circumference (in)", 39.37, "in", "SCREENING", + "01-101-1001", "WSTCIR", "Waist Circumference (in)", 38.98, "in", "WEEK 2", + "01-101-1001", "WSTCIR", "Waist Circumference (in)", 38.58, "in", "WEEK 3", + "01-101-1002", "HEIGHT", "Height (cm)", 163, "cm", "SCREENING", + "01-101-1002", "WSTCIR", "Waist Circumference (in)", 43.31, "in", "SCREENING", + "01-101-1002", "WSTCIR", "Waist Circumference (in)", 42.91, "in", "WEEK 2", + "01-101-1002", "WSTCIR", "Waist Circumference (in)", 42.52, "in", "WEEK 3" +) + +derive_param_waisthgt( + advs, + by_vars = exprs(USUBJID, VISIT), + wstcir_code = "WSTCIR", + height_code = "HEIGHT", + set_values_to = exprs( + PARAMCD = "WAISTHGT", + PARAM = "Waist-to-Height Ratio" + ), + constant_by_vars = exprs(USUBJID), + get_unit_expr = AVALU +) } \seealso{ \code{\link[admiral:derive_param_computed]{admiral::derive_param_computed()}} diff --git a/man/derive_param_waisthip.Rd b/man/derive_param_waisthip.Rd index 64fd2f6..d6c8097 100644 --- a/man/derive_param_waisthip.Rd +++ b/man/derive_param_waisthip.Rd @@ -10,7 +10,8 @@ derive_param_waisthip( wstcir_code = "WSTCIR", hipcir_code = "HIPCIR", set_values_to = exprs(PARAMCD = "WAISTHIP"), - filter = NULL + filter = NULL, + get_unit_expr = NULL ) } \arguments{ @@ -61,6 +62,17 @@ new parameter, i.e., only observations fulfilling the condition are taken into account. \emph{Permitted Values:} a condition} + +\item{get_unit_expr}{An expression providing the unit of the parameter + +The result is used to check the units of the input parameters. If the units are not consistent +within each parameter, an error will be thrown. + +Additionally, if the input parameters are measured in different units but are mutually +convertible (e.g., centimeters for one parameter and inches for another), an automatic +conversion will be performed in order to uniform the values before calculating the ratio. + +\emph{Permitted Values:} A variable of the input dataset or a function call} } \value{ The input dataset with the new parameter added. Note, a variable will only @@ -108,6 +120,37 @@ derive_param_waisthip( PARAM = "Waist-to-Hip Ratio" ) ) + +# Automatic conversion is performed when deriving the ratio +# if parameters are provided in different units + +advs <- tribble( + ~USUBJID, ~PARAMCD, ~PARAM, ~AVAL, ~AVALU, ~VISIT, + "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 125, "cm", "SCREENING", + "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 124, "cm", "WEEK 2", + "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 123, "cm", "WEEK 3", + "01-101-1001", "WSTCIR", "Waist Circumference (in)", 43.31, "in", "SCREENING", + "01-101-1001", "WSTCIR", "Waist Circumference (in)", 42.52, "in", "WEEK 2", + "01-101-1001", "WSTCIR", "Waist Circumference (in)", 42.13, "in", "WEEK 3", + "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 135, "cm", "SCREENING", + "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 133, "cm", "WEEK 2", + "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 132, "cm", "WEEK 3", + "01-101-1002", "WSTCIR", "Waist Circumference (in)", 47.24, "in", "SCREENING", + "01-101-1002", "WSTCIR", "Waist Circumference (in)", 46.46, "in", "WEEK 2", + "01-101-1002", "WSTCIR", "Waist Circumference (in)", 46.06, "in", "WEEK 3" +) + +derive_param_waisthip( + advs, + by_vars = exprs(USUBJID, VISIT), + wstcir_code = "WSTCIR", + hipcir_code = "HIPCIR", + set_values_to = exprs( + PARAMCD = "WAISTHIP", + PARAM = "Waist-to-Hip Ratio" + ), + get_unit_expr = admiral::extract_unit(PARAM) +) } \seealso{ \code{\link[admiral:derive_param_computed]{admiral::derive_param_computed()}} From ccdf0026843d424c1c8c484da0ab6f130500a5f8 Mon Sep 17 00:00:00 2001 From: Andrii Yurovskyi Date: Fri, 11 Oct 2024 19:42:35 +0200 Subject: [PATCH 08/28] (#31): Removed hyphens from PARAM and added a couple of unit tests --- R/derive_advs_params.R | 22 +++---- man/derive_param_waisthgt.Rd | 14 ++--- man/derive_param_waisthip.Rd | 8 +-- tests/testthat/test-derive_param_waisthgt.R | 67 ++++++++++++++++++-- tests/testthat/test-derive_param_waisthip.R | 69 ++++++++++++++++++++- 5 files changed, 152 insertions(+), 28 deletions(-) diff --git a/R/derive_advs_params.R b/R/derive_advs_params.R index 8060f87..5d31768 100644 --- a/R/derive_advs_params.R +++ b/R/derive_advs_params.R @@ -1,6 +1,6 @@ -#' Adds a Parameter for Waist-to-Hip Ratio +#' Adds a Parameter for Waist to Hip Ratio #' -#' @description Adds a record for Waist-to-Hip Ratio using Waist Circumference and Hip Circumference +#' @description Adds a record for Waist to Hip Ratio using Waist Circumference and Hip Circumference #' each by group (e.g., subject and visit) where the source parameters are available. #' #' **Note:** This is a wrapper function for the more generic @@ -74,7 +74,7 @@ #' hipcir_code = "HIPCIR", #' set_values_to = exprs( #' PARAMCD = "WAISTHIP", -#' PARAM = "Waist-to-Hip Ratio" +#' PARAM = "Waist to Hip Ratio" #' ) #' ) #' @@ -104,7 +104,7 @@ #' hipcir_code = "HIPCIR", #' set_values_to = exprs( #' PARAMCD = "WAISTHIP", -#' PARAM = "Waist-to-Hip Ratio" +#' PARAM = "Waist to Hip Ratio" #' ), #' get_unit_expr = admiral::extract_unit(PARAM) #' ) @@ -135,9 +135,9 @@ derive_param_waisthip <- function(dataset, ) } -#' Adds a Parameter for Waist-to-Height Ratio +#' Adds a Parameter for Waist to Height Ratio #' -#' @description Adds a record for Waist-to-Height Ratio using Waist Circumference and Height +#' @description Adds a record for Waist to Height Ratio using Waist Circumference and Height #' each by group (e.g., subject and visit) where the source parameters are available. #' #' **Note:** This is a wrapper function for the more generic @@ -173,7 +173,7 @@ derive_param_waisthip <- function(dataset, #' #' If Height is constant (e.g. only measured once at screening or baseline) then use #' \code{constant_by_vars} to select the subject-level variable to merge on (e.g. \code{USUBJID}). -#' This will produce Waist-to-Height Ratio at all visits where Waist Circumference is measured. +#' This will produce Waist to Height Ratio at all visits where Waist Circumference is measured. #' Otherwise it will only be calculated at visits with both Height and Waist Circumference #' collected. #' @@ -202,7 +202,7 @@ derive_param_waisthip <- function(dataset, #' library(tibble) #' library(rlang) #' -#' # Example 1: Derive Waist-to-Height Ratio where Height is measured only once +#' # Example 1: Derive Waist to Height Ratio where Height is measured only once #' #' advs <- tribble( #' ~USUBJID, ~PARAMCD, ~PARAM, ~AVAL, ~AVALU, ~VISIT, @@ -223,7 +223,7 @@ derive_param_waisthip <- function(dataset, #' height_code = "HEIGHT", #' set_values_to = exprs( #' PARAMCD = "WAISTHGT", -#' PARAM = "Waist-to-Height Ratio" +#' PARAM = "Waist to Height Ratio" #' ), #' constant_by_vars = exprs(USUBJID) #' ) @@ -253,7 +253,7 @@ derive_param_waisthip <- function(dataset, #' height_code = "HEIGHT", #' set_values_to = exprs( #' PARAMCD = "WAISTHGT", -#' PARAM = "Waist-to-Height Ratio" +#' PARAM = "Waist to Height Ratio" #' ) #' ) #' @@ -279,7 +279,7 @@ derive_param_waisthip <- function(dataset, #' height_code = "HEIGHT", #' set_values_to = exprs( #' PARAMCD = "WAISTHGT", -#' PARAM = "Waist-to-Height Ratio" +#' PARAM = "Waist to Height Ratio" #' ), #' constant_by_vars = exprs(USUBJID), #' get_unit_expr = AVALU diff --git a/man/derive_param_waisthgt.Rd b/man/derive_param_waisthgt.Rd index ce9069a..f62de48 100644 --- a/man/derive_param_waisthgt.Rd +++ b/man/derive_param_waisthgt.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/derive_advs_params.R \name{derive_param_waisthgt} \alias{derive_param_waisthgt} -\title{Adds a Parameter for Waist-to-Height Ratio} +\title{Adds a Parameter for Waist to Height Ratio} \usage{ derive_param_waisthgt( dataset, @@ -71,7 +71,7 @@ to the other parameters using the specified variables. If Height is constant (e.g. only measured once at screening or baseline) then use \code{constant_by_vars} to select the subject-level variable to merge on (e.g. \code{USUBJID}). -This will produce Waist-to-Height Ratio at all visits where Waist Circumference is measured. +This will produce Waist to Height Ratio at all visits where Waist Circumference is measured. Otherwise it will only be calculated at visits with both Height and Waist Circumference collected. @@ -94,7 +94,7 @@ The input dataset with the new parameter added. Note, a variable will only be populated in the new parameter rows if it is specified in \code{by_vars}. } \description{ -Adds a record for Waist-to-Height Ratio using Waist Circumference and Height +Adds a record for Waist to Height Ratio using Waist Circumference and Height each by group (e.g., subject and visit) where the source parameters are available. \strong{Note:} This is a wrapper function for the more generic @@ -109,7 +109,7 @@ The analysis value of the new parameter is derived as library(tibble) library(rlang) -# Example 1: Derive Waist-to-Height Ratio where Height is measured only once +# Example 1: Derive Waist to Height Ratio where Height is measured only once advs <- tribble( ~USUBJID, ~PARAMCD, ~PARAM, ~AVAL, ~AVALU, ~VISIT, @@ -130,7 +130,7 @@ derive_param_waisthgt( height_code = "HEIGHT", set_values_to = exprs( PARAMCD = "WAISTHGT", - PARAM = "Waist-to-Height Ratio" + PARAM = "Waist to Height Ratio" ), constant_by_vars = exprs(USUBJID) ) @@ -160,7 +160,7 @@ derive_param_waisthgt( height_code = "HEIGHT", set_values_to = exprs( PARAMCD = "WAISTHGT", - PARAM = "Waist-to-Height Ratio" + PARAM = "Waist to Height Ratio" ) ) @@ -186,7 +186,7 @@ derive_param_waisthgt( height_code = "HEIGHT", set_values_to = exprs( PARAMCD = "WAISTHGT", - PARAM = "Waist-to-Height Ratio" + PARAM = "Waist to Height Ratio" ), constant_by_vars = exprs(USUBJID), get_unit_expr = AVALU diff --git a/man/derive_param_waisthip.Rd b/man/derive_param_waisthip.Rd index d6c8097..4ac16cf 100644 --- a/man/derive_param_waisthip.Rd +++ b/man/derive_param_waisthip.Rd @@ -2,7 +2,7 @@ % Please edit documentation in R/derive_advs_params.R \name{derive_param_waisthip} \alias{derive_param_waisthip} -\title{Adds a Parameter for Waist-to-Hip Ratio} +\title{Adds a Parameter for Waist to Hip Ratio} \usage{ derive_param_waisthip( dataset, @@ -79,7 +79,7 @@ The input dataset with the new parameter added. Note, a variable will only be populated in the new parameter rows if it is specified in \code{by_vars}. } \description{ -Adds a record for Waist-to-Hip Ratio using Waist Circumference and Hip Circumference +Adds a record for Waist to Hip Ratio using Waist Circumference and Hip Circumference each by group (e.g., subject and visit) where the source parameters are available. \strong{Note:} This is a wrapper function for the more generic @@ -117,7 +117,7 @@ derive_param_waisthip( hipcir_code = "HIPCIR", set_values_to = exprs( PARAMCD = "WAISTHIP", - PARAM = "Waist-to-Hip Ratio" + PARAM = "Waist to Hip Ratio" ) ) @@ -147,7 +147,7 @@ derive_param_waisthip( hipcir_code = "HIPCIR", set_values_to = exprs( PARAMCD = "WAISTHIP", - PARAM = "Waist-to-Hip Ratio" + PARAM = "Waist to Hip Ratio" ), get_unit_expr = admiral::extract_unit(PARAM) ) diff --git a/tests/testthat/test-derive_param_waisthgt.R b/tests/testthat/test-derive_param_waisthgt.R index 60e8256..bd6c886 100644 --- a/tests/testthat/test-derive_param_waisthgt.R +++ b/tests/testthat/test-derive_param_waisthgt.R @@ -19,7 +19,7 @@ test_that( by_vars = exprs(USUBJID, VISIT), set_values_to = exprs( PARAMCD = "WAISTHGT", - PARAM = "Waist-to-Height Ratio" + PARAM = "Waist to Height Ratio" ), constant_by_vars = exprs(USUBJID) ) @@ -31,7 +31,7 @@ test_that( set_values_to = exprs( AVAL = AVAL.WSTCIR / AVAL.HEIGHT, PARAMCD = "WAISTHGT", - PARAM = "Waist-to-Height Ratio" + PARAM = "Waist to Height Ratio" ), constant_parameters = "HEIGHT", constant_by_vars = exprs(USUBJID) @@ -70,7 +70,7 @@ test_that( by_vars = exprs(USUBJID, VISIT), set_values_to = exprs( PARAMCD = "WAISTHGT", - PARAM = "Waist-to-Height Ratio" + PARAM = "Waist to Height Ratio" ) ) @@ -81,7 +81,7 @@ test_that( set_values_to = exprs( AVAL = AVAL.WSTCIR / AVAL.HEIGHT, PARAMCD = "WAISTHGT", - PARAM = "Waist-to-Height Ratio" + PARAM = "Waist to Height Ratio" ) ) @@ -92,3 +92,62 @@ test_that( ) } ) + +test_that( + "derive_param_waisthgt Test 3: Cross-check with and without units conversion", + { + input_diff_units <- tribble( + ~USUBJID, ~PARAMCD, ~PARAM, ~AVAL, ~AVALU, ~VISIT, + "01-101-1001", "HEIGHT", "Height (cm)", 147, "cm", "SCREENING", + "01-101-1001", "WSTCIR", "Waist Circumference (in)", 39.37, "in", "SCREENING", + "01-101-1001", "WSTCIR", "Waist Circumference (in)", 38.98, "in", "WEEK 2", + "01-101-1001", "WSTCIR", "Waist Circumference (in)", 38.58, "in", "WEEK 3", + "01-101-1002", "HEIGHT", "Height (cm)", 163, "cm", "SCREENING", + "01-101-1002", "WSTCIR", "Waist Circumference (in)", 43.31, "in", "SCREENING", + "01-101-1002", "WSTCIR", "Waist Circumference (in)", 42.91, "in", "WEEK 2", + "01-101-1002", "WSTCIR", "Waist Circumference (in)", 42.52, "in", "WEEK 3" + ) + + output_units_unified <- derive_param_waisthgt( + input_diff_units, + by_vars = exprs(USUBJID, VISIT), + set_values_to = exprs( + PARAMCD = "WAISTHGT", + PARAM = "Waist to Height Ratio" + ), + constant_by_vars = exprs(USUBJID), + get_unit_expr = AVALU + ) %>% + filter(PARAMCD == "WAISTHGT") + + input_same_units <- tribble( + ~USUBJID, ~PARAMCD, ~PARAM, ~AVAL, ~AVALU, ~VISIT, + "01-101-1001", "HEIGHT", "Height (cm)", 147, "cm", "SCREENING", + "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 100, "cm", "SCREENING", + "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 99, "cm", "WEEK 2", + "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 98, "cm", "WEEK 3", + "01-101-1002", "HEIGHT", "Height (cm)", 163, "cm", "SCREENING", + "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 110, "cm", "SCREENING", + "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 109, "cm", "WEEK 2", + "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 108, "cm", "WEEK 3" + ) + + expected_output <- derive_param_waisthgt( + input_same_units, + by_vars = exprs(USUBJID, VISIT), + set_values_to = exprs( + PARAMCD = "WAISTHGT", + PARAM = "Waist to Height Ratio" + ), + constant_by_vars = exprs(USUBJID) + ) %>% + filter(PARAMCD == "WAISTHGT") + + expect_dfs_equal( + output_units_unified, + expected_output, + keys = c("USUBJID", "PARAMCD", "VISIT"), + tolerance = 0.0001 + ) + } +) diff --git a/tests/testthat/test-derive_param_waisthip.R b/tests/testthat/test-derive_param_waisthip.R index 74f728c..b4c8017 100644 --- a/tests/testthat/test-derive_param_waisthip.R +++ b/tests/testthat/test-derive_param_waisthip.R @@ -22,7 +22,7 @@ test_that( by_vars = exprs(USUBJID, VISIT), set_values_to = exprs( PARAMCD = "WAISTHIP", - PARAM = "Waist-to-Hip Ratio" + PARAM = "Waist to Hip Ratio" ) ) @@ -33,7 +33,7 @@ test_that( set_values_to = exprs( AVAL = AVAL.WSTCIR / AVAL.HIPCIR, PARAMCD = "WAISTHIP", - PARAM = "Waist-to-Hip Ratio" + PARAM = "Waist to Hip Ratio" ) ) @@ -44,3 +44,68 @@ test_that( ) } ) + +test_that( + "derive_param_waisthip Test 2: Cross-check with and without units conversion", + { + input_diff_units <- tribble( + ~USUBJID, ~PARAMCD, ~PARAM, ~AVAL, ~AVALU, ~VISIT, + "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 125, "cm", "SCREENING", + "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 124, "cm", "WEEK 2", + "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 123, "cm", "WEEK 3", + "01-101-1001", "WSTCIR", "Waist Circumference (in)", 43.31, "in", "SCREENING", + "01-101-1001", "WSTCIR", "Waist Circumference (in)", 42.52, "in", "WEEK 2", + "01-101-1001", "WSTCIR", "Waist Circumference (in)", 42.13, "in", "WEEK 3", + "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 135, "cm", "SCREENING", + "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 133, "cm", "WEEK 2", + "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 132, "cm", "WEEK 3", + "01-101-1002", "WSTCIR", "Waist Circumference (in)", 47.24, "in", "SCREENING", + "01-101-1002", "WSTCIR", "Waist Circumference (in)", 46.46, "in", "WEEK 2", + "01-101-1002", "WSTCIR", "Waist Circumference (in)", 46.06, "in", "WEEK 3" + ) + + output_units_unified <- derive_param_waisthip( + input_diff_units, + by_vars = exprs(USUBJID, VISIT), + set_values_to = exprs( + PARAMCD = "WAISTHIP", + PARAM = "Waist to Hip Ratio" + ), + get_unit_expr = AVALU + ) %>% + filter(PARAMCD == "WAISTHIP") + + input_same_units <- tribble( + ~USUBJID, ~PARAMCD, ~PARAM, ~AVAL, ~AVALU, ~VISIT, + "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 125, "cm", "SCREENING", + "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 124, "cm", "WEEK 2", + "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 123, "cm", "WEEK 3", + "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 110, "cm", "SCREENING", + "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 108, "cm", "WEEK 2", + "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 107, "cm", "WEEK 3", + "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 135, "cm", "SCREENING", + "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 133, "cm", "WEEK 2", + "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 132, "cm", "WEEK 3", + "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 120, "cm", "SCREENING", + "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 118, "cm", "WEEK 2", + "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 117, "cm", "WEEK 3" + ) + + expected_output <- derive_param_waisthip( + input_same_units, + by_vars = exprs(USUBJID, VISIT), + set_values_to = exprs( + PARAMCD = "WAISTHIP", + PARAM = "Waist to Hip Ratio" + ) + ) %>% + filter(PARAMCD == "WAISTHIP") + + expect_dfs_equal( + output_units_unified, + expected_output, + keys = c("USUBJID", "PARAMCD", "VISIT"), + tolerance = 0.0001 + ) + } +) From eaa6524f959167cfe67913d14151a9365c24485f Mon Sep 17 00:00:00 2001 From: Andrii Yurovskyi Date: Wed, 16 Oct 2024 01:30:27 +0200 Subject: [PATCH 09/28] #31 Get rid of {units} package --- DESCRIPTION | 3 +- NAMESPACE | 3 +- R/admiralmetabolic-package.R | 3 +- R/derive_advs_params.R | 20 ++-- R/derive_bds_params.R | 198 ++++++++++++++++++++++------------- man/derive_param_ratio.Rd | 58 +++++----- man/derive_param_waisthgt.Rd | 4 +- man/derive_param_waisthip.Rd | 4 +- 8 files changed, 172 insertions(+), 121 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index c47162c..31ddf54 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -31,8 +31,7 @@ Imports: lubridate (>= 1.7.4), magrittr (>= 1.5), rlang (>= 0.4.4), - tidyselect (>= 1.0.0), - units (>= 0.8-5) + tidyselect (>= 1.0.0) Suggests: diffdf, DT, diff --git a/NAMESPACE b/NAMESPACE index 7378044..f0fd614 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -15,6 +15,7 @@ importFrom(admiraldev,assert_vars) importFrom(admiraldev,assert_varval_list) importFrom(admiraldev,expect_dfs_equal) importFrom(cli,cli_abort) +importFrom(cli,cli_alert_info) importFrom(dplyr,arrange) importFrom(dplyr,bind_cols) importFrom(dplyr,bind_rows) @@ -132,7 +133,5 @@ importFrom(stringr,str_trim) importFrom(tidyselect,all_of) importFrom(tidyselect,contains) importFrom(tidyselect,vars_select) -importFrom(units,drop_units) -importFrom(units,mixed_units) importFrom(utils,capture.output) importFrom(utils,str) diff --git a/R/admiralmetabolic-package.R b/R/admiralmetabolic-package.R index 8c805dd..3b23065 100644 --- a/R/admiralmetabolic-package.R +++ b/R/admiralmetabolic-package.R @@ -4,7 +4,7 @@ #' assert_data_frame assert_vars assert_varval_list assert_filter_cond #' assert_param_does_not_exist assert_expr expect_dfs_equal #' @importFrom admiral derive_param_computed -#' @importFrom cli cli_abort +#' @importFrom cli cli_abort cli_alert_info #' @importFrom dplyr arrange bind_rows case_when desc ends_with filter full_join group_by #' if_else mutate mutate_at mutate_if n pull rename rename_at row_number select slice #' starts_with transmute ungroup vars n_distinct union distinct @@ -25,5 +25,4 @@ #' time_length %--% ymd ymd_hms weeks years hours minutes #' @importFrom tidyselect all_of contains vars_select #' @importFrom lifecycle deprecate_warn deprecated deprecate_stop -#' @importFrom units mixed_units drop_units "_PACKAGE" diff --git a/R/derive_advs_params.R b/R/derive_advs_params.R index 5d31768..11b3402 100644 --- a/R/derive_advs_params.R +++ b/R/derive_advs_params.R @@ -12,8 +12,8 @@ #' \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} -#' parameter) and to the parameters specified by \code{wstcir_code} and \code{hipcir_code}. +#' the input dataset after restricting it by the filter condition (\code{filter} argument) +#' and to the parameters specified by \code{wstcir_code} and \code{hipcir_code}. #' #' @param wstcir_code Waist Circumference parameter code #' @@ -127,8 +127,8 @@ derive_param_waisthip <- function(dataset, derive_param_ratio( dataset, filter = !!filter, - dividend_code = wstcir_code, - divisor_code = hipcir_code, + numerator_code = wstcir_code, + denominator_code = hipcir_code, by_vars = by_vars, set_values_to = set_values_to, get_unit_expr = !!get_unit_expr @@ -149,8 +149,8 @@ derive_param_waisthip <- function(dataset, #' \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} -#' parameter) and to the parameters specified by \code{wstcir_code} and \code{height_code}. +#' the input dataset after restricting it by the filter condition (\code{filter} argument) +#' and to the parameters specified by \code{wstcir_code} and \code{height_code}. #' #' @param wstcir_code Waist Circumference parameter code #' @@ -305,12 +305,12 @@ derive_param_waisthgt <- function(dataset, derive_param_ratio( dataset, filter = !!filter, - dividend_code = wstcir_code, - divisor_code = height_code, + numerator_code = wstcir_code, + denominator_code = height_code, by_vars = by_vars, set_values_to = set_values_to, - constant_dividend = FALSE, - constant_divisor = !is.null(constant_by_vars), + constant_numerator = FALSE, + constant_denominator = !is.null(constant_by_vars), constant_by_vars = constant_by_vars, get_unit_expr = !!get_unit_expr ) diff --git a/R/derive_bds_params.R b/R/derive_bds_params.R index e40ec3b..79e005f 100644 --- a/R/derive_bds_params.R +++ b/R/derive_bds_params.R @@ -1,7 +1,7 @@ #' Adds a Ratio Parameter Computed from the Analysis Value of Other Parameters #' #' @description Adds a record for a generic Ratio parameter using two existing parameter -#' (dividend and divisor) each by group (e.g., subject and visit) where the source parameters +#' (numerator and denominator) each by group (e.g., subject and visit) where the source parameters #' are available. #' #' **Note:** This is a wrapper function for the more generic \code{derive_param_computed()} @@ -12,53 +12,53 @@ #' \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} -#' parameter) and to the parameters specified by \code{dividend_code} and \code{divisor_code}. +#' the input dataset after restricting it by the filter condition (\code{filter} argument) +#' and to the parameters specified by \code{numerator_code} and \code{denominator_code}. #' -#' @param dividend_code Dividend parameter code +#' @param numerator_code Numerator parameter code #' #' The observations where \code{PARAMCD} equals the specified value are considered -#' as the dividend +#' as the numerator #' #' *Permitted Values:* character value #' -#' @param divisor_code Divisor parameter code +#' @param denominator_code Denominator parameter code #' #' The observations where \code{PARAMCD} equals the specified value are considered -#' as the divisor +#' as the denominator #' #' *Permitted Values:* character value #' -#' @param constant_dividend Is dividend parameter constant? +#' @param constant_numerator Is numerator parameter constant? #' -#' It is expected that the parameter code (PARAMCD) specified in \code{dividend_code} +#' It is expected that the parameter code (PARAMCD) specified in \code{numerator_code} #' which is required to derive the new parameter is measured only once. For example, -#' if Height-to-Weight Ratio should be derived and height is measured only once -#' while Weight is measured at each visit. Height could be specified -#' in the \code{dividend_code} argument and \code{constant_dividend} is to be set to \code{TRUE}. +#' if Height to Weight Ratio should be derived and height is measured only once +#' while Weight is measured at each visit. Height could be specified in the +#' \code{numerator_code} argument and \code{constant_numerator} is to be set to \code{TRUE}. #' #' *Permitted Values:* logical scalar #' -#' @param constant_divisor Is divisor parameter constant? +#' @param constant_denominator Is denominator parameter constant? #' -#' It is expected that the parameter code (PARAMCD) specified in \code{dividend_code} +#' It is expected that the parameter code (PARAMCD) specified in \code{numerator_code} #' which is required to derive the new parameter is measured only once. For example, -#' if Waist-to-Height Ratio should be derived and height is measured only once -#' while Waist Circumference is measured at each visit. Height could be specified -#' in the \code{divisor_code} argument and \code{constant_divisor} is to be set to \code{TRUE}. +#' if Waist to Height Ratio should be derived and height is measured only once +#' while Waist Circumference is measured at each visit. Height could be specified in the +#' \code{denominator_code} argument and \code{constant_denominator} is to be set to \code{TRUE}. #' #' *Permitted Values:* logical scalar #' -#' @param constant_by_vars By variables for when dividend and/or divisor is constant +#' @param constant_by_vars By variables for when numerator and/or denominator is constant #' -#' When dividend and/or divisor is constant, the parameters (measured only once) are merged +#' When numerator and/or denominator is constant, the parameters (measured only once) are merged #' to the other parameters using the specified variables. #' -#' If dividend and/or divisor is constant (e.g. only measured once at screening or baseline) -#' then use \code{constant_by_vars} to select the subject-level variable to merge on -#' (e.g. \code{USUBJID}). This will produce a generic Ratio parameter at all visits where dividend -#' and/or divisor is measured. Otherwise it will only be calculated at visits with both dividend -#' and divisor parameters collected. +#' If numerator and/or denominator is constant (e.g. only measured once at screening or baseline) +#' then use \code{constant_by_vars} to select the subject-level variable to merge on (e.g. +#' \code{USUBJID}). This will produce a generic Ratio parameter at all visits where numerator +#' and/or denominator is measured. Otherwise it will only be calculated at visits with both +#' numerator and denominator parameters collected. #' #' *Permitted Values*: list of variables created by \code{exprs()} #' e.g. \code{exprs(USUBJID, VISIT)} @@ -78,7 +78,7 @@ #' #' @details #' The analysis value of the new parameter is derived as -#' \deqn{RATIO = \frac{DIVIDENT}{DIVISOR}} +#' \deqn{RATIO = \frac{NUMERATOR}{DENOMINATOR}} #' #' #' @return The input dataset with the new parameter added. Note, a variable will only @@ -88,93 +88,147 @@ #' @keywords internal derive_param_ratio <- function(dataset, by_vars, - dividend_code, - divisor_code, + numerator_code, + denominator_code, set_values_to, - constant_dividend = FALSE, - constant_divisor = FALSE, + constant_numerator = FALSE, + constant_denominator = FALSE, filter = NULL, constant_by_vars = NULL, get_unit_expr = NULL) { assert_vars(by_vars) assert_data_frame(dataset, required_vars = exprs(!!!by_vars, PARAMCD, AVAL)) - assert_character_scalar(dividend_code) - assert_character_scalar(divisor_code) + assert_character_scalar(numerator_code) + assert_character_scalar(denominator_code) assert_varval_list(set_values_to, required_elements = "PARAMCD") assert_param_does_not_exist(dataset, set_values_to$PARAMCD) - assert_logical_scalar(constant_dividend) - assert_logical_scalar(constant_divisor) + assert_logical_scalar(constant_numerator) + assert_logical_scalar(constant_denominator) filter <- assert_filter_cond(enexpr(filter), optional = TRUE) assert_vars(constant_by_vars, optional = TRUE) get_unit_expr <- assert_expr(enexpr(get_unit_expr), optional = TRUE) + ### Default formula with no units conversion applied ---- + + ratio_formula <- expr( + !!sym(paste0("AVAL.", numerator_code)) / + !!sym(paste0("AVAL.", denominator_code)) + ) + + ### If `get_unit_expr` provided then check units and enable units conversion ---- + if (!missing(get_unit_expr) && !is.null(get_unit_expr)) { - # Check if units are the same within each parameter - for (param in c(dividend_code, divisor_code)) { - units <- dataset %>% + param_units <- list() + + # Check if units are the same within each of two parameters + + for (param in c(numerator_code, denominator_code)) { + units_found <- dataset %>% mutate(`_unit` = !!get_unit_expr) %>% filter(PARAMCD == param) %>% pull(`_unit`) %>% unique() - if (length(units) != 1L) { + if (length(units_found) != 1L) { cli_abort( - "Multiple units {.val {units}} found for {.val {param}}. + "Multiple units {.val {units_found}} found for {.val {param}}. Please review and update the units." ) } + + param_units[[param]] <- units_found } - # Set units in AVAL context to enable automatic conversion when used in formula - dataset <- dataset %>% - mutate( - AVAL = mixed_units( - AVAL, - !!get_unit_expr %>% if_else(is.na(.), "", .), - mode = "standard" - ) + # If the input parameters are measured in different units + # but are convertible from one to another (and this kind of conversion supported) + # then modify the formula in order to perform units conversion on the fly + + if (param_units[[denominator_code]] != param_units[[numerator_code]]) { + # Find conversion factor for denominator + conv_factor <- get_conv_factor( + param_units[[denominator_code]], + param_units[[numerator_code]] ) + + if (!is.na(conv_factor)) { + ratio_formula <- expr( + !!sym(paste0("AVAL.", numerator_code)) / ( + !!sym(paste0("AVAL.", denominator_code)) * !!conv_factor + ) + ) + + cli_alert_info( + "Unit conversion performed for {.val {denominator_code}}. Values converted from + {.val {param_units[[denominator_code]]}} to {.val {param_units[[numerator_code]]}}.", + wrap = TRUE + ) + } + } } - ratio_formula <- expr( - !!sym(paste0("AVAL.", dividend_code)) / !!sym(paste0("AVAL.", divisor_code)) - ) + ### Identify constant parameters ---- - parameters <- c(dividend_code, divisor_code) + parameters <- c(numerator_code, denominator_code) constant_parameters <- NULL - if (constant_dividend) { - constant_parameters <- c(constant_parameters, dividend_code) + if (constant_numerator) { + constant_parameters <- c(constant_parameters, numerator_code) parameters <- parameters %>% - .[!. == dividend_code] + .[!. == numerator_code] } - if (constant_divisor) { - constant_parameters <- c(constant_parameters, divisor_code) + if (constant_denominator) { + constant_parameters <- c(constant_parameters, denominator_code) parameters <- parameters %>% - .[!. == divisor_code] %>% + .[!. == denominator_code] %>% ifelse(length(.) == 0, NULL, .) } - result <- dataset %>% - derive_param_computed( - filter = !!filter, - parameters = parameters, - by_vars = by_vars, - set_values_to = exprs( - AVAL = !!ratio_formula, - !!!set_values_to - ), - constant_parameters = constant_parameters, - constant_by_vars = constant_by_vars - ) + ### Call the core {admiral} function to derive Ratio parameter ---- + + derive_param_computed( + dataset, + filter = !!filter, + parameters = parameters, + by_vars = by_vars, + set_values_to = exprs( + AVAL = !!ratio_formula, + !!!set_values_to + ), + constant_parameters = constant_parameters, + constant_by_vars = constant_by_vars + ) +} - if ("mixed_units" %in% class(result$AVAL)) { - # Drop units from AVAL context - result$AVAL <- drop_units(result$AVAL) +get_conv_factor <- function(from_unit, to_unit) { + # Get all conversion factors supported + conv_factors_all <- get_conv_factors_all() + + # Return conversion factor if units are supported and convertible + for (unit_category in names(conv_factors_all)) { + if (all(c(from_unit, to_unit) %in% names(conv_factors_all[[unit_category]]))) { + return( + conv_factors_all[[unit_category]][[from_unit]] / + conv_factors_all[[unit_category]][[to_unit]] + ) + } } - result + # If units are not supported/convertible + return(NA_real_) +} + +get_conv_factors_all <- function() { + list( + # Conversion factors for length relative to centimeters + length = list( + "cm" = 1, + "m" = 100, + "mm" = 0.1, + "in" = 2.54, + "ft" = 30.48 + ) + ) } diff --git a/man/derive_param_ratio.Rd b/man/derive_param_ratio.Rd index 059f282..3f9f25a 100644 --- a/man/derive_param_ratio.Rd +++ b/man/derive_param_ratio.Rd @@ -7,11 +7,11 @@ derive_param_ratio( dataset, by_vars, - dividend_code, - divisor_code, + numerator_code, + denominator_code, set_values_to, - constant_dividend = FALSE, - constant_divisor = FALSE, + constant_numerator = FALSE, + constant_denominator = FALSE, filter = NULL, constant_by_vars = NULL, get_unit_expr = NULL @@ -24,8 +24,8 @@ The variables specified by the \code{by_vars} argument are expected to be in the \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} -parameter) and to the parameters specified by \code{dividend_code} and \code{divisor_code}.} +the input dataset after restricting it by the filter condition (\code{filter} argument) +and to the parameters specified by \code{numerator_code} and \code{denominator_code}.} \item{by_vars}{Grouping variables @@ -36,17 +36,17 @@ in the newly created records. \emph{Permitted Values}: list of variables created by \code{exprs()} e.g. \code{exprs(USUBJID, VISIT)}} -\item{dividend_code}{Dividend parameter code +\item{numerator_code}{Numerator parameter code The observations where \code{PARAMCD} equals the specified value are considered -as the dividend +as the numerator \emph{Permitted Values:} character value} -\item{divisor_code}{Divisor parameter code +\item{denominator_code}{Denominator parameter code The observations where \code{PARAMCD} equals the specified value are considered -as the divisor +as the denominator \emph{Permitted Values:} character value} @@ -58,23 +58,23 @@ for the new parameter. \emph{Permitted Values}: List of variable-value pairs} -\item{constant_dividend}{Is dividend parameter constant? +\item{constant_numerator}{Is numerator parameter constant? -It is expected that the parameter code (PARAMCD) specified in \code{dividend_code} +It is expected that the parameter code (PARAMCD) specified in \code{numerator_code} which is required to derive the new parameter is measured only once. For example, -if Height-to-Weight Ratio should be derived and height is measured only once -while Weight is measured at each visit. Height could be specified -in the \code{dividend_code} argument and \code{constant_dividend} is to be set to \code{TRUE}. +if Height to Weight Ratio should be derived and height is measured only once +while Weight is measured at each visit. Height could be specified in the +\code{numerator_code} argument and \code{constant_numerator} is to be set to \code{TRUE}. \emph{Permitted Values:} logical scalar} -\item{constant_divisor}{Is divisor parameter constant? +\item{constant_denominator}{Is denominator parameter constant? -It is expected that the parameter code (PARAMCD) specified in \code{dividend_code} +It is expected that the parameter code (PARAMCD) specified in \code{numerator_code} which is required to derive the new parameter is measured only once. For example, -if Waist-to-Height Ratio should be derived and height is measured only once -while Waist Circumference is measured at each visit. Height could be specified -in the \code{divisor_code} argument and \code{constant_divisor} is to be set to \code{TRUE}. +if Waist to Height Ratio should be derived and height is measured only once +while Waist Circumference is measured at each visit. Height could be specified in the +\code{denominator_code} argument and \code{constant_denominator} is to be set to \code{TRUE}. \emph{Permitted Values:} logical scalar} @@ -86,16 +86,16 @@ into account. \emph{Permitted Values:} a condition} -\item{constant_by_vars}{By variables for when dividend and/or divisor is constant +\item{constant_by_vars}{By variables for when numerator and/or denominator is constant -When dividend and/or divisor is constant, the parameters (measured only once) are merged +When numerator and/or denominator is constant, the parameters (measured only once) are merged to the other parameters using the specified variables. -If dividend and/or divisor is constant (e.g. only measured once at screening or baseline) -then use \code{constant_by_vars} to select the subject-level variable to merge on -(e.g. \code{USUBJID}). This will produce a generic Ratio parameter at all visits where dividend -and/or divisor is measured. Otherwise it will only be calculated at visits with both dividend -and divisor parameters collected. +If numerator and/or denominator is constant (e.g. only measured once at screening or baseline) +then use \code{constant_by_vars} to select the subject-level variable to merge on (e.g. +\code{USUBJID}). This will produce a generic Ratio parameter at all visits where numerator +and/or denominator is measured. Otherwise it will only be calculated at visits with both +numerator and denominator parameters collected. \emph{Permitted Values}: list of variables created by \code{exprs()} e.g. \code{exprs(USUBJID, VISIT)}} @@ -117,14 +117,14 @@ be populated in the new parameter rows if it is specified in \code{by_vars}. } \description{ Adds a record for a generic Ratio parameter using two existing parameter -(dividend and divisor) each by group (e.g., subject and visit) where the source parameters +(numerator and denominator) each by group (e.g., subject and visit) where the source parameters are available. \strong{Note:} This is a wrapper function for the more generic \code{derive_param_computed()} } \details{ The analysis value of the new parameter is derived as -\deqn{RATIO = \frac{DIVIDENT}{DIVISOR}} +\deqn{RATIO = \frac{NUMERATOR}{DENOMINATOR}} } \seealso{ Other internal: diff --git a/man/derive_param_waisthgt.Rd b/man/derive_param_waisthgt.Rd index f62de48..a69d2e8 100644 --- a/man/derive_param_waisthgt.Rd +++ b/man/derive_param_waisthgt.Rd @@ -22,8 +22,8 @@ The variables specified by the \code{by_vars} argument are expected to be in the \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} -parameter) and to the parameters specified by \code{wstcir_code} and \code{height_code}.} +the input dataset after restricting it by the filter condition (\code{filter} argument) +and to the parameters specified by \code{wstcir_code} and \code{height_code}.} \item{by_vars}{Grouping variables diff --git a/man/derive_param_waisthip.Rd b/man/derive_param_waisthip.Rd index 4ac16cf..76f4a1a 100644 --- a/man/derive_param_waisthip.Rd +++ b/man/derive_param_waisthip.Rd @@ -21,8 +21,8 @@ The variables specified by the \code{by_vars} argument are expected to be in the \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} -parameter) and to the parameters specified by \code{wstcir_code} and \code{hipcir_code}.} +the input dataset after restricting it by the filter condition (\code{filter} argument) +and to the parameters specified by \code{wstcir_code} and \code{hipcir_code}.} \item{by_vars}{Grouping variables From 0fd9e8f2a05807a8730664542d5252b17ad555d2 Mon Sep 17 00:00:00 2001 From: Andrii Yurovskyi Date: Sun, 20 Oct 2024 12:24:11 +0200 Subject: [PATCH 10/28] (#31): Update keywords --- R/derive_advs_params.R | 8 ++++---- R/derive_bds_params.R | 16 ++++++++++++++++ _pkgdown.yml | 6 +++--- man/derive_param_waisthgt.Rd | 6 +++--- man/derive_param_waisthip.Rd | 6 +++--- man/unit-conversion.Rd | 19 +++++++++++++++++++ 6 files changed, 48 insertions(+), 13 deletions(-) create mode 100644 man/unit-conversion.Rd diff --git a/R/derive_advs_params.R b/R/derive_advs_params.R index 11b3402..2c32b51 100644 --- a/R/derive_advs_params.R +++ b/R/derive_advs_params.R @@ -39,8 +39,8 @@ #' @return The input dataset with the new parameter added. Note, a variable will only #' be populated in the new parameter rows if it is specified in \code{by_vars}. #' -#' @family der_prm_adxx -#' @keywords der_prm_adxx +#' @family der_prm_advs +#' @keywords der_prm_advs #' #' @export #' @@ -190,8 +190,8 @@ derive_param_waisthip <- function(dataset, #' @return The input dataset with the new parameter added. Note, a variable will only #' be populated in the new parameter rows if it is specified in \code{by_vars}. #' -#' @family der_prm_adxx -#' @keywords der_prm_adxx +#' @family der_prm_advs +#' @keywords der_prm_advs #' #' @export #' diff --git a/R/derive_bds_params.R b/R/derive_bds_params.R index 79e005f..72eaf92 100644 --- a/R/derive_bds_params.R +++ b/R/derive_bds_params.R @@ -202,6 +202,18 @@ derive_param_ratio <- function(dataset, ) } +#' Unit conversion +#' +#' @name unit-conversion +#' @keywords internal +NULL +#> NULL + +#' @description `get_conv_factor()` extracts a conversion factor for a pair of units. +#' Returns `NA` if units are not supported/convertible. +#' +#' @rdname unit-conversion +#' @keywords internal get_conv_factor <- function(from_unit, to_unit) { # Get all conversion factors supported conv_factors_all <- get_conv_factors_all() @@ -220,6 +232,10 @@ get_conv_factor <- function(from_unit, to_unit) { return(NA_real_) } +#' @description `get_conv_factors_all()` returns all conversion factors supported. +#' +#' @rdname unit-conversion +#' @keywords internal get_conv_factors_all <- function() { list( # Conversion factors for length relative to centimeters diff --git a/_pkgdown.yml b/_pkgdown.yml index 158aade..d93adec 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -26,10 +26,10 @@ reference: - has_keyword("der_adxx") - title: Derivations for Adding Parameters -- subtitle: ADXX-specific - desc: Parameter Derivation Functions helpful for building the ADXX dataset +- subtitle: ADVS-specific + desc: Parameter Derivation Functions helpful for building the ADVS dataset - contents: - - has_keyword("der_prm_adxx") + - has_keyword("der_prm_advs") - title: Advanced Functions - subtitle: Pre-Defined Source Objects diff --git a/man/derive_param_waisthgt.Rd b/man/derive_param_waisthgt.Rd index a69d2e8..1731a44 100644 --- a/man/derive_param_waisthgt.Rd +++ b/man/derive_param_waisthgt.Rd @@ -195,8 +195,8 @@ derive_param_waisthgt( \seealso{ \code{\link[admiral:derive_param_computed]{admiral::derive_param_computed()}} -ADXX Functions for adding Parameters: +Other der_prm_advs: \code{\link{derive_param_waisthip}()} } -\concept{der_prm_adxx} -\keyword{der_prm_adxx} +\concept{der_prm_advs} +\keyword{der_prm_advs} diff --git a/man/derive_param_waisthip.Rd b/man/derive_param_waisthip.Rd index 76f4a1a..e295ddb 100644 --- a/man/derive_param_waisthip.Rd +++ b/man/derive_param_waisthip.Rd @@ -155,8 +155,8 @@ derive_param_waisthip( \seealso{ \code{\link[admiral:derive_param_computed]{admiral::derive_param_computed()}} -ADXX Functions for adding Parameters: +Other der_prm_advs: \code{\link{derive_param_waisthgt}()} } -\concept{der_prm_adxx} -\keyword{der_prm_adxx} +\concept{der_prm_advs} +\keyword{der_prm_advs} diff --git a/man/unit-conversion.Rd b/man/unit-conversion.Rd new file mode 100644 index 0000000..7347b71 --- /dev/null +++ b/man/unit-conversion.Rd @@ -0,0 +1,19 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/derive_bds_params.R +\name{unit-conversion} +\alias{unit-conversion} +\alias{get_conv_factor} +\alias{get_conv_factors_all} +\title{Unit conversion} +\usage{ +get_conv_factor(from_unit, to_unit) + +get_conv_factors_all() +} +\description{ +\code{get_conv_factor()} extracts a conversion factor for a pair of units. +Returns \code{NA} if units are not supported/convertible. + +\code{get_conv_factors_all()} returns all conversion factors supported. +} +\keyword{internal} From 37cfd4949bd113020a61183008842c4d042d9913 Mon Sep 17 00:00:00 2001 From: Andrii Yurovskyi Date: Wed, 23 Oct 2024 10:11:43 +0200 Subject: [PATCH 11/28] Update R/derive_advs_params.R Co-authored-by: Edoardo Mancini <53403957+manciniedoardo@users.noreply.github.com> --- R/derive_advs_params.R | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/R/derive_advs_params.R b/R/derive_advs_params.R index 2c32b51..7f51ec8 100644 --- a/R/derive_advs_params.R +++ b/R/derive_advs_params.R @@ -1,7 +1,7 @@ #' Adds a Parameter for Waist to Hip Ratio #' #' @description Adds a record for Waist to Hip Ratio using Waist Circumference and Hip Circumference -#' each by group (e.g., subject and visit) where the source parameters are available. +#' for each by group (e.g., subject and visit) where the source parameters are available. #' #' **Note:** This is a wrapper function for the more generic #' \code{admiral::derive_param_computed()}. From 84f39c455558ababe2ea3c6521d1166bf8392b10 Mon Sep 17 00:00:00 2001 From: Andrii Yurovskyi Date: Wed, 23 Oct 2024 10:14:55 +0200 Subject: [PATCH 12/28] Apply suggestions from code review Co-authored-by: Edoardo Mancini <53403957+manciniedoardo@users.noreply.github.com> --- R/derive_advs_params.R | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/R/derive_advs_params.R b/R/derive_advs_params.R index 7f51ec8..ecccae6 100644 --- a/R/derive_advs_params.R +++ b/R/derive_advs_params.R @@ -18,7 +18,7 @@ #' @param wstcir_code Waist Circumference parameter code #' #' The observations where \code{PARAMCD} equals the specified value are considered -#' as the Waist Circumference +#' as the Waist Circumference. #' #' *Permitted Values:* character value #' @@ -47,7 +47,6 @@ #' @seealso \code{\link[admiral:derive_param_computed]{admiral::derive_param_computed()}} #' #' @examples -#' #' library(tibble) #' library(rlang) #' @@ -138,7 +137,7 @@ derive_param_waisthip <- function(dataset, #' Adds a Parameter for Waist to Height Ratio #' #' @description Adds a record for Waist to Height Ratio using Waist Circumference and Height -#' each by group (e.g., subject and visit) where the source parameters are available. +#' for each by group (e.g., subject and visit) where the source parameters are available. #' #' **Note:** This is a wrapper function for the more generic #' \code{admiral::derive_param_computed()}. @@ -155,7 +154,7 @@ derive_param_waisthip <- function(dataset, #' @param wstcir_code Waist Circumference parameter code #' #' The observations where \code{PARAMCD} equals the specified value are considered -#' as the Waist Circumference +#' as the Waist Circumference. #' #' *Permitted Values:* character value #' @@ -198,7 +197,6 @@ derive_param_waisthip <- function(dataset, #' @seealso \code{\link[admiral:derive_param_computed]{admiral::derive_param_computed()}} #' #' @examples -#' #' library(tibble) #' library(rlang) #' From 8024de22710d6f3a9554bfd4c01a95c9871267ab Mon Sep 17 00:00:00 2001 From: Andrii Yurovskyi Date: Wed, 23 Oct 2024 13:31:59 +0200 Subject: [PATCH 13/28] Addressed review comments --- R/derive_advs_params.R | 291 ++++++++++++++++++++++- R/derive_bds_params.R | 250 ------------------- man/derive_param_ratio.Rd | 7 +- man/derive_param_waisthgt.Rd | 30 ++- man/derive_param_waisthip.Rd | 23 +- man/roxygen/meta.R | 2 +- man/unit-conversion.Rd | 4 +- tests/testthat/test-derive_param_ratio.R | 98 ++++++++ 8 files changed, 437 insertions(+), 268 deletions(-) delete mode 100644 R/derive_bds_params.R create mode 100644 tests/testthat/test-derive_param_ratio.R diff --git a/R/derive_advs_params.R b/R/derive_advs_params.R index ecccae6..f1ac2e1 100644 --- a/R/derive_advs_params.R +++ b/R/derive_advs_params.R @@ -77,6 +77,20 @@ #' ) #' ) #' +#' # Only adding Waist to Hip Ratio at certain visits +#' +#' derive_param_waisthip( +#' advs, +#' by_vars = exprs(USUBJID, VISIT), +#' wstcir_code = "WSTCIR", +#' hipcir_code = "HIPCIR", +#' set_values_to = exprs( +#' PARAMCD = "WAISTHIP", +#' PARAM = "Waist to Hip Ratio" +#' ), +#' filter = VISIT %in% c("SCREENING", "WEEK 3") +#' ) +#' #' # Automatic conversion is performed when deriving the ratio #' # if parameters are provided in different units #' @@ -161,7 +175,7 @@ derive_param_waisthip <- function(dataset, #' @param height_code Height parameter code #' #' The observations where \code{PARAMCD} equals the specified value are considered -#' as the Height. It is expected that Height is measured in cm +#' as the Height. #' #' *Permitted Values:* character value #' @@ -226,7 +240,22 @@ derive_param_waisthip <- function(dataset, #' constant_by_vars = exprs(USUBJID) #' ) #' -#' # Example 2: Pediatric study where Height and Waist Circumference are measured multiple times +#' # Example 2: Same as above but only adding Waist to Height Ratio at certain visits +#' +#' derive_param_waisthgt( +#' advs, +#' by_vars = exprs(USUBJID, VISIT), +#' wstcir_code = "WSTCIR", +#' height_code = "HEIGHT", +#' set_values_to = exprs( +#' PARAMCD = "WAISTHGT", +#' PARAM = "Waist to Height Ratio" +#' ), +#' constant_by_vars = exprs(USUBJID), +#' filter = VISIT %in% c("SCREENING", "WEEK 3") +#' ) +#' +#' # Example 3: Pediatric study where Height and Waist Circumference are measured multiple times #' #' advs <- tribble( #' ~USUBJID, ~PARAMCD, ~PARAM, ~AVAL, ~AVALU, ~VISIT, @@ -255,7 +284,7 @@ derive_param_waisthip <- function(dataset, #' ) #' ) #' -#' # Example 3: Automatic conversion is performed when deriving the ratio +#' # Example 4: Automatic conversion is performed when deriving the ratio #' # if parameters are provided in different units (e.g. centimeters and inches) #' #' advs <- tribble( @@ -313,3 +342,259 @@ derive_param_waisthgt <- function(dataset, get_unit_expr = !!get_unit_expr ) } + +#' Adds a Ratio Parameter Computed from the Analysis Value of Other Parameters +#' +#' @description Adds a record for a generic Ratio parameter using two existing parameter +#' (numerator and denominator) each by group (e.g., subject and visit) where the source parameters +#' are available. +#' +#' **Note:** This is a wrapper function for the more generic +#' \code{admiral::derive_param_computed()}. +#' +#' @param dataset Input dataset +#' +#' The variables specified by the \code{by_vars} argument are expected to be in the dataset. +#' \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} argument) +#' and to the parameters specified by \code{numerator_code} and \code{denominator_code}. +#' +#' @param numerator_code Numerator parameter code +#' +#' The observations where \code{PARAMCD} equals the specified value are considered +#' as the numerator +#' +#' *Permitted Values:* character value +#' +#' @param denominator_code Denominator parameter code +#' +#' The observations where \code{PARAMCD} equals the specified value are considered +#' as the denominator +#' +#' *Permitted Values:* character value +#' +#' @param constant_numerator Is numerator parameter constant? +#' +#' It is expected that the parameter code (PARAMCD) specified in \code{numerator_code} +#' which is required to derive the new parameter is measured only once. For example, +#' if Height to Weight Ratio should be derived and height is measured only once +#' while Weight is measured at each visit. Height could be specified in the +#' \code{numerator_code} argument and \code{constant_numerator} is to be set to \code{TRUE}. +#' +#' *Permitted Values:* logical scalar +#' +#' @param constant_denominator Is denominator parameter constant? +#' +#' It is expected that the parameter code (PARAMCD) specified in \code{numerator_code} +#' which is required to derive the new parameter is measured only once. For example, +#' if Waist to Height Ratio should be derived and height is measured only once +#' while Waist Circumference is measured at each visit. Height could be specified in the +#' \code{denominator_code} argument and \code{constant_denominator} is to be set to \code{TRUE}. +#' +#' *Permitted Values:* logical scalar +#' +#' @param constant_by_vars By variables for when numerator and/or denominator is constant +#' +#' When numerator and/or denominator is constant, the parameters (measured only once) are merged +#' to the other parameters using the specified variables. +#' +#' If numerator and/or denominator is constant (e.g. only measured once at screening or baseline) +#' then use \code{constant_by_vars} to select the subject-level variable to merge on (e.g. +#' \code{USUBJID}). This will produce a generic Ratio parameter at all visits where numerator +#' and/or denominator is measured. Otherwise it will only be calculated at visits with both +#' numerator and denominator parameters collected. +#' +#' *Permitted Values*: list of variables created by \code{exprs()} +#' e.g. \code{exprs(USUBJID, VISIT)} +#' +#' @param get_unit_expr An expression providing the unit of the parameter +#' +#' The result is used to check the units of the input parameters. If the units are not consistent +#' within each parameter, an error will be thrown. +#' +#' Additionally, if the input parameters are measured in different units but are mutually +#' convertible (e.g., centimeters for one parameter and inches for another), an automatic +#' conversion will be performed in order to uniform the values before calculating the ratio. +#' +#' **Note:** Conversion factors comes from unit definitions as per the NCI Thesaurus +#' +#' *Permitted Values:* A variable of the input dataset or a function call +#' +#' @inheritParams admiral::derive_param_bmi +#' +#' @details +#' The analysis value of the new parameter is derived as +#' \deqn{RATIO = \frac{NUMERATOR}{DENOMINATOR}} +#' +#' +#' @return The input dataset with the new parameter added. Note, a variable will only +#' be populated in the new parameter rows if it is specified in \code{by_vars}. +#' +#' @family internal +#' @keywords internal +derive_param_ratio <- function(dataset, + by_vars, + numerator_code, + denominator_code, + set_values_to, + constant_numerator = FALSE, + constant_denominator = FALSE, + filter = NULL, + constant_by_vars = NULL, + get_unit_expr = NULL) { + assert_vars(by_vars) + assert_data_frame(dataset, required_vars = exprs(!!!by_vars, PARAMCD, AVAL)) + assert_character_scalar(numerator_code) + assert_character_scalar(denominator_code) + assert_varval_list(set_values_to, required_elements = "PARAMCD") + assert_param_does_not_exist(dataset, set_values_to$PARAMCD) + assert_logical_scalar(constant_numerator) + assert_logical_scalar(constant_denominator) + filter <- assert_filter_cond(enexpr(filter), optional = TRUE) + assert_vars(constant_by_vars, optional = TRUE) + get_unit_expr <- assert_expr(enexpr(get_unit_expr), optional = TRUE) + + ### Default formula with no units conversion applied ---- + + ratio_formula <- expr( + !!sym(paste0("AVAL.", numerator_code)) / + !!sym(paste0("AVAL.", denominator_code)) + ) + + ### If `get_unit_expr` provided then check units and enable units conversion ---- + + if (!missing(get_unit_expr) && !is.null(get_unit_expr)) { + param_units <- list() + + # Check if units are the same within each of two parameters + + for (param in c(numerator_code, denominator_code)) { + units_found <- dataset %>% + mutate(`_unit` = !!get_unit_expr) %>% + filter(PARAMCD == param) %>% + pull(`_unit`) %>% + unique() + + if (length(units_found) != 1L) { + cli_abort( + "Multiple units {.val {units_found}} found for {.val {param}}. + Please review and update the units." + ) + } + + param_units[[param]] <- units_found + } + + # If the input parameters are measured in different units + # but are convertible from one to another (and this kind of conversion supported) + # then modify the formula in order to perform units conversion on the fly + + if (param_units[[denominator_code]] != param_units[[numerator_code]]) { + # Find conversion factor for denominator + conv_factor <- get_conv_factor( + param_units[[denominator_code]], + param_units[[numerator_code]] + ) + + if (!is.na(conv_factor)) { + ratio_formula <- expr( + !!sym(paste0("AVAL.", numerator_code)) / ( + !!sym(paste0("AVAL.", denominator_code)) * !!conv_factor + ) + ) + + cli_alert_info( + "Unit conversion performed for {.val {denominator_code}}. Values converted from + {.val {param_units[[denominator_code]]}} to {.val {param_units[[numerator_code]]}}.", + wrap = TRUE + ) + } + } + } + + ### Identify constant parameters ---- + + parameters <- c(numerator_code, denominator_code) + constant_parameters <- NULL + + if (constant_numerator) { + constant_parameters <- c(constant_parameters, numerator_code) + + parameters <- parameters %>% + .[!. == numerator_code] + } + + if (constant_denominator) { + constant_parameters <- c(constant_parameters, denominator_code) + + parameters <- parameters %>% + .[!. == denominator_code] %>% + ifelse(length(.) == 0, NULL, .) + } + + ### Call the core {admiral} function to derive Ratio parameter ---- + + derive_param_computed( + dataset, + filter = !!filter, + parameters = parameters, + by_vars = by_vars, + set_values_to = exprs( + AVAL = !!ratio_formula, + !!!set_values_to + ), + constant_parameters = constant_parameters, + constant_by_vars = constant_by_vars + ) +} + +#' Unit conversion +#' +#' @name unit-conversion +#' @keywords internal +NULL +#> NULL + +#' @description `get_conv_factor()` extracts a conversion factor for a pair of units. +#' Returns `NA` if units are not supported/convertible. +#' +#' @rdname unit-conversion +#' @keywords internal +get_conv_factor <- function(from_unit, to_unit) { + # Get all conversion factors supported + conv_factors_all <- get_conv_factors_all() + + # Return conversion factor if units are supported and convertible + for (unit_category in names(conv_factors_all)) { + if (all(c(from_unit, to_unit) %in% names(conv_factors_all[[unit_category]]))) { + return( + conv_factors_all[[unit_category]][[from_unit]] / + conv_factors_all[[unit_category]][[to_unit]] + ) + } + } + + # If units are not supported/convertible + return(NA_real_) +} + +#' @description `get_conv_factors_all()` returns all conversion factors supported. +#' +#' **Note:** Conversion factor for inch comes from the NCI Thesaurus +#' +#' @rdname unit-conversion +#' @keywords internal +get_conv_factors_all <- function() { + list( + # Conversion factors for length relative to centimeters + length = list( + "cm" = 1, + "m" = 100, + "mm" = 0.1, + "in" = 2.54, + "ft" = 30.48 + ) + ) +} diff --git a/R/derive_bds_params.R b/R/derive_bds_params.R deleted file mode 100644 index 72eaf92..0000000 --- a/R/derive_bds_params.R +++ /dev/null @@ -1,250 +0,0 @@ -#' Adds a Ratio Parameter Computed from the Analysis Value of Other Parameters -#' -#' @description Adds a record for a generic Ratio parameter using two existing parameter -#' (numerator and denominator) each by group (e.g., subject and visit) where the source parameters -#' are available. -#' -#' **Note:** This is a wrapper function for the more generic \code{derive_param_computed()} -#' -#' @param dataset Input dataset -#' -#' The variables specified by the \code{by_vars} argument are expected to be in the dataset. -#' \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} argument) -#' and to the parameters specified by \code{numerator_code} and \code{denominator_code}. -#' -#' @param numerator_code Numerator parameter code -#' -#' The observations where \code{PARAMCD} equals the specified value are considered -#' as the numerator -#' -#' *Permitted Values:* character value -#' -#' @param denominator_code Denominator parameter code -#' -#' The observations where \code{PARAMCD} equals the specified value are considered -#' as the denominator -#' -#' *Permitted Values:* character value -#' -#' @param constant_numerator Is numerator parameter constant? -#' -#' It is expected that the parameter code (PARAMCD) specified in \code{numerator_code} -#' which is required to derive the new parameter is measured only once. For example, -#' if Height to Weight Ratio should be derived and height is measured only once -#' while Weight is measured at each visit. Height could be specified in the -#' \code{numerator_code} argument and \code{constant_numerator} is to be set to \code{TRUE}. -#' -#' *Permitted Values:* logical scalar -#' -#' @param constant_denominator Is denominator parameter constant? -#' -#' It is expected that the parameter code (PARAMCD) specified in \code{numerator_code} -#' which is required to derive the new parameter is measured only once. For example, -#' if Waist to Height Ratio should be derived and height is measured only once -#' while Waist Circumference is measured at each visit. Height could be specified in the -#' \code{denominator_code} argument and \code{constant_denominator} is to be set to \code{TRUE}. -#' -#' *Permitted Values:* logical scalar -#' -#' @param constant_by_vars By variables for when numerator and/or denominator is constant -#' -#' When numerator and/or denominator is constant, the parameters (measured only once) are merged -#' to the other parameters using the specified variables. -#' -#' If numerator and/or denominator is constant (e.g. only measured once at screening or baseline) -#' then use \code{constant_by_vars} to select the subject-level variable to merge on (e.g. -#' \code{USUBJID}). This will produce a generic Ratio parameter at all visits where numerator -#' and/or denominator is measured. Otherwise it will only be calculated at visits with both -#' numerator and denominator parameters collected. -#' -#' *Permitted Values*: list of variables created by \code{exprs()} -#' e.g. \code{exprs(USUBJID, VISIT)} -#' -#' @param get_unit_expr An expression providing the unit of the parameter -#' -#' The result is used to check the units of the input parameters. If the units are not consistent -#' within each parameter, an error will be thrown. -#' -#' Additionally, if the input parameters are measured in different units but are mutually -#' convertible (e.g., centimeters for one parameter and inches for another), an automatic -#' conversion will be performed in order to uniform the values before calculating the ratio. -#' -#' *Permitted Values:* A variable of the input dataset or a function call -#' -#' @inheritParams admiral::derive_param_bmi -#' -#' @details -#' The analysis value of the new parameter is derived as -#' \deqn{RATIO = \frac{NUMERATOR}{DENOMINATOR}} -#' -#' -#' @return The input dataset with the new parameter added. Note, a variable will only -#' be populated in the new parameter rows if it is specified in \code{by_vars}. -#' -#' @family internal -#' @keywords internal -derive_param_ratio <- function(dataset, - by_vars, - numerator_code, - denominator_code, - set_values_to, - constant_numerator = FALSE, - constant_denominator = FALSE, - filter = NULL, - constant_by_vars = NULL, - get_unit_expr = NULL) { - assert_vars(by_vars) - assert_data_frame(dataset, required_vars = exprs(!!!by_vars, PARAMCD, AVAL)) - assert_character_scalar(numerator_code) - assert_character_scalar(denominator_code) - assert_varval_list(set_values_to, required_elements = "PARAMCD") - assert_param_does_not_exist(dataset, set_values_to$PARAMCD) - assert_logical_scalar(constant_numerator) - assert_logical_scalar(constant_denominator) - filter <- assert_filter_cond(enexpr(filter), optional = TRUE) - assert_vars(constant_by_vars, optional = TRUE) - get_unit_expr <- assert_expr(enexpr(get_unit_expr), optional = TRUE) - - ### Default formula with no units conversion applied ---- - - ratio_formula <- expr( - !!sym(paste0("AVAL.", numerator_code)) / - !!sym(paste0("AVAL.", denominator_code)) - ) - - ### If `get_unit_expr` provided then check units and enable units conversion ---- - - if (!missing(get_unit_expr) && !is.null(get_unit_expr)) { - param_units <- list() - - # Check if units are the same within each of two parameters - - for (param in c(numerator_code, denominator_code)) { - units_found <- dataset %>% - mutate(`_unit` = !!get_unit_expr) %>% - filter(PARAMCD == param) %>% - pull(`_unit`) %>% - unique() - - if (length(units_found) != 1L) { - cli_abort( - "Multiple units {.val {units_found}} found for {.val {param}}. - Please review and update the units." - ) - } - - param_units[[param]] <- units_found - } - - # If the input parameters are measured in different units - # but are convertible from one to another (and this kind of conversion supported) - # then modify the formula in order to perform units conversion on the fly - - if (param_units[[denominator_code]] != param_units[[numerator_code]]) { - # Find conversion factor for denominator - conv_factor <- get_conv_factor( - param_units[[denominator_code]], - param_units[[numerator_code]] - ) - - if (!is.na(conv_factor)) { - ratio_formula <- expr( - !!sym(paste0("AVAL.", numerator_code)) / ( - !!sym(paste0("AVAL.", denominator_code)) * !!conv_factor - ) - ) - - cli_alert_info( - "Unit conversion performed for {.val {denominator_code}}. Values converted from - {.val {param_units[[denominator_code]]}} to {.val {param_units[[numerator_code]]}}.", - wrap = TRUE - ) - } - } - } - - ### Identify constant parameters ---- - - parameters <- c(numerator_code, denominator_code) - constant_parameters <- NULL - - if (constant_numerator) { - constant_parameters <- c(constant_parameters, numerator_code) - - parameters <- parameters %>% - .[!. == numerator_code] - } - - if (constant_denominator) { - constant_parameters <- c(constant_parameters, denominator_code) - - parameters <- parameters %>% - .[!. == denominator_code] %>% - ifelse(length(.) == 0, NULL, .) - } - - ### Call the core {admiral} function to derive Ratio parameter ---- - - derive_param_computed( - dataset, - filter = !!filter, - parameters = parameters, - by_vars = by_vars, - set_values_to = exprs( - AVAL = !!ratio_formula, - !!!set_values_to - ), - constant_parameters = constant_parameters, - constant_by_vars = constant_by_vars - ) -} - -#' Unit conversion -#' -#' @name unit-conversion -#' @keywords internal -NULL -#> NULL - -#' @description `get_conv_factor()` extracts a conversion factor for a pair of units. -#' Returns `NA` if units are not supported/convertible. -#' -#' @rdname unit-conversion -#' @keywords internal -get_conv_factor <- function(from_unit, to_unit) { - # Get all conversion factors supported - conv_factors_all <- get_conv_factors_all() - - # Return conversion factor if units are supported and convertible - for (unit_category in names(conv_factors_all)) { - if (all(c(from_unit, to_unit) %in% names(conv_factors_all[[unit_category]]))) { - return( - conv_factors_all[[unit_category]][[from_unit]] / - conv_factors_all[[unit_category]][[to_unit]] - ) - } - } - - # If units are not supported/convertible - return(NA_real_) -} - -#' @description `get_conv_factors_all()` returns all conversion factors supported. -#' -#' @rdname unit-conversion -#' @keywords internal -get_conv_factors_all <- function() { - list( - # Conversion factors for length relative to centimeters - length = list( - "cm" = 1, - "m" = 100, - "mm" = 0.1, - "in" = 2.54, - "ft" = 30.48 - ) - ) -} diff --git a/man/derive_param_ratio.Rd b/man/derive_param_ratio.Rd index 3f9f25a..464ea1f 100644 --- a/man/derive_param_ratio.Rd +++ b/man/derive_param_ratio.Rd @@ -1,5 +1,5 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/derive_bds_params.R +% Please edit documentation in R/derive_advs_params.R \name{derive_param_ratio} \alias{derive_param_ratio} \title{Adds a Ratio Parameter Computed from the Analysis Value of Other Parameters} @@ -109,6 +109,8 @@ Additionally, if the input parameters are measured in different units but are mu convertible (e.g., centimeters for one parameter and inches for another), an automatic conversion will be performed in order to uniform the values before calculating the ratio. +\strong{Note:} Conversion factors comes from unit definitions as per the NCI Thesaurus + \emph{Permitted Values:} A variable of the input dataset or a function call} } \value{ @@ -120,7 +122,8 @@ Adds a record for a generic Ratio parameter using two existing parameter (numerator and denominator) each by group (e.g., subject and visit) where the source parameters are available. -\strong{Note:} This is a wrapper function for the more generic \code{derive_param_computed()} +\strong{Note:} This is a wrapper function for the more generic +\code{admiral::derive_param_computed()}. } \details{ The analysis value of the new parameter is derived as diff --git a/man/derive_param_waisthgt.Rd b/man/derive_param_waisthgt.Rd index 1731a44..131870e 100644 --- a/man/derive_param_waisthgt.Rd +++ b/man/derive_param_waisthgt.Rd @@ -37,14 +37,14 @@ e.g. \code{exprs(USUBJID, VISIT)}} \item{wstcir_code}{Waist Circumference parameter code The observations where \code{PARAMCD} equals the specified value are considered -as the Waist Circumference +as the Waist Circumference. \emph{Permitted Values:} character value} \item{height_code}{Height parameter code The observations where \code{PARAMCD} equals the specified value are considered -as the Height. It is expected that Height is measured in cm +as the Height. \emph{Permitted Values:} character value} @@ -87,6 +87,8 @@ Additionally, if the input parameters are measured in different units but are mu convertible (e.g., centimeters for one parameter and inches for another), an automatic conversion will be performed in order to uniform the values before calculating the ratio. +\strong{Note:} Conversion factors comes from unit definitions as per the NCI Thesaurus + \emph{Permitted Values:} A variable of the input dataset or a function call} } \value{ @@ -95,7 +97,7 @@ be populated in the new parameter rows if it is specified in \code{by_vars}. } \description{ Adds a record for Waist to Height Ratio using Waist Circumference and Height -each by group (e.g., subject and visit) where the source parameters are available. +for each by group (e.g., subject and visit) where the source parameters are available. \strong{Note:} This is a wrapper function for the more generic \code{admiral::derive_param_computed()}. @@ -105,7 +107,6 @@ The analysis value of the new parameter is derived as \deqn{WAISTHGT = \frac{WSTCIR}{HEIGHT}}{WAISTHGT = WSTCIR / HEIGHT} } \examples{ - library(tibble) library(rlang) @@ -135,7 +136,22 @@ derive_param_waisthgt( constant_by_vars = exprs(USUBJID) ) -# Example 2: Pediatric study where Height and Waist Circumference are measured multiple times +# Example 2: Same as above but only adding Waist to Height Ratio at certain visits + +derive_param_waisthgt( + advs, + by_vars = exprs(USUBJID, VISIT), + wstcir_code = "WSTCIR", + height_code = "HEIGHT", + set_values_to = exprs( + PARAMCD = "WAISTHGT", + PARAM = "Waist to Height Ratio" + ), + constant_by_vars = exprs(USUBJID), + filter = VISIT \%in\% c("SCREENING", "WEEK 3") +) + +# Example 3: Pediatric study where Height and Waist Circumference are measured multiple times advs <- tribble( ~USUBJID, ~PARAMCD, ~PARAM, ~AVAL, ~AVALU, ~VISIT, @@ -164,7 +180,7 @@ derive_param_waisthgt( ) ) -# Example 3: Automatic conversion is performed when deriving the ratio +# Example 4: Automatic conversion is performed when deriving the ratio # if parameters are provided in different units (e.g. centimeters and inches) advs <- tribble( @@ -195,7 +211,7 @@ derive_param_waisthgt( \seealso{ \code{\link[admiral:derive_param_computed]{admiral::derive_param_computed()}} -Other der_prm_advs: +ADVS Functions for adding Parameters: \code{\link{derive_param_waisthip}()} } \concept{der_prm_advs} diff --git a/man/derive_param_waisthip.Rd b/man/derive_param_waisthip.Rd index e295ddb..8a9d12a 100644 --- a/man/derive_param_waisthip.Rd +++ b/man/derive_param_waisthip.Rd @@ -36,7 +36,7 @@ e.g. \code{exprs(USUBJID, VISIT)}} \item{wstcir_code}{Waist Circumference parameter code The observations where \code{PARAMCD} equals the specified value are considered -as the Waist Circumference +as the Waist Circumference. \emph{Permitted Values:} character value} @@ -72,6 +72,8 @@ Additionally, if the input parameters are measured in different units but are mu convertible (e.g., centimeters for one parameter and inches for another), an automatic conversion will be performed in order to uniform the values before calculating the ratio. +\strong{Note:} Conversion factors comes from unit definitions as per the NCI Thesaurus + \emph{Permitted Values:} A variable of the input dataset or a function call} } \value{ @@ -80,7 +82,7 @@ be populated in the new parameter rows if it is specified in \code{by_vars}. } \description{ Adds a record for Waist to Hip Ratio using Waist Circumference and Hip Circumference -each by group (e.g., subject and visit) where the source parameters are available. +for each by group (e.g., subject and visit) where the source parameters are available. \strong{Note:} This is a wrapper function for the more generic \code{admiral::derive_param_computed()}. @@ -90,7 +92,6 @@ The analysis value of the new parameter is derived as \deqn{WAISTHIP = \frac{WSTCIR}{HIPCIR}}{WAISTHIP = WSTCIR / HIPCIR} } \examples{ - library(tibble) library(rlang) @@ -121,6 +122,20 @@ derive_param_waisthip( ) ) +# Only adding Waist to Hip Ratio at certain visits + +derive_param_waisthip( + advs, + by_vars = exprs(USUBJID, VISIT), + wstcir_code = "WSTCIR", + hipcir_code = "HIPCIR", + set_values_to = exprs( + PARAMCD = "WAISTHIP", + PARAM = "Waist to Hip Ratio" + ), + filter = VISIT \%in\% c("SCREENING", "WEEK 3") +) + # Automatic conversion is performed when deriving the ratio # if parameters are provided in different units @@ -155,7 +170,7 @@ derive_param_waisthip( \seealso{ \code{\link[admiral:derive_param_computed]{admiral::derive_param_computed()}} -Other der_prm_advs: +ADVS Functions for adding Parameters: \code{\link{derive_param_waisthgt}()} } \concept{der_prm_advs} diff --git a/man/roxygen/meta.R b/man/roxygen/meta.R index 44feadd..4843f06 100644 --- a/man/roxygen/meta.R +++ b/man/roxygen/meta.R @@ -1,7 +1,7 @@ list( rd_family_title = list( der_adxx = "ADXX Functions that returns variable appended to dataset: ", - der_prm_adxx = "ADXX Functions for adding Parameters: ", + der_prm_advs = "ADVS Functions for adding Parameters: ", com_adxx = "ADXX Functions that returns a vector: ", utils_ds_chk = "Utilities for Dataset Checking: ", utils_fil = "Utilities for Filtering Observations: ", diff --git a/man/unit-conversion.Rd b/man/unit-conversion.Rd index 7347b71..d6d07ce 100644 --- a/man/unit-conversion.Rd +++ b/man/unit-conversion.Rd @@ -1,5 +1,5 @@ % Generated by roxygen2: do not edit by hand -% Please edit documentation in R/derive_bds_params.R +% Please edit documentation in R/derive_advs_params.R \name{unit-conversion} \alias{unit-conversion} \alias{get_conv_factor} @@ -15,5 +15,7 @@ get_conv_factors_all() Returns \code{NA} if units are not supported/convertible. \code{get_conv_factors_all()} returns all conversion factors supported. + +\strong{Note:} Conversion factor for inch comes from the NCI Thesaurus } \keyword{internal} diff --git a/tests/testthat/test-derive_param_ratio.R b/tests/testthat/test-derive_param_ratio.R new file mode 100644 index 0000000..55da3f5 --- /dev/null +++ b/tests/testthat/test-derive_param_ratio.R @@ -0,0 +1,98 @@ +test_that( + "derive_param_ratio Test 1: Cross-check with derive_param_computed()", + { + input <- tribble( + ~USUBJID, ~PARAMCD, ~PARAM, ~AVAL, ~AVALU, ~VISIT, + "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 125, "cm", "SCREENING", + "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 124, "cm", "WEEK 2", + "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 123, "cm", "WEEK 3", + "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 110, "cm", "SCREENING", + "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 108, "cm", "WEEK 2", + "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 107, "cm", "WEEK 3", + "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 135, "cm", "SCREENING", + "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 133, "cm", "WEEK 2", + "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 132, "cm", "WEEK 3", + "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 120, "cm", "SCREENING", + "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 118, "cm", "WEEK 2", + "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 117, "cm", "WEEK 3" + ) + + wrapper_output <- derive_param_ratio( + input, + by_vars = exprs(USUBJID, VISIT), + numerator_code = "WSTCIR", + denominator_code = "HIPCIR", + set_values_to = exprs( + PARAMCD = "WAISTHIP", + PARAM = "Waist-to-Hip Ratio" + ) + ) + + expected_output <- derive_param_computed( + input, + parameters = c("WSTCIR", "HIPCIR"), + by_vars = exprs(USUBJID, VISIT), + set_values_to = exprs( + AVAL = AVAL.WSTCIR / AVAL.HIPCIR, + PARAMCD = "WAISTHIP", + PARAM = "Waist-to-Hip Ratio" + ) + ) + + expect_dfs_equal( + wrapper_output, + expected_output, + keys = c("USUBJID", "PARAMCD", "VISIT") + ) + } +) + +test_that( + "derive_param_computed Test 2: Cross-check with derive_param_computed(), + new observations with constant parameters", + { + input <- tribble( + ~USUBJID, ~PARAMCD, ~PARAM, ~AVAL, ~AVALU, ~VISIT, + "01-101-1001", "HEIGHT", "Height (cm)", 147, "cm", "SCREENING", + "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 110, "cm", "SCREENING", + "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 108, "cm", "WEEK 2", + "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 107, "cm", "WEEK 3", + "01-101-1002", "HEIGHT", "Height (cm)", 163, "cm", "SCREENING", + "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 120, "cm", "SCREENING", + "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 118, "cm", "WEEK 2", + "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 117, "cm", "WEEK 3", + ) + + wrapper_output <- derive_param_ratio( + input, + by_vars = exprs(USUBJID, VISIT), + numerator_code = "WSTCIR", + denominator_code = "HEIGHT", + set_values_to = exprs( + PARAMCD = "WAISTHGT", + PARAM = "Waist-to-Height Ratio" + ), + constant_denominator = TRUE, + constant_by_vars = exprs(USUBJID) + ) + + expected_output <- derive_param_computed( + input, + parameters = "WSTCIR", + by_vars = exprs(USUBJID, VISIT), + set_values_to = exprs( + AVAL = AVAL.WSTCIR / AVAL.HEIGHT, + PARAMCD = "WAISTHGT", + PARAM = "Waist-to-Height Ratio" + ), + constant_parameters = "HEIGHT", + constant_by_vars = exprs(USUBJID) + ) + + expect_dfs_equal( + wrapper_output, + expected_output, + keys = c("USUBJID", "PARAMCD", "VISIT") + ) + } +) From 03f57ed0496e3e7f6f7da6396b53e8c73a26d48f Mon Sep 17 00:00:00 2001 From: Andrii Yurovskyi Date: Wed, 23 Oct 2024 13:36:31 +0200 Subject: [PATCH 14/28] Remove my_first_fcn --- NAMESPACE | 1 - R/my_first_fcn.R | 28 ---------------------------- man/hello_admiral.Rd | 28 ---------------------------- tests/testthat/test-my_first_fcn.R | 20 -------------------- 4 files changed, 77 deletions(-) delete mode 100644 R/my_first_fcn.R delete mode 100644 man/hello_admiral.Rd delete mode 100644 tests/testthat/test-my_first_fcn.R diff --git a/NAMESPACE b/NAMESPACE index f0fd614..84c61f8 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -2,7 +2,6 @@ export(derive_param_waisthgt) export(derive_param_waisthip) -export(hello_admiral) importFrom(admiral,derive_param_computed) importFrom(admiraldev,assert_character_scalar) importFrom(admiraldev,assert_data_frame) diff --git a/R/my_first_fcn.R b/R/my_first_fcn.R deleted file mode 100644 index d0b5269..0000000 --- a/R/my_first_fcn.R +++ /dev/null @@ -1,28 +0,0 @@ -#' Derive Extension Example -#' -#' Says hello admiral -#' -#' @param hw TRUE or FALSE -#' -#' @details In the roxygen documentation you will find tags for family and keywords. -#' This is to create organized sections for the Reference tab on the pkgdown website. -#' You can modify the `_pkgdown.yml` as necessary to create appropriate sections as necessary. -#' Under `./man/roxygen/meta.R`, you will find where to store these family/keywords. -#' -#' @return Happy Message -#' -#' @family der_adxx -#' -#' @keywords der_adxx -#' -#' @export -#' -#' @examples -#' hello_admiral(hw = FALSE) -hello_admiral <- function(hw = TRUE) { - if (hw) { - message("Welcome to the admiral family!") - } else { - message("Welcome to the admiral family!") - } -} diff --git a/man/hello_admiral.Rd b/man/hello_admiral.Rd deleted file mode 100644 index 31d1c3c..0000000 --- a/man/hello_admiral.Rd +++ /dev/null @@ -1,28 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/my_first_fcn.R -\name{hello_admiral} -\alias{hello_admiral} -\title{Derive Extension Example} -\usage{ -hello_admiral(hw = TRUE) -} -\arguments{ -\item{hw}{TRUE or FALSE} -} -\value{ -Happy Message -} -\description{ -Says hello admiral -} -\details{ -In the roxygen documentation you will find tags for family and keywords. -This is to create organized sections for the Reference tab on the pkgdown website. -You can modify the \verb{_pkgdown.yml} as necessary to create appropriate sections as necessary. -Under \code{./man/roxygen/meta.R}, you will find where to store these family/keywords. -} -\examples{ -hello_admiral(hw = FALSE) -} -\concept{der_adxx} -\keyword{der_adxx} diff --git a/tests/testthat/test-my_first_fcn.R b/tests/testthat/test-my_first_fcn.R deleted file mode 100644 index 72e4aac..0000000 --- a/tests/testthat/test-my_first_fcn.R +++ /dev/null @@ -1,20 +0,0 @@ -test_that("hello admiral greets without hw", { - expect_message( - hello_admiral(), - "^Welcome to the admiral family!\\n" - ) -}) - -test_that("hello admiral greets with hw", { - expect_message( - hello_admiral(hw = TRUE), - "^Welcome to the admiral family!\\n" - ) -}) - -test_that("hello admiral greets with hw", { - expect_message( - hello_admiral(hw = FALSE), - "^Welcome to the admiral family!\\n" - ) -}) From 271e2a36db665a69c861d2e449a541ef7b6e3bce Mon Sep 17 00:00:00 2001 From: Andrii Yurovskyi Date: Wed, 23 Oct 2024 13:42:06 +0200 Subject: [PATCH 15/28] Updated WORDLIST --- inst/WORDLIST | 1 + 1 file changed, 1 insertion(+) diff --git a/inst/WORDLIST b/inst/WORDLIST index e48ddf8..0719445 100644 --- a/inst/WORDLIST +++ b/inst/WORDLIST @@ -38,3 +38,4 @@ roxygen advs PARAMCD prm +NCI From 75c92c7b04c85610187e4f4753cd6f8b5881b3af Mon Sep 17 00:00:00 2001 From: Andrii Yurovskyi Date: Sat, 26 Oct 2024 12:17:39 +0200 Subject: [PATCH 16/28] Update as per review comments --- R/derive_advs_params.R | 10 +++++++++- man/derive_param_ratio.Rd | 2 +- man/derive_param_waisthgt.Rd | 2 +- man/derive_param_waisthip.Rd | 2 +- 4 files changed, 12 insertions(+), 4 deletions(-) diff --git a/R/derive_advs_params.R b/R/derive_advs_params.R index f1ac2e1..ce4dccd 100644 --- a/R/derive_advs_params.R +++ b/R/derive_advs_params.R @@ -375,6 +375,14 @@ derive_param_waisthgt <- function(dataset, #' #' *Permitted Values:* character value #' +#' @param set_values_to Variables to be set +#' +#' The specified variables are set to the specified values for the new +#' observations. For example `exprs(PARAMCD = "RATIO")` defines the parameter code +#' for the new parameter. +#' +#' *Permitted Values*: List of variable-value pairs +#' #' @param constant_numerator Is numerator parameter constant? #' #' It is expected that the parameter code (PARAMCD) specified in \code{numerator_code} @@ -422,7 +430,7 @@ derive_param_waisthgt <- function(dataset, #' #' *Permitted Values:* A variable of the input dataset or a function call #' -#' @inheritParams admiral::derive_param_bmi +#' @inheritParams admiral::derive_param_computed #' #' @details #' The analysis value of the new parameter is derived as diff --git a/man/derive_param_ratio.Rd b/man/derive_param_ratio.Rd index 464ea1f..733c67d 100644 --- a/man/derive_param_ratio.Rd +++ b/man/derive_param_ratio.Rd @@ -53,7 +53,7 @@ as the denominator \item{set_values_to}{Variables to be set The specified variables are set to the specified values for the new -observations. For example \code{exprs(PARAMCD = "MAP")} defines the parameter code +observations. For example \code{exprs(PARAMCD = "RATIO")} defines the parameter code for the new parameter. \emph{Permitted Values}: List of variable-value pairs} diff --git a/man/derive_param_waisthgt.Rd b/man/derive_param_waisthgt.Rd index 131870e..aab9124 100644 --- a/man/derive_param_waisthgt.Rd +++ b/man/derive_param_waisthgt.Rd @@ -51,7 +51,7 @@ as the Height. \item{set_values_to}{Variables to be set The specified variables are set to the specified values for the new -observations. For example \code{exprs(PARAMCD = "MAP")} defines the parameter code +observations. For example \code{exprs(PARAMCD = "RATIO")} defines the parameter code for the new parameter. \emph{Permitted Values}: List of variable-value pairs} diff --git a/man/derive_param_waisthip.Rd b/man/derive_param_waisthip.Rd index 8a9d12a..36e69bb 100644 --- a/man/derive_param_waisthip.Rd +++ b/man/derive_param_waisthip.Rd @@ -50,7 +50,7 @@ as the Hip Circumference \item{set_values_to}{Variables to be set The specified variables are set to the specified values for the new -observations. For example \code{exprs(PARAMCD = "MAP")} defines the parameter code +observations. For example \code{exprs(PARAMCD = "RATIO")} defines the parameter code for the new parameter. \emph{Permitted Values}: List of variable-value pairs} From 5274ef0e069bc1ad05153851116aa96db6f997f0 Mon Sep 17 00:00:00 2001 From: Andrii Yurovskyi Date: Sat, 26 Oct 2024 12:21:13 +0200 Subject: [PATCH 17/28] Apply suggestions from code review Co-authored-by: Anders Askeland --- R/derive_advs_params.R | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/R/derive_advs_params.R b/R/derive_advs_params.R index ce4dccd..0b9b826 100644 --- a/R/derive_advs_params.R +++ b/R/derive_advs_params.R @@ -309,7 +309,7 @@ derive_param_waisthip <- function(dataset, #' PARAM = "Waist to Height Ratio" #' ), #' constant_by_vars = exprs(USUBJID), -#' get_unit_expr = AVALU +#' get_unit_expr = admiral::extract_unit(PARAM) #' ) derive_param_waisthgt <- function(dataset, by_vars, @@ -531,16 +531,15 @@ derive_param_ratio <- function(dataset, constant_parameters <- c(constant_parameters, numerator_code) parameters <- parameters %>% - .[!. == numerator_code] + setdiff(numenator_code) } if (constant_denominator) { constant_parameters <- c(constant_parameters, denominator_code) parameters <- parameters %>% - .[!. == denominator_code] %>% - ifelse(length(.) == 0, NULL, .) - } + setdiff(denominator_code) %>% + (\(x) if (length(x) == 0) NULL else x)() ### Call the core {admiral} function to derive Ratio parameter ---- From af058ee252f7f58a10be33cd8676eac0c07c854b Mon Sep 17 00:00:00 2001 From: Andrii Yurovskyi Date: Sat, 26 Oct 2024 12:38:20 +0200 Subject: [PATCH 18/28] Update as per review comments --- R/derive_advs_params.R | 4 ++-- man/derive_param_ratio.Rd | 2 +- man/derive_param_waisthgt.Rd | 2 +- man/derive_param_waisthip.Rd | 2 +- man/unit-conversion.Rd | 2 +- 5 files changed, 6 insertions(+), 6 deletions(-) diff --git a/R/derive_advs_params.R b/R/derive_advs_params.R index 0b9b826..1fa4101 100644 --- a/R/derive_advs_params.R +++ b/R/derive_advs_params.R @@ -426,7 +426,7 @@ derive_param_waisthgt <- function(dataset, #' convertible (e.g., centimeters for one parameter and inches for another), an automatic #' conversion will be performed in order to uniform the values before calculating the ratio. #' -#' **Note:** Conversion factors comes from unit definitions as per the NCI Thesaurus +#' **Note:** Conversion factors come from unit definitions as per the NCI Thesaurus #' #' *Permitted Values:* A variable of the input dataset or a function call #' @@ -589,7 +589,7 @@ get_conv_factor <- function(from_unit, to_unit) { #' @description `get_conv_factors_all()` returns all conversion factors supported. #' -#' **Note:** Conversion factor for inch comes from the NCI Thesaurus +#' **Note:** Conversion factors come from unit definitions as per the NCI Thesaurus #' #' @rdname unit-conversion #' @keywords internal diff --git a/man/derive_param_ratio.Rd b/man/derive_param_ratio.Rd index 733c67d..0cc66f6 100644 --- a/man/derive_param_ratio.Rd +++ b/man/derive_param_ratio.Rd @@ -109,7 +109,7 @@ Additionally, if the input parameters are measured in different units but are mu convertible (e.g., centimeters for one parameter and inches for another), an automatic conversion will be performed in order to uniform the values before calculating the ratio. -\strong{Note:} Conversion factors comes from unit definitions as per the NCI Thesaurus +\strong{Note:} Conversion factors come from unit definitions as per the NCI Thesaurus \emph{Permitted Values:} A variable of the input dataset or a function call} } diff --git a/man/derive_param_waisthgt.Rd b/man/derive_param_waisthgt.Rd index aab9124..00629d2 100644 --- a/man/derive_param_waisthgt.Rd +++ b/man/derive_param_waisthgt.Rd @@ -87,7 +87,7 @@ Additionally, if the input parameters are measured in different units but are mu convertible (e.g., centimeters for one parameter and inches for another), an automatic conversion will be performed in order to uniform the values before calculating the ratio. -\strong{Note:} Conversion factors comes from unit definitions as per the NCI Thesaurus +\strong{Note:} Conversion factors come from unit definitions as per the NCI Thesaurus \emph{Permitted Values:} A variable of the input dataset or a function call} } diff --git a/man/derive_param_waisthip.Rd b/man/derive_param_waisthip.Rd index 36e69bb..5cbe453 100644 --- a/man/derive_param_waisthip.Rd +++ b/man/derive_param_waisthip.Rd @@ -72,7 +72,7 @@ Additionally, if the input parameters are measured in different units but are mu convertible (e.g., centimeters for one parameter and inches for another), an automatic conversion will be performed in order to uniform the values before calculating the ratio. -\strong{Note:} Conversion factors comes from unit definitions as per the NCI Thesaurus +\strong{Note:} Conversion factors come from unit definitions as per the NCI Thesaurus \emph{Permitted Values:} A variable of the input dataset or a function call} } diff --git a/man/unit-conversion.Rd b/man/unit-conversion.Rd index d6d07ce..7dda8d0 100644 --- a/man/unit-conversion.Rd +++ b/man/unit-conversion.Rd @@ -16,6 +16,6 @@ Returns \code{NA} if units are not supported/convertible. \code{get_conv_factors_all()} returns all conversion factors supported. -\strong{Note:} Conversion factor for inch comes from the NCI Thesaurus +\strong{Note:} Conversion factors come from unit definitions as per the NCI Thesaurus } \keyword{internal} From 283de1260f1599b784991762d36c4bdd71c4f2e5 Mon Sep 17 00:00:00 2001 From: Andrii Yurovskyi Date: Sat, 26 Oct 2024 12:48:15 +0200 Subject: [PATCH 19/28] Fix broken code after applying suggestion from code review --- R/derive_advs_params.R | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/R/derive_advs_params.R b/R/derive_advs_params.R index 1fa4101..13a69d7 100644 --- a/R/derive_advs_params.R +++ b/R/derive_advs_params.R @@ -539,7 +539,8 @@ derive_param_ratio <- function(dataset, parameters <- parameters %>% setdiff(denominator_code) %>% - (\(x) if (length(x) == 0) NULL else x)() + (\(x) if (length(x) == 0) NULL else x)() + } ### Call the core {admiral} function to derive Ratio parameter ---- From 65f7d89d9e006558a973d3026a57413a951798b7 Mon Sep 17 00:00:00 2001 From: Andrii Yurovskyi Date: Mon, 28 Oct 2024 21:45:32 +0100 Subject: [PATCH 20/28] Update as per review comments --- NAMESPACE | 3 + R/admiralmetabolic-package.R | 9 ++- R/assertions.R | 62 ++++++++++++++ R/derive_advs_params.R | 85 ++++++++++++------- man/assert_unit.Rd | 90 +++++++++++++++++++++ man/derive_param_waisthgt.Rd | 11 ++- man/derive_param_waisthip.Rd | 6 +- tests/testthat/test-derive_param_ratio.R | 8 +- tests/testthat/test-derive_param_waisthgt.R | 11 ++- tests/testthat/test-derive_param_waisthip.R | 8 +- 10 files changed, 243 insertions(+), 50 deletions(-) create mode 100644 R/assertions.R create mode 100644 man/assert_unit.Rd diff --git a/NAMESPACE b/NAMESPACE index 84c61f8..c0e05bf 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -3,7 +3,9 @@ export(derive_param_waisthgt) export(derive_param_waisthip) importFrom(admiral,derive_param_computed) +importFrom(admiraldev,"%notin%") importFrom(admiraldev,assert_character_scalar) +importFrom(admiraldev,assert_character_vector) importFrom(admiraldev,assert_data_frame) importFrom(admiraldev,assert_expr) importFrom(admiraldev,assert_filter_cond) @@ -68,6 +70,7 @@ importFrom(lubridate,years) importFrom(lubridate,ymd) importFrom(lubridate,ymd_hms) importFrom(magrittr,"%>%") +importFrom(rlang,"%||%") importFrom(rlang,":=") importFrom(rlang,.data) importFrom(rlang,abort) diff --git a/R/admiralmetabolic-package.R b/R/admiralmetabolic-package.R index 3b23065..5435e1b 100644 --- a/R/admiralmetabolic-package.R +++ b/R/admiralmetabolic-package.R @@ -1,8 +1,9 @@ #' @keywords internal #' @family internal -#' @importFrom admiraldev assert_numeric_vector assert_character_scalar assert_logical_scalar -#' assert_data_frame assert_vars assert_varval_list assert_filter_cond -#' assert_param_does_not_exist assert_expr expect_dfs_equal +#' @importFrom admiraldev %notin% assert_numeric_vector assert_character_scalar +#' assert_logical_scalar assert_data_frame assert_vars assert_varval_list +#' assert_filter_cond assert_param_does_not_exist assert_expr expect_dfs_equal +#' assert_character_vector #' @importFrom admiral derive_param_computed #' @importFrom cli cli_abort cli_alert_info #' @importFrom dplyr arrange bind_rows case_when desc ends_with filter full_join group_by @@ -10,7 +11,7 @@ #' starts_with transmute ungroup vars n_distinct union distinct #' summarise_at summarise coalesce bind_cols na_if tibble tribble #' @importFrom magrittr %>% -#' @importFrom rlang := abort arg_match as_function as_string call2 caller_env +#' @importFrom rlang := %||% abort arg_match as_function as_string call2 caller_env #' call_name current_env .data enexpr enexprs enquo eval_bare eval_tidy expr #' exprs expr_interp expr_label f_lhs f_rhs inform #' is_bare_formula is_call is_character is_formula is_integerish diff --git a/R/assertions.R b/R/assertions.R new file mode 100644 index 0000000..62aa7e9 --- /dev/null +++ b/R/assertions.R @@ -0,0 +1,62 @@ +#' Asserts That a Parameter is Provided in One of the Expected Units +#' +#' @description +#' `r lifecycle::badge("deprecated")` +#' +#' This function is to be *deprecated*. Please use `admiraldev::assert_unit()` instead +#' once https://github.com/pharmaverse/admiraldev/issues/468 is closed. +#' +#' @inherit admiraldev::assert_unit +#' +#' @examples +#' # See examples of `admiraldev::assert_unit` +#' +#' @family deprecated +#' @keywords deprecated +assert_unit <- function(dataset, + param, + required_unit, + get_unit_expr, + arg_name = rlang::caller_arg(required_unit), + message = NULL, + class = "assert_unit", + call = parent.frame()) { + assert_data_frame(dataset, required_vars = exprs(PARAMCD)) + assert_character_scalar(param) + assert_character_vector(required_unit) + + get_unit_expr <- enexpr(get_unit_expr) + + units <- dataset %>% + mutate(tmp_unit = !!get_unit_expr) %>% + filter(PARAMCD == param & !is.na(.data$tmp_unit)) %>% + pull(.data$tmp_unit) %>% + unique() + + if (length(units) != 1L) { + message <- + message %||% + "Multiple units {.val {units}} found for {.val {param}}. Please review and update the units." + + cli_abort( + message = message, + call = call, + class = c(class, "assert-admiraldev") + ) + } + + if (tolower(units) %notin% tolower(required_unit)) { + message <- + message %||% + "It is expected that {.val {param}} has unit of {.or {required_unit}}. + In the input dataset the unit is {.val {units}}." + + cli_abort( + message = message, + call = call, + class = c(class, "assert-admiraldev") + ) + } + + invisible(dataset) +} diff --git a/R/derive_advs_params.R b/R/derive_advs_params.R index 13a69d7..9ba8678 100644 --- a/R/derive_advs_params.R +++ b/R/derive_advs_params.R @@ -74,7 +74,8 @@ #' set_values_to = exprs( #' PARAMCD = "WAISTHIP", #' PARAM = "Waist to Hip Ratio" -#' ) +#' ), +#' get_unit_expr = admiral::extract_unit(PARAM) #' ) #' #' # Only adding Waist to Hip Ratio at certain visits @@ -88,6 +89,7 @@ #' PARAMCD = "WAISTHIP", #' PARAM = "Waist to Hip Ratio" #' ), +#' get_unit_expr = admiral::extract_unit(PARAM), #' filter = VISIT %in% c("SCREENING", "WEEK 3") #' ) #' @@ -127,7 +129,7 @@ derive_param_waisthip <- function(dataset, hipcir_code = "HIPCIR", set_values_to = exprs(PARAMCD = "WAISTHIP"), filter = NULL, - get_unit_expr = NULL) { + get_unit_expr) { assert_vars(by_vars) assert_data_frame(dataset, required_vars = exprs(!!!by_vars, PARAMCD, AVAL)) assert_character_scalar(wstcir_code) @@ -135,7 +137,23 @@ derive_param_waisthip <- function(dataset, assert_varval_list(set_values_to, required_elements = "PARAMCD") assert_param_does_not_exist(dataset, set_values_to$PARAMCD) filter <- assert_filter_cond(enexpr(filter), optional = TRUE) - get_unit_expr <- assert_expr(enexpr(get_unit_expr), optional = TRUE) + get_unit_expr <- assert_expr(enexpr(get_unit_expr)) + + units_supported <- names(get_conv_factors_all()[["length"]]) + + assert_unit( + dataset, + param = wstcir_code, + required_unit = units_supported, + get_unit_expr = !!get_unit_expr + ) + + assert_unit( + dataset, + param = hipcir_code, + required_unit = units_supported, + get_unit_expr = !!get_unit_expr + ) derive_param_ratio( dataset, @@ -237,7 +255,8 @@ derive_param_waisthip <- function(dataset, #' PARAMCD = "WAISTHGT", #' PARAM = "Waist to Height Ratio" #' ), -#' constant_by_vars = exprs(USUBJID) +#' constant_by_vars = exprs(USUBJID), +#' get_unit_expr = admiral::extract_unit(PARAM) #' ) #' #' # Example 2: Same as above but only adding Waist to Height Ratio at certain visits @@ -252,6 +271,7 @@ derive_param_waisthip <- function(dataset, #' PARAM = "Waist to Height Ratio" #' ), #' constant_by_vars = exprs(USUBJID), +#' get_unit_expr = admiral::extract_unit(PARAM), #' filter = VISIT %in% c("SCREENING", "WEEK 3") #' ) #' @@ -281,7 +301,8 @@ derive_param_waisthip <- function(dataset, #' set_values_to = exprs( #' PARAMCD = "WAISTHGT", #' PARAM = "Waist to Height Ratio" -#' ) +#' ), +#' get_unit_expr = admiral::extract_unit(PARAM) #' ) #' #' # Example 4: Automatic conversion is performed when deriving the ratio @@ -318,7 +339,7 @@ derive_param_waisthgt <- function(dataset, set_values_to = exprs(PARAMCD = "WAISTHGT"), filter = NULL, constant_by_vars = NULL, - get_unit_expr = NULL) { + get_unit_expr) { assert_vars(by_vars) assert_data_frame(dataset, required_vars = exprs(!!!by_vars, PARAMCD, AVAL)) assert_character_scalar(wstcir_code) @@ -327,7 +348,23 @@ derive_param_waisthgt <- function(dataset, assert_param_does_not_exist(dataset, set_values_to$PARAMCD) filter <- assert_filter_cond(enexpr(filter), optional = TRUE) assert_vars(constant_by_vars, optional = TRUE) - get_unit_expr <- assert_expr(enexpr(get_unit_expr), optional = TRUE) + get_unit_expr <- assert_expr(enexpr(get_unit_expr)) + + units_supported <- names(get_conv_factors_all()[["length"]]) + + assert_unit( + dataset, + param = wstcir_code, + required_unit = units_supported, + get_unit_expr = !!get_unit_expr + ) + + assert_unit( + dataset, + param = height_code, + required_unit = units_supported, + get_unit_expr = !!get_unit_expr + ) derive_param_ratio( dataset, @@ -464,6 +501,12 @@ derive_param_ratio <- function(dataset, assert_vars(constant_by_vars, optional = TRUE) get_unit_expr <- assert_expr(enexpr(get_unit_expr), optional = TRUE) + if (constant_numerator && constant_denominator) { + cli_abort( + "Only one of two input parameters are expected to be constant, or none of them." + ) + } + ### Default formula with no units conversion applied ---- ratio_formula <- expr( @@ -474,31 +517,15 @@ derive_param_ratio <- function(dataset, ### If `get_unit_expr` provided then check units and enable units conversion ---- if (!missing(get_unit_expr) && !is.null(get_unit_expr)) { - param_units <- list() - - # Check if units are the same within each of two parameters - - for (param in c(numerator_code, denominator_code)) { - units_found <- dataset %>% - mutate(`_unit` = !!get_unit_expr) %>% - filter(PARAMCD == param) %>% - pull(`_unit`) %>% - unique() - - if (length(units_found) != 1L) { - cli_abort( - "Multiple units {.val {units_found}} found for {.val {param}}. - Please review and update the units." - ) - } - - param_units[[param]] <- units_found - } - # If the input parameters are measured in different units # but are convertible from one to another (and this kind of conversion supported) # then modify the formula in order to perform units conversion on the fly + param_units <- dataset %>% + mutate(tmp_unit = !!get_unit_expr) %>% + distinct(PARAMCD, .data$tmp_unit) %>% + pull(name = PARAMCD) + if (param_units[[denominator_code]] != param_units[[numerator_code]]) { # Find conversion factor for denominator conv_factor <- get_conv_factor( @@ -531,7 +558,7 @@ derive_param_ratio <- function(dataset, constant_parameters <- c(constant_parameters, numerator_code) parameters <- parameters %>% - setdiff(numenator_code) + setdiff(numerator_code) } if (constant_denominator) { diff --git a/man/assert_unit.Rd b/man/assert_unit.Rd new file mode 100644 index 0000000..78a326c --- /dev/null +++ b/man/assert_unit.Rd @@ -0,0 +1,90 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/assertions.R +\name{assert_unit} +\alias{assert_unit} +\title{Asserts That a Parameter is Provided in One of the Expected Units} +\usage{ +assert_unit( + dataset, + param, + required_unit, + get_unit_expr, + arg_name = rlang::caller_arg(required_unit), + message = NULL, + class = "assert_unit", + call = parent.frame() +) +} +\arguments{ +\item{dataset}{A \code{data.frame}} + +\item{param}{Parameter code of the parameter to check} + +\item{required_unit}{Expected unit} + +\item{get_unit_expr}{Expression used to provide the unit of \code{param}} + +\item{arg_name}{string indicating the label/symbol of the object being checked.} + +\item{message}{string passed to \code{cli::cli_abort(message)}. +When \code{NULL}, default messaging is used (see examples for default messages). +\code{"{arg_name}"} can be used in messaging.} + +\item{class}{Subclass of the condition.} + +\item{call}{The execution environment of a currently running +function, e.g. \code{call = caller_env()}. The corresponding function +call is retrieved and mentioned in error messages as the source +of the error. + +You only need to supply \code{call} when throwing a condition from a +helper function which wouldn't be relevant to mention in the +message. + +Can also be \code{NULL} or a \link[rlang:topic-defuse]{defused function call} to +respectively not display any call or hard-code a code to display. + +For more information about error calls, see \ifelse{html}{\link[rlang:topic-error-call]{Including function calls in error messages}}{\link[rlang:topic-error-call]{Including function calls in error messages}}.} +} +\value{ +The function throws an error if the unit variable differs from the +unit for any observation of the parameter in the input dataset. Otherwise, the +dataset is returned invisibly. +} +\description{ +\ifelse{html}{\href{https://lifecycle.r-lib.org/articles/stages.html#deprecated}{\figure{lifecycle-deprecated.svg}{options: alt='[Deprecated]'}}}{\strong{[Deprecated]}} + +This function is to be \emph{deprecated}. Please use \code{admiraldev::assert_unit()} instead +once https://github.com/pharmaverse/admiraldev/issues/468 is closed. +} +\examples{ +# See examples of `admiraldev::assert_unit` + +} +\seealso{ +Checks for valid input and returns warning or errors messages: +\code{\link[admiraldev]{assert_atomic_vector}()}, +\code{\link[admiraldev]{assert_character_scalar}()}, +\code{\link[admiraldev]{assert_character_vector}()}, +\code{\link[admiraldev]{assert_data_frame}()}, +\code{\link[admiraldev]{assert_date_vector}()}, +\code{\link[admiraldev]{assert_expr}()}, +\code{\link[admiraldev]{assert_expr_list}()}, +\code{\link[admiraldev]{assert_filter_cond}()}, +\code{\link[admiraldev]{assert_function}()}, +\code{\link[admiraldev]{assert_integer_scalar}()}, +\code{\link[admiraldev]{assert_list_element}()}, +\code{\link[admiraldev]{assert_list_of}()}, +\code{\link[admiraldev]{assert_logical_scalar}()}, +\code{\link[admiraldev]{assert_named}()}, +\code{\link[admiraldev]{assert_numeric_vector}()}, +\code{\link[admiraldev]{assert_one_to_one}()}, +\code{\link[admiraldev]{assert_param_does_not_exist}()}, +\code{\link[admiraldev]{assert_s3_class}()}, +\code{\link[admiraldev]{assert_same_type}()}, +\code{\link[admiraldev]{assert_symbol}()}, +\code{\link[admiraldev]{assert_vars}()}, +\code{\link[admiraldev]{assert_varval_list}()} +} +\concept{deprecated} +\keyword{deprecated} diff --git a/man/derive_param_waisthgt.Rd b/man/derive_param_waisthgt.Rd index 00629d2..978f59e 100644 --- a/man/derive_param_waisthgt.Rd +++ b/man/derive_param_waisthgt.Rd @@ -12,7 +12,7 @@ derive_param_waisthgt( set_values_to = exprs(PARAMCD = "WAISTHGT"), filter = NULL, constant_by_vars = NULL, - get_unit_expr = NULL + get_unit_expr ) } \arguments{ @@ -133,7 +133,8 @@ derive_param_waisthgt( PARAMCD = "WAISTHGT", PARAM = "Waist to Height Ratio" ), - constant_by_vars = exprs(USUBJID) + constant_by_vars = exprs(USUBJID), + get_unit_expr = admiral::extract_unit(PARAM) ) # Example 2: Same as above but only adding Waist to Height Ratio at certain visits @@ -148,6 +149,7 @@ derive_param_waisthgt( PARAM = "Waist to Height Ratio" ), constant_by_vars = exprs(USUBJID), + get_unit_expr = admiral::extract_unit(PARAM), filter = VISIT \%in\% c("SCREENING", "WEEK 3") ) @@ -177,7 +179,8 @@ derive_param_waisthgt( set_values_to = exprs( PARAMCD = "WAISTHGT", PARAM = "Waist to Height Ratio" - ) + ), + get_unit_expr = admiral::extract_unit(PARAM) ) # Example 4: Automatic conversion is performed when deriving the ratio @@ -205,7 +208,7 @@ derive_param_waisthgt( PARAM = "Waist to Height Ratio" ), constant_by_vars = exprs(USUBJID), - get_unit_expr = AVALU + get_unit_expr = admiral::extract_unit(PARAM) ) } \seealso{ diff --git a/man/derive_param_waisthip.Rd b/man/derive_param_waisthip.Rd index 5cbe453..808de68 100644 --- a/man/derive_param_waisthip.Rd +++ b/man/derive_param_waisthip.Rd @@ -11,7 +11,7 @@ derive_param_waisthip( hipcir_code = "HIPCIR", set_values_to = exprs(PARAMCD = "WAISTHIP"), filter = NULL, - get_unit_expr = NULL + get_unit_expr ) } \arguments{ @@ -119,7 +119,8 @@ derive_param_waisthip( set_values_to = exprs( PARAMCD = "WAISTHIP", PARAM = "Waist to Hip Ratio" - ) + ), + get_unit_expr = admiral::extract_unit(PARAM) ) # Only adding Waist to Hip Ratio at certain visits @@ -133,6 +134,7 @@ derive_param_waisthip( PARAMCD = "WAISTHIP", PARAM = "Waist to Hip Ratio" ), + get_unit_expr = admiral::extract_unit(PARAM), filter = VISIT \%in\% c("SCREENING", "WEEK 3") ) diff --git a/tests/testthat/test-derive_param_ratio.R b/tests/testthat/test-derive_param_ratio.R index 55da3f5..2402ff3 100644 --- a/tests/testthat/test-derive_param_ratio.R +++ b/tests/testthat/test-derive_param_ratio.R @@ -24,7 +24,7 @@ test_that( denominator_code = "HIPCIR", set_values_to = exprs( PARAMCD = "WAISTHIP", - PARAM = "Waist-to-Hip Ratio" + PARAM = "Waist to Hip Ratio" ) ) @@ -35,7 +35,7 @@ test_that( set_values_to = exprs( AVAL = AVAL.WSTCIR / AVAL.HIPCIR, PARAMCD = "WAISTHIP", - PARAM = "Waist-to-Hip Ratio" + PARAM = "Waist to Hip Ratio" ) ) @@ -70,7 +70,7 @@ test_that( denominator_code = "HEIGHT", set_values_to = exprs( PARAMCD = "WAISTHGT", - PARAM = "Waist-to-Height Ratio" + PARAM = "Waist to Height Ratio" ), constant_denominator = TRUE, constant_by_vars = exprs(USUBJID) @@ -83,7 +83,7 @@ test_that( set_values_to = exprs( AVAL = AVAL.WSTCIR / AVAL.HEIGHT, PARAMCD = "WAISTHGT", - PARAM = "Waist-to-Height Ratio" + PARAM = "Waist to Height Ratio" ), constant_parameters = "HEIGHT", constant_by_vars = exprs(USUBJID) diff --git a/tests/testthat/test-derive_param_waisthgt.R b/tests/testthat/test-derive_param_waisthgt.R index bd6c886..6a20be6 100644 --- a/tests/testthat/test-derive_param_waisthgt.R +++ b/tests/testthat/test-derive_param_waisthgt.R @@ -21,7 +21,8 @@ test_that( PARAMCD = "WAISTHGT", PARAM = "Waist to Height Ratio" ), - constant_by_vars = exprs(USUBJID) + constant_by_vars = exprs(USUBJID), + get_unit_expr = admiral::extract_unit(PARAM) ) expected_output <- derive_param_computed( @@ -71,7 +72,8 @@ test_that( set_values_to = exprs( PARAMCD = "WAISTHGT", PARAM = "Waist to Height Ratio" - ) + ), + get_unit_expr = admiral::extract_unit(PARAM) ) expected_output <- derive_param_computed( @@ -116,7 +118,7 @@ test_that( PARAM = "Waist to Height Ratio" ), constant_by_vars = exprs(USUBJID), - get_unit_expr = AVALU + get_unit_expr = admiral::extract_unit(PARAM) ) %>% filter(PARAMCD == "WAISTHGT") @@ -139,7 +141,8 @@ test_that( PARAMCD = "WAISTHGT", PARAM = "Waist to Height Ratio" ), - constant_by_vars = exprs(USUBJID) + constant_by_vars = exprs(USUBJID), + get_unit_expr = admiral::extract_unit(PARAM) ) %>% filter(PARAMCD == "WAISTHGT") diff --git a/tests/testthat/test-derive_param_waisthip.R b/tests/testthat/test-derive_param_waisthip.R index b4c8017..a4783ad 100644 --- a/tests/testthat/test-derive_param_waisthip.R +++ b/tests/testthat/test-derive_param_waisthip.R @@ -23,7 +23,8 @@ test_that( set_values_to = exprs( PARAMCD = "WAISTHIP", PARAM = "Waist to Hip Ratio" - ) + ), + get_unit_expr = admiral::extract_unit(PARAM) ) expected_output <- derive_param_computed( @@ -71,7 +72,7 @@ test_that( PARAMCD = "WAISTHIP", PARAM = "Waist to Hip Ratio" ), - get_unit_expr = AVALU + get_unit_expr = admiral::extract_unit(PARAM) ) %>% filter(PARAMCD == "WAISTHIP") @@ -97,7 +98,8 @@ test_that( set_values_to = exprs( PARAMCD = "WAISTHIP", PARAM = "Waist to Hip Ratio" - ) + ), + get_unit_expr = admiral::extract_unit(PARAM) ) %>% filter(PARAMCD == "WAISTHIP") From 1f05f0f67627d1abe8a663d762e275574dd8720f Mon Sep 17 00:00:00 2001 From: Andrii Yurovskyi Date: Tue, 29 Oct 2024 09:37:30 +0100 Subject: [PATCH 21/28] Update WORDLIST --- inst/WORDLIST | 2 ++ 1 file changed, 2 insertions(+) diff --git a/inst/WORDLIST b/inst/WORDLIST index 0719445..4766ddf 100644 --- a/inst/WORDLIST +++ b/inst/WORDLIST @@ -39,3 +39,5 @@ advs PARAMCD prm NCI +admiraldev +github From d745aca4727c5ba4141bd42987bbe8469972b7b3 Mon Sep 17 00:00:00 2001 From: Andrii Yurovskyi Date: Tue, 29 Oct 2024 09:41:50 +0100 Subject: [PATCH 22/28] Refined code/documentation and added more tests --- R/assertions.R | 7 +- R/derive_advs_params.R | 116 ++++++++++------------ man/assert_unit.Rd | 27 +---- man/derive_param_ratio.Rd | 40 ++++---- man/derive_param_waisthgt.Rd | 25 +++-- man/derive_param_waisthip.Rd | 13 ++- man/unit-conversion.Rd | 2 +- tests/testthat/test-derive_param_ratio.R | 121 ++++++++++++++++++++++- 8 files changed, 218 insertions(+), 133 deletions(-) diff --git a/R/assertions.R b/R/assertions.R index 62aa7e9..024c635 100644 --- a/R/assertions.R +++ b/R/assertions.R @@ -8,11 +8,13 @@ #' #' @inherit admiraldev::assert_unit #' +#' @seealso [admiraldev::assert_unit] +#' #' @examples #' # See examples of `admiraldev::assert_unit` #' -#' @family deprecated -#' @keywords deprecated +#' @family internal deprecated +#' @keywords internal deprecated assert_unit <- function(dataset, param, required_unit, @@ -24,7 +26,6 @@ assert_unit <- function(dataset, assert_data_frame(dataset, required_vars = exprs(PARAMCD)) assert_character_scalar(param) assert_character_vector(required_unit) - get_unit_expr <- enexpr(get_unit_expr) units <- dataset %>% diff --git a/R/derive_advs_params.R b/R/derive_advs_params.R index 9ba8678..19d32ed 100644 --- a/R/derive_advs_params.R +++ b/R/derive_advs_params.R @@ -3,28 +3,27 @@ #' @description Adds a record for Waist to Hip Ratio using Waist Circumference and Hip Circumference #' for each by group (e.g., subject and visit) where the source parameters are available. #' -#' **Note:** This is a wrapper function for the more generic -#' \code{admiral::derive_param_computed()}. +#' **Note:** This is a wrapper function for the more generic [`admiral::derive_param_computed()`]. #' #' @param dataset Input dataset #' -#' The variables specified by the \code{by_vars} argument are expected to be in the dataset. -#' \code{PARAMCD}, and \code{AVAL} are expected as well. +#' The variables specified by the `by_vars` argument are expected to be in the dataset. +#' `PARAMCD`, and `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} argument) -#' and to the parameters specified by \code{wstcir_code} and \code{hipcir_code}. +#' 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` argument) and to the parameters +#' specified by `wstcir_code` and `hipcir_code`. #' #' @param wstcir_code Waist Circumference parameter code #' -#' The observations where \code{PARAMCD} equals the specified value are considered +#' The observations where `PARAMCD` equals the specified value are considered #' as the Waist Circumference. #' #' *Permitted Values:* character value #' #' @param hipcir_code Hip Circumference parameter code #' -#' The observations where \code{PARAMCD} equals the specified value are considered +#' The observations where `PARAMCD` equals the specified value are considered #' as the Hip Circumference #' #' *Permitted Values:* character value @@ -35,16 +34,15 @@ #' The analysis value of the new parameter is derived as #' \deqn{WAISTHIP = \frac{WSTCIR}{HIPCIR}}{WAISTHIP = WSTCIR / HIPCIR} #' -#' #' @return The input dataset with the new parameter added. Note, a variable will only -#' be populated in the new parameter rows if it is specified in \code{by_vars}. +#' be populated in the new parameter rows if it is specified in `by_vars`. #' #' @family der_prm_advs #' @keywords der_prm_advs #' #' @export #' -#' @seealso \code{\link[admiral:derive_param_computed]{admiral::derive_param_computed()}} +#' @seealso [admiral::derive_param_computed()] #' #' @examples #' library(tibble) @@ -171,29 +169,27 @@ derive_param_waisthip <- function(dataset, #' @description Adds a record for Waist to Height Ratio using Waist Circumference and Height #' for each by group (e.g., subject and visit) where the source parameters are available. #' -#' **Note:** This is a wrapper function for the more generic -#' \code{admiral::derive_param_computed()}. +#' **Note:** This is a wrapper function for the more generic [`admiral::derive_param_computed()`]. #' #' @param dataset Input dataset #' -#' The variables specified by the \code{by_vars} argument are expected to be in the dataset. -#' \code{PARAMCD}, and \code{AVAL} are expected as well. +#' The variables specified by the `by_vars` argument are expected to be in the dataset. +#' `PARAMCD`, and `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} argument) -#' and to the parameters specified by \code{wstcir_code} and \code{height_code}. +#' 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` argument) and to the parameters +#' specified by `wstcir_code` and `height_code`. #' #' @param wstcir_code Waist Circumference parameter code #' -#' The observations where \code{PARAMCD} equals the specified value are considered +#' The observations where `PARAMCD` equals the specified value are considered #' as the Waist Circumference. #' #' *Permitted Values:* character value #' #' @param height_code Height parameter code #' -#' The observations where \code{PARAMCD} equals the specified value are considered -#' as the Height. +#' The observations where `PARAMCD` equals the specified value are considered as the Height. #' #' *Permitted Values:* character value #' @@ -203,13 +199,12 @@ derive_param_waisthip <- function(dataset, #' to the other parameters using the specified variables. #' #' If Height is constant (e.g. only measured once at screening or baseline) then use -#' \code{constant_by_vars} to select the subject-level variable to merge on (e.g. \code{USUBJID}). +#' `constant_by_vars` to select the subject-level variable to merge on (e.g. `USUBJID`). #' This will produce Waist to Height Ratio at all visits where Waist Circumference is measured. #' Otherwise it will only be calculated at visits with both Height and Waist Circumference #' collected. #' -#' *Permitted Values*: list of variables created by \code{exprs()} -#' e.g. \code{exprs(USUBJID, VISIT)} +#' *Permitted Values*: list of variables created by `exprs()`, e.g. `exprs(USUBJID, VISIT)` #' #' @inheritParams derive_param_ratio #' @@ -217,16 +212,15 @@ derive_param_waisthip <- function(dataset, #' The analysis value of the new parameter is derived as #' \deqn{WAISTHGT = \frac{WSTCIR}{HEIGHT}}{WAISTHGT = WSTCIR / HEIGHT} #' -#' #' @return The input dataset with the new parameter added. Note, a variable will only -#' be populated in the new parameter rows if it is specified in \code{by_vars}. +#' be populated in the new parameter rows if it is specified in `by_vars`. #' #' @family der_prm_advs #' @keywords der_prm_advs #' #' @export #' -#' @seealso \code{\link[admiral:derive_param_computed]{admiral::derive_param_computed()}} +#' @seealso [admiral::derive_param_computed()] #' #' @examples #' library(tibble) @@ -259,7 +253,8 @@ derive_param_waisthip <- function(dataset, #' get_unit_expr = admiral::extract_unit(PARAM) #' ) #' -#' # Example 2: Same as above but only adding Waist to Height Ratio at certain visits +#' # Example 2: Same as above but only adding Waist to Height Ratio +#' # at certain visits #' #' derive_param_waisthgt( #' advs, @@ -275,7 +270,8 @@ derive_param_waisthip <- function(dataset, #' filter = VISIT %in% c("SCREENING", "WEEK 3") #' ) #' -#' # Example 3: Pediatric study where Height and Waist Circumference are measured multiple times +#' # Example 3: Pediatric study where Height and Waist Circumference +#' # are measured multiple times #' #' advs <- tribble( #' ~USUBJID, ~PARAMCD, ~PARAM, ~AVAL, ~AVALU, ~VISIT, @@ -386,57 +382,54 @@ derive_param_waisthgt <- function(dataset, #' (numerator and denominator) each by group (e.g., subject and visit) where the source parameters #' are available. #' -#' **Note:** This is a wrapper function for the more generic -#' \code{admiral::derive_param_computed()}. +#' **Note:** This is a wrapper function for the more generic [`admiral::derive_param_computed()`]. #' #' @param dataset Input dataset #' -#' The variables specified by the \code{by_vars} argument are expected to be in the dataset. -#' \code{PARAMCD}, and \code{AVAL} are expected as well. +#' The variables specified by the `by_vars` argument are expected to be in the dataset. +#' `PARAMCD`, and `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} argument) -#' and to the parameters specified by \code{numerator_code} and \code{denominator_code}. +#' 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` argument) and to the parameters +#' specified by `numerator_code` and `denominator_code`. #' #' @param numerator_code Numerator parameter code #' -#' The observations where \code{PARAMCD} equals the specified value are considered -#' as the numerator +#' The observations where `PARAMCD` equals the specified value are considered as the numerator. #' #' *Permitted Values:* character value #' #' @param denominator_code Denominator parameter code #' -#' The observations where \code{PARAMCD} equals the specified value are considered -#' as the denominator +#' The observations where `PARAMCD` equals the specified value are considered as the denominator. #' #' *Permitted Values:* character value #' #' @param set_values_to Variables to be set #' -#' The specified variables are set to the specified values for the new -#' observations. For example `exprs(PARAMCD = "RATIO")` defines the parameter code -#' for the new parameter. +#' The specified variables are set to the specified values for the new +#' observations. For example `exprs(PARAMCD = "RATIO")` defines the parameter code +#' for the new parameter. #' -#' *Permitted Values*: List of variable-value pairs +#' *Permitted Values:* List of variable-value pairs #' #' @param constant_numerator Is numerator parameter constant? #' -#' It is expected that the parameter code (PARAMCD) specified in \code{numerator_code} +#' It is expected that the parameter code (PARAMCD) specified in `numerator_code` #' which is required to derive the new parameter is measured only once. For example, -#' if Height to Weight Ratio should be derived and height is measured only once -#' while Weight is measured at each visit. Height could be specified in the -#' \code{numerator_code} argument and \code{constant_numerator} is to be set to \code{TRUE}. +#' if Height to Weight Ratio should be derived and height is measured only once while +#' Weight is measured at each visit. Height could be specified in the `numerator_code` +#' argument and `constant_numerator` is to be set to `TRUE`. #' #' *Permitted Values:* logical scalar #' #' @param constant_denominator Is denominator parameter constant? #' -#' It is expected that the parameter code (PARAMCD) specified in \code{numerator_code} +#' It is expected that the parameter code (PARAMCD) specified in `numerator_code` #' which is required to derive the new parameter is measured only once. For example, #' if Waist to Height Ratio should be derived and height is measured only once -#' while Waist Circumference is measured at each visit. Height could be specified in the -#' \code{denominator_code} argument and \code{constant_denominator} is to be set to \code{TRUE}. +#' while Waist Circumference is measured at each visit. Height could be specified in +#' the `denominator_code` argument and `constant_denominator` is to be set to `TRUE`. #' #' *Permitted Values:* logical scalar #' @@ -446,13 +439,12 @@ derive_param_waisthgt <- function(dataset, #' to the other parameters using the specified variables. #' #' If numerator and/or denominator is constant (e.g. only measured once at screening or baseline) -#' then use \code{constant_by_vars} to select the subject-level variable to merge on (e.g. -#' \code{USUBJID}). This will produce a generic Ratio parameter at all visits where numerator -#' and/or denominator is measured. Otherwise it will only be calculated at visits with both -#' numerator and denominator parameters collected. +#' then use `constant_by_vars` to select the subject-level variable to merge on (e.g. `USUBJID`). +#' This will produce a generic Ratio parameter at all visits where numerator and/or denominator +#' is measured. Otherwise it will only be calculated at visits with both numerator and denominator +#' parameters collected. #' -#' *Permitted Values*: list of variables created by \code{exprs()} -#' e.g. \code{exprs(USUBJID, VISIT)} +#' *Permitted Values*: list of variables created by `exprs()`, e.g. `exprs(USUBJID, VISIT)` #' #' @param get_unit_expr An expression providing the unit of the parameter #' @@ -463,7 +455,7 @@ derive_param_waisthgt <- function(dataset, #' convertible (e.g., centimeters for one parameter and inches for another), an automatic #' conversion will be performed in order to uniform the values before calculating the ratio. #' -#' **Note:** Conversion factors come from unit definitions as per the NCI Thesaurus +#' **Note:** Conversion factors come from unit definitions as per the NCI Thesaurus. #' #' *Permitted Values:* A variable of the input dataset or a function call #' @@ -475,7 +467,7 @@ derive_param_waisthgt <- function(dataset, #' #' #' @return The input dataset with the new parameter added. Note, a variable will only -#' be populated in the new parameter rows if it is specified in \code{by_vars}. +#' be populated in the new parameter rows if it is specified in `by_vars`. #' #' @family internal #' @keywords internal @@ -541,7 +533,7 @@ derive_param_ratio <- function(dataset, ) cli_alert_info( - "Unit conversion performed for {.val {denominator_code}}. Values converted from + "ALERT: Unit conversion performed for {.val {denominator_code}}. Values converted from {.val {param_units[[denominator_code]]}} to {.val {param_units[[numerator_code]]}}.", wrap = TRUE ) @@ -617,7 +609,7 @@ get_conv_factor <- function(from_unit, to_unit) { #' @description `get_conv_factors_all()` returns all conversion factors supported. #' -#' **Note:** Conversion factors come from unit definitions as per the NCI Thesaurus +#' **Note:** Conversion factors come from unit definitions as per the NCI Thesaurus. #' #' @rdname unit-conversion #' @keywords internal diff --git a/man/assert_unit.Rd b/man/assert_unit.Rd index 78a326c..a8d7981 100644 --- a/man/assert_unit.Rd +++ b/man/assert_unit.Rd @@ -62,29 +62,8 @@ once https://github.com/pharmaverse/admiraldev/issues/468 is closed. } \seealso{ -Checks for valid input and returns warning or errors messages: -\code{\link[admiraldev]{assert_atomic_vector}()}, -\code{\link[admiraldev]{assert_character_scalar}()}, -\code{\link[admiraldev]{assert_character_vector}()}, -\code{\link[admiraldev]{assert_data_frame}()}, -\code{\link[admiraldev]{assert_date_vector}()}, -\code{\link[admiraldev]{assert_expr}()}, -\code{\link[admiraldev]{assert_expr_list}()}, -\code{\link[admiraldev]{assert_filter_cond}()}, -\code{\link[admiraldev]{assert_function}()}, -\code{\link[admiraldev]{assert_integer_scalar}()}, -\code{\link[admiraldev]{assert_list_element}()}, -\code{\link[admiraldev]{assert_list_of}()}, -\code{\link[admiraldev]{assert_logical_scalar}()}, -\code{\link[admiraldev]{assert_named}()}, -\code{\link[admiraldev]{assert_numeric_vector}()}, -\code{\link[admiraldev]{assert_one_to_one}()}, -\code{\link[admiraldev]{assert_param_does_not_exist}()}, -\code{\link[admiraldev]{assert_s3_class}()}, -\code{\link[admiraldev]{assert_same_type}()}, -\code{\link[admiraldev]{assert_symbol}()}, -\code{\link[admiraldev]{assert_vars}()}, -\code{\link[admiraldev]{assert_varval_list}()} +\link[admiraldev:assert_unit]{admiraldev::assert_unit} } -\concept{deprecated} +\concept{internal deprecated} \keyword{deprecated} +\keyword{internal} diff --git a/man/derive_param_ratio.Rd b/man/derive_param_ratio.Rd index 0cc66f6..e463c43 100644 --- a/man/derive_param_ratio.Rd +++ b/man/derive_param_ratio.Rd @@ -23,9 +23,9 @@ derive_param_ratio( The variables specified by the \code{by_vars} argument are expected to be in the dataset. \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} argument) -and to the parameters specified by \code{numerator_code} and \code{denominator_code}.} +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} argument) and to the parameters +specified by \code{numerator_code} and \code{denominator_code}.} \item{by_vars}{Grouping variables @@ -38,15 +38,13 @@ e.g. \code{exprs(USUBJID, VISIT)}} \item{numerator_code}{Numerator parameter code -The observations where \code{PARAMCD} equals the specified value are considered -as the numerator +The observations where \code{PARAMCD} equals the specified value are considered as the numerator. \emph{Permitted Values:} character value} \item{denominator_code}{Denominator parameter code -The observations where \code{PARAMCD} equals the specified value are considered -as the denominator +The observations where \code{PARAMCD} equals the specified value are considered as the denominator. \emph{Permitted Values:} character value} @@ -56,15 +54,15 @@ The specified variables are set to the specified values for the new observations. For example \code{exprs(PARAMCD = "RATIO")} defines the parameter code for the new parameter. -\emph{Permitted Values}: List of variable-value pairs} +\emph{Permitted Values:} List of variable-value pairs} \item{constant_numerator}{Is numerator parameter constant? It is expected that the parameter code (PARAMCD) specified in \code{numerator_code} which is required to derive the new parameter is measured only once. For example, -if Height to Weight Ratio should be derived and height is measured only once -while Weight is measured at each visit. Height could be specified in the -\code{numerator_code} argument and \code{constant_numerator} is to be set to \code{TRUE}. +if Height to Weight Ratio should be derived and height is measured only once while +Weight is measured at each visit. Height could be specified in the \code{numerator_code} +argument and \code{constant_numerator} is to be set to \code{TRUE}. \emph{Permitted Values:} logical scalar} @@ -73,8 +71,8 @@ while Weight is measured at each visit. Height could be specified in the It is expected that the parameter code (PARAMCD) specified in \code{numerator_code} which is required to derive the new parameter is measured only once. For example, if Waist to Height Ratio should be derived and height is measured only once -while Waist Circumference is measured at each visit. Height could be specified in the -\code{denominator_code} argument and \code{constant_denominator} is to be set to \code{TRUE}. +while Waist Circumference is measured at each visit. Height could be specified in +the \code{denominator_code} argument and \code{constant_denominator} is to be set to \code{TRUE}. \emph{Permitted Values:} logical scalar} @@ -92,13 +90,12 @@ When numerator and/or denominator is constant, the parameters (measured only onc to the other parameters using the specified variables. If numerator and/or denominator is constant (e.g. only measured once at screening or baseline) -then use \code{constant_by_vars} to select the subject-level variable to merge on (e.g. -\code{USUBJID}). This will produce a generic Ratio parameter at all visits where numerator -and/or denominator is measured. Otherwise it will only be calculated at visits with both -numerator and denominator parameters collected. +then use \code{constant_by_vars} to select the subject-level variable to merge on (e.g. \code{USUBJID}). +This will produce a generic Ratio parameter at all visits where numerator and/or denominator +is measured. Otherwise it will only be calculated at visits with both numerator and denominator +parameters collected. -\emph{Permitted Values}: list of variables created by \code{exprs()} -e.g. \code{exprs(USUBJID, VISIT)}} +\emph{Permitted Values}: list of variables created by \code{exprs()}, e.g. \code{exprs(USUBJID, VISIT)}} \item{get_unit_expr}{An expression providing the unit of the parameter @@ -109,7 +106,7 @@ Additionally, if the input parameters are measured in different units but are mu convertible (e.g., centimeters for one parameter and inches for another), an automatic conversion will be performed in order to uniform the values before calculating the ratio. -\strong{Note:} Conversion factors come from unit definitions as per the NCI Thesaurus +\strong{Note:} Conversion factors come from unit definitions as per the NCI Thesaurus. \emph{Permitted Values:} A variable of the input dataset or a function call} } @@ -122,8 +119,7 @@ Adds a record for a generic Ratio parameter using two existing parameter (numerator and denominator) each by group (e.g., subject and visit) where the source parameters are available. -\strong{Note:} This is a wrapper function for the more generic -\code{admiral::derive_param_computed()}. +\strong{Note:} This is a wrapper function for the more generic \code{\link[admiral:derive_param_computed]{admiral::derive_param_computed()}}. } \details{ The analysis value of the new parameter is derived as diff --git a/man/derive_param_waisthgt.Rd b/man/derive_param_waisthgt.Rd index 978f59e..5ce7efd 100644 --- a/man/derive_param_waisthgt.Rd +++ b/man/derive_param_waisthgt.Rd @@ -21,9 +21,9 @@ derive_param_waisthgt( The variables specified by the \code{by_vars} argument are expected to be in the dataset. \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} argument) -and to the parameters specified by \code{wstcir_code} and \code{height_code}.} +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} argument) and to the parameters +specified by \code{wstcir_code} and \code{height_code}.} \item{by_vars}{Grouping variables @@ -43,8 +43,7 @@ as the Waist Circumference. \item{height_code}{Height parameter code -The observations where \code{PARAMCD} equals the specified value are considered -as the Height. +The observations where \code{PARAMCD} equals the specified value are considered as the Height. \emph{Permitted Values:} character value} @@ -54,7 +53,7 @@ The specified variables are set to the specified values for the new observations. For example \code{exprs(PARAMCD = "RATIO")} defines the parameter code for the new parameter. -\emph{Permitted Values}: List of variable-value pairs} +\emph{Permitted Values:} List of variable-value pairs} \item{filter}{Filter condition @@ -75,8 +74,7 @@ This will produce Waist to Height Ratio at all visits where Waist Circumference Otherwise it will only be calculated at visits with both Height and Waist Circumference collected. -\emph{Permitted Values}: list of variables created by \code{exprs()} -e.g. \code{exprs(USUBJID, VISIT)}} +\emph{Permitted Values}: list of variables created by \code{exprs()}, e.g. \code{exprs(USUBJID, VISIT)}} \item{get_unit_expr}{An expression providing the unit of the parameter @@ -87,7 +85,7 @@ Additionally, if the input parameters are measured in different units but are mu convertible (e.g., centimeters for one parameter and inches for another), an automatic conversion will be performed in order to uniform the values before calculating the ratio. -\strong{Note:} Conversion factors come from unit definitions as per the NCI Thesaurus +\strong{Note:} Conversion factors come from unit definitions as per the NCI Thesaurus. \emph{Permitted Values:} A variable of the input dataset or a function call} } @@ -99,8 +97,7 @@ be populated in the new parameter rows if it is specified in \code{by_vars}. Adds a record for Waist to Height Ratio using Waist Circumference and Height for each by group (e.g., subject and visit) where the source parameters are available. -\strong{Note:} This is a wrapper function for the more generic -\code{admiral::derive_param_computed()}. +\strong{Note:} This is a wrapper function for the more generic \code{\link[admiral:derive_param_computed]{admiral::derive_param_computed()}}. } \details{ The analysis value of the new parameter is derived as @@ -137,7 +134,8 @@ derive_param_waisthgt( get_unit_expr = admiral::extract_unit(PARAM) ) -# Example 2: Same as above but only adding Waist to Height Ratio at certain visits +# Example 2: Same as above but only adding Waist to Height Ratio +# at certain visits derive_param_waisthgt( advs, @@ -153,7 +151,8 @@ derive_param_waisthgt( filter = VISIT \%in\% c("SCREENING", "WEEK 3") ) -# Example 3: Pediatric study where Height and Waist Circumference are measured multiple times +# Example 3: Pediatric study where Height and Waist Circumference +# are measured multiple times advs <- tribble( ~USUBJID, ~PARAMCD, ~PARAM, ~AVAL, ~AVALU, ~VISIT, diff --git a/man/derive_param_waisthip.Rd b/man/derive_param_waisthip.Rd index 808de68..d29cbed 100644 --- a/man/derive_param_waisthip.Rd +++ b/man/derive_param_waisthip.Rd @@ -20,9 +20,9 @@ derive_param_waisthip( The variables specified by the \code{by_vars} argument are expected to be in the dataset. \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} argument) -and to the parameters specified by \code{wstcir_code} and \code{hipcir_code}.} +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} argument) and to the parameters +specified by \code{wstcir_code} and \code{hipcir_code}.} \item{by_vars}{Grouping variables @@ -53,7 +53,7 @@ The specified variables are set to the specified values for the new observations. For example \code{exprs(PARAMCD = "RATIO")} defines the parameter code for the new parameter. -\emph{Permitted Values}: List of variable-value pairs} +\emph{Permitted Values:} List of variable-value pairs} \item{filter}{Filter condition @@ -72,7 +72,7 @@ Additionally, if the input parameters are measured in different units but are mu convertible (e.g., centimeters for one parameter and inches for another), an automatic conversion will be performed in order to uniform the values before calculating the ratio. -\strong{Note:} Conversion factors come from unit definitions as per the NCI Thesaurus +\strong{Note:} Conversion factors come from unit definitions as per the NCI Thesaurus. \emph{Permitted Values:} A variable of the input dataset or a function call} } @@ -84,8 +84,7 @@ be populated in the new parameter rows if it is specified in \code{by_vars}. Adds a record for Waist to Hip Ratio using Waist Circumference and Hip Circumference for each by group (e.g., subject and visit) where the source parameters are available. -\strong{Note:} This is a wrapper function for the more generic -\code{admiral::derive_param_computed()}. +\strong{Note:} This is a wrapper function for the more generic \code{\link[admiral:derive_param_computed]{admiral::derive_param_computed()}}. } \details{ The analysis value of the new parameter is derived as diff --git a/man/unit-conversion.Rd b/man/unit-conversion.Rd index 7dda8d0..3644723 100644 --- a/man/unit-conversion.Rd +++ b/man/unit-conversion.Rd @@ -16,6 +16,6 @@ Returns \code{NA} if units are not supported/convertible. \code{get_conv_factors_all()} returns all conversion factors supported. -\strong{Note:} Conversion factors come from unit definitions as per the NCI Thesaurus +\strong{Note:} Conversion factors come from unit definitions as per the NCI Thesaurus. } \keyword{internal} diff --git a/tests/testthat/test-derive_param_ratio.R b/tests/testthat/test-derive_param_ratio.R index 2402ff3..9661059 100644 --- a/tests/testthat/test-derive_param_ratio.R +++ b/tests/testthat/test-derive_param_ratio.R @@ -49,7 +49,7 @@ test_that( test_that( "derive_param_computed Test 2: Cross-check with derive_param_computed(), - new observations with constant parameters", + new observations with constant denominator", { input <- tribble( ~USUBJID, ~PARAMCD, ~PARAM, ~AVAL, ~AVALU, ~VISIT, @@ -96,3 +96,122 @@ test_that( ) } ) + +test_that( + "derive_param_computed Test 3: Cross-check with derive_param_computed(), + new observations with constant numerator", + { + input <- tribble( + ~USUBJID, ~PARAMCD, ~PARAM, ~AVAL, ~AVALU, ~VISIT, + "01-101-1001", "HEIGHT", "Height (cm)", 147, "cm", "SCREENING", + "01-101-1001", "WEIGHT", "Weight (kg)", 95, "kg", "SCREENING", + "01-101-1001", "WEIGHT", "Weight (kg)", 94.5, "kg", "WEEK 2", + "01-101-1001", "WEIGHT", "Weight (kg)", 94, "kg", "WEEK 3", + "01-101-1002", "HEIGHT", "Height (cm)", 163, "cm", "SCREENING", + "01-101-1002", "WEIGHT", "Weight (kg)", 105, "kg", "SCREENING", + "01-101-1002", "WEIGHT", "Weight (kg)", 104.5, "kg", "WEEK 2", + "01-101-1002", "WEIGHT", "Weight (kg)", 104, "kg", "WEEK 3" + ) + + wrapper_output <- derive_param_ratio( + input, + by_vars = exprs(USUBJID, VISIT), + numerator_code = "HEIGHT", + denominator_code = "WEIGHT", + set_values_to = exprs( + PARAMCD = "HGTWGT", + PARAM = "Height to Weight Ratio" + ), + constant_numerator = TRUE, + constant_by_vars = exprs(USUBJID) + ) + + expected_output <- derive_param_computed( + input, + parameters = "WEIGHT", + by_vars = exprs(USUBJID, VISIT), + set_values_to = exprs( + AVAL = AVAL.HEIGHT / AVAL.WEIGHT, + PARAMCD = "HGTWGT", + PARAM = "Height to Weight Ratio" + ), + constant_parameters = "HEIGHT", + constant_by_vars = exprs(USUBJID) + ) + + expect_dfs_equal( + wrapper_output, + expected_output, + keys = c("USUBJID", "PARAMCD", "VISIT") + ) + } +) + +test_that( + "derive_param_ratio Test 4: Cross-check with and without units conversion", + { + input_diff_units <- tribble( + ~USUBJID, ~PARAMCD, ~PARAM, ~AVAL, ~AVALU, ~VISIT, + "01-101-1001", "HIPCIR", "Hip Circumference (in)", round(125 / 2.54, 2), "in", "SCREENING", + "01-101-1001", "HIPCIR", "Hip Circumference (in)", round(124 / 2.54, 2), "in", "WEEK 2", + "01-101-1001", "HIPCIR", "Hip Circumference (in)", round(123 / 2.54, 2), "in", "WEEK 3", + "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 110, "cm", "SCREENING", + "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 108, "cm", "WEEK 2", + "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 107, "cm", "WEEK 3", + "01-101-1002", "HIPCIR", "Hip Circumference (in)", round(135 / 2.54, 2), "in", "SCREENING", + "01-101-1002", "HIPCIR", "Hip Circumference (in)", round(133 / 2.54, 2), "in", "WEEK 2", + "01-101-1002", "HIPCIR", "Hip Circumference (in)", round(132 / 2.54, 2), "in", "WEEK 3", + "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 120, "cm", "SCREENING", + "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 118, "cm", "WEEK 2", + "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 117, "cm", "WEEK 3" + ) + + output_units_unified <- derive_param_ratio( + input_diff_units, + by_vars = exprs(USUBJID, VISIT), + numerator_code = "WSTCIR", + denominator_code = "HIPCIR", + set_values_to = exprs( + PARAMCD = "WAISTHIP", + PARAM = "Waist to Hip Ratio" + ), + get_unit_expr = admiral::extract_unit(PARAM) + ) %>% + filter(PARAMCD == "WAISTHIP") + + input_same_units <- tribble( + ~USUBJID, ~PARAMCD, ~PARAM, ~AVAL, ~AVALU, ~VISIT, + "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 125, "cm", "SCREENING", + "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 124, "cm", "WEEK 2", + "01-101-1001", "HIPCIR", "Hip Circumference (cm)", 123, "cm", "WEEK 3", + "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 110, "cm", "SCREENING", + "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 108, "cm", "WEEK 2", + "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 107, "cm", "WEEK 3", + "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 135, "cm", "SCREENING", + "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 133, "cm", "WEEK 2", + "01-101-1002", "HIPCIR", "Hip Circumference (cm)", 132, "cm", "WEEK 3", + "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 120, "cm", "SCREENING", + "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 118, "cm", "WEEK 2", + "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 117, "cm", "WEEK 3" + ) + + expected_output <- derive_param_ratio( + input_same_units, + by_vars = exprs(USUBJID, VISIT), + numerator_code = "WSTCIR", + denominator_code = "HIPCIR", + set_values_to = exprs( + PARAMCD = "WAISTHIP", + PARAM = "Waist to Hip Ratio" + ) + ) %>% + filter(PARAMCD == "WAISTHIP") + + expect_dfs_equal( + output_units_unified, + expected_output, + keys = c("USUBJID", "PARAMCD", "VISIT"), + tolerance = 0.0001 + ) + } +) From 888d2fa4feaf23ba85d16c235d13da615631d2af Mon Sep 17 00:00:00 2001 From: Andrii Yurovskyi Date: Wed, 30 Oct 2024 11:27:20 +0100 Subject: [PATCH 23/28] Added conversion factors in documentation --- DESCRIPTION | 1 + NAMESPACE | 2 ++ R/admiralmetabolic-package.R | 3 ++- R/derive_advs_params.R | 9 +++++++-- inst/WORDLIST | 1 - man/derive_param_ratio.Rd | 6 +++++- man/derive_param_waisthgt.Rd | 6 +++++- man/derive_param_waisthip.Rd | 6 +++++- man/unit-conversion.Rd | 2 +- 9 files changed, 28 insertions(+), 8 deletions(-) diff --git a/DESCRIPTION b/DESCRIPTION index 31ddf54..c440ab9 100644 --- a/DESCRIPTION +++ b/DESCRIPTION @@ -30,6 +30,7 @@ Imports: lifecycle (>= 0.1.0), lubridate (>= 1.7.4), magrittr (>= 1.5), + purrr (>= 0.3.3), rlang (>= 0.4.4), tidyselect (>= 1.0.0) Suggests: diff --git a/NAMESPACE b/NAMESPACE index c0e05bf..ced3370 100644 --- a/NAMESPACE +++ b/NAMESPACE @@ -70,6 +70,7 @@ importFrom(lubridate,years) importFrom(lubridate,ymd) importFrom(lubridate,ymd_hms) importFrom(magrittr,"%>%") +importFrom(purrr,discard_at) importFrom(rlang,"%||%") importFrom(rlang,":=") importFrom(rlang,.data) @@ -125,6 +126,7 @@ importFrom(stringr,str_c) importFrom(stringr,str_detect) importFrom(stringr,str_extract) importFrom(stringr,str_glue) +importFrom(stringr,str_glue_data) importFrom(stringr,str_remove) importFrom(stringr,str_remove_all) importFrom(stringr,str_replace) diff --git a/R/admiralmetabolic-package.R b/R/admiralmetabolic-package.R index 5435e1b..5b35a9e 100644 --- a/R/admiralmetabolic-package.R +++ b/R/admiralmetabolic-package.R @@ -11,6 +11,7 @@ #' starts_with transmute ungroup vars n_distinct union distinct #' summarise_at summarise coalesce bind_cols na_if tibble tribble #' @importFrom magrittr %>% +#' @importFrom purrr discard_at #' @importFrom rlang := %||% abort arg_match as_function as_string call2 caller_env #' call_name current_env .data enexpr enexprs enquo eval_bare eval_tidy expr #' exprs expr_interp expr_label f_lhs f_rhs inform @@ -21,7 +22,7 @@ #' set_names sym syms type_of warn quo_set_env quo_get_env #' @importFrom utils capture.output str #' @importFrom stringr str_c str_detect str_extract str_remove str_remove_all -#' str_replace str_trim str_to_lower str_to_title str_to_upper str_glue +#' str_replace str_trim str_to_lower str_to_title str_to_upper str_glue str_glue_data #' @importFrom lubridate as_datetime ceiling_date date days duration floor_date is.Date is.instant #' time_length %--% ymd ymd_hms weeks years hours minutes #' @importFrom tidyselect all_of contains vars_select diff --git a/R/derive_advs_params.R b/R/derive_advs_params.R index 19d32ed..65cbf79 100644 --- a/R/derive_advs_params.R +++ b/R/derive_advs_params.R @@ -455,7 +455,12 @@ derive_param_waisthgt <- function(dataset, #' convertible (e.g., centimeters for one parameter and inches for another), an automatic #' conversion will be performed in order to uniform the values before calculating the ratio. #' -#' **Note:** Conversion factors come from unit definitions as per the NCI Thesaurus. +#' **Note:** Conversion factors come from unit definitions as per CDISC standards. +#' ```{r, echo = FALSE, comment = "", results = "asis"} +#' get_conv_factors_all()[["length"]] %>% +#' discard_at("cm") %>% +#' str_glue_data("
*{names(.)}* is defined as {.} cm") +#' ``` #' #' *Permitted Values:* A variable of the input dataset or a function call #' @@ -609,7 +614,7 @@ get_conv_factor <- function(from_unit, to_unit) { #' @description `get_conv_factors_all()` returns all conversion factors supported. #' -#' **Note:** Conversion factors come from unit definitions as per the NCI Thesaurus. +#' **Note:** Conversion factors come from unit definitions as per CDISC standards. #' #' @rdname unit-conversion #' @keywords internal diff --git a/inst/WORDLIST b/inst/WORDLIST index 4766ddf..26e8d42 100644 --- a/inst/WORDLIST +++ b/inst/WORDLIST @@ -38,6 +38,5 @@ roxygen advs PARAMCD prm -NCI admiraldev github diff --git a/man/derive_param_ratio.Rd b/man/derive_param_ratio.Rd index e463c43..2461f86 100644 --- a/man/derive_param_ratio.Rd +++ b/man/derive_param_ratio.Rd @@ -106,7 +106,11 @@ Additionally, if the input parameters are measured in different units but are mu convertible (e.g., centimeters for one parameter and inches for another), an automatic conversion will be performed in order to uniform the values before calculating the ratio. -\strong{Note:} Conversion factors come from unit definitions as per the NCI Thesaurus. +\strong{Note:} Conversion factors come from unit definitions as per CDISC standards. +\if{html}{\out{
}}\emph{m} is defined as 100 cm +\if{html}{\out{
}}\emph{mm} is defined as 0.1 cm +\if{html}{\out{
}}\emph{in} is defined as 2.54 cm +\if{html}{\out{
}}\emph{ft} is defined as 30.48 cm \emph{Permitted Values:} A variable of the input dataset or a function call} } diff --git a/man/derive_param_waisthgt.Rd b/man/derive_param_waisthgt.Rd index 5ce7efd..4ddfaee 100644 --- a/man/derive_param_waisthgt.Rd +++ b/man/derive_param_waisthgt.Rd @@ -85,7 +85,11 @@ Additionally, if the input parameters are measured in different units but are mu convertible (e.g., centimeters for one parameter and inches for another), an automatic conversion will be performed in order to uniform the values before calculating the ratio. -\strong{Note:} Conversion factors come from unit definitions as per the NCI Thesaurus. +\strong{Note:} Conversion factors come from unit definitions as per CDISC standards. +\if{html}{\out{
}}\emph{m} is defined as 100 cm +\if{html}{\out{
}}\emph{mm} is defined as 0.1 cm +\if{html}{\out{
}}\emph{in} is defined as 2.54 cm +\if{html}{\out{
}}\emph{ft} is defined as 30.48 cm \emph{Permitted Values:} A variable of the input dataset or a function call} } diff --git a/man/derive_param_waisthip.Rd b/man/derive_param_waisthip.Rd index d29cbed..a3c7031 100644 --- a/man/derive_param_waisthip.Rd +++ b/man/derive_param_waisthip.Rd @@ -72,7 +72,11 @@ Additionally, if the input parameters are measured in different units but are mu convertible (e.g., centimeters for one parameter and inches for another), an automatic conversion will be performed in order to uniform the values before calculating the ratio. -\strong{Note:} Conversion factors come from unit definitions as per the NCI Thesaurus. +\strong{Note:} Conversion factors come from unit definitions as per CDISC standards. +\if{html}{\out{
}}\emph{m} is defined as 100 cm +\if{html}{\out{
}}\emph{mm} is defined as 0.1 cm +\if{html}{\out{
}}\emph{in} is defined as 2.54 cm +\if{html}{\out{
}}\emph{ft} is defined as 30.48 cm \emph{Permitted Values:} A variable of the input dataset or a function call} } diff --git a/man/unit-conversion.Rd b/man/unit-conversion.Rd index 3644723..8210026 100644 --- a/man/unit-conversion.Rd +++ b/man/unit-conversion.Rd @@ -16,6 +16,6 @@ Returns \code{NA} if units are not supported/convertible. \code{get_conv_factors_all()} returns all conversion factors supported. -\strong{Note:} Conversion factors come from unit definitions as per the NCI Thesaurus. +\strong{Note:} Conversion factors come from unit definitions as per CDISC standards. } \keyword{internal} From d92721dd2ca24c6a898582f3f953c3becf1f1571 Mon Sep 17 00:00:00 2001 From: Andrii Yurovskyi Date: Wed, 30 Oct 2024 16:33:38 +0100 Subject: [PATCH 24/28] Apply suggestions from code review Co-authored-by: Edoardo Mancini <53403957+manciniedoardo@users.noreply.github.com> --- R/derive_advs_params.R | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/R/derive_advs_params.R b/R/derive_advs_params.R index 65cbf79..7e3e6b4 100644 --- a/R/derive_advs_params.R +++ b/R/derive_advs_params.R @@ -1,6 +1,6 @@ #' Adds a Parameter for Waist to Hip Ratio #' -#' @description Adds a record for Waist to Hip Ratio using Waist Circumference and Hip Circumference +#' @description Adds a parameter for Waist to Hip Ratio using Waist Circumference and Hip Circumference #' for each by group (e.g., subject and visit) where the source parameters are available. #' #' **Note:** This is a wrapper function for the more generic [`admiral::derive_param_computed()`]. @@ -166,7 +166,7 @@ derive_param_waisthip <- function(dataset, #' Adds a Parameter for Waist to Height Ratio #' -#' @description Adds a record for Waist to Height Ratio using Waist Circumference and Height +#' @description Adds a parameter for Waist to Height Ratio using Waist Circumference and Height #' for each by group (e.g., subject and visit) where the source parameters are available. #' #' **Note:** This is a wrapper function for the more generic [`admiral::derive_param_computed()`]. From 1009e766fc3529b28041c4be2514cb793513cee3 Mon Sep 17 00:00:00 2001 From: Andrii Yurovskyi Date: Wed, 30 Oct 2024 16:36:21 +0100 Subject: [PATCH 25/28] Roxygenize after applying suggestions from code review --- man/derive_param_waisthgt.Rd | 2 +- man/derive_param_waisthip.Rd | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/man/derive_param_waisthgt.Rd b/man/derive_param_waisthgt.Rd index 4ddfaee..3523d36 100644 --- a/man/derive_param_waisthgt.Rd +++ b/man/derive_param_waisthgt.Rd @@ -98,7 +98,7 @@ The input dataset with the new parameter added. Note, a variable will only be populated in the new parameter rows if it is specified in \code{by_vars}. } \description{ -Adds a record for Waist to Height Ratio using Waist Circumference and Height +Adds a parameter for Waist to Height Ratio using Waist Circumference and Height for each by group (e.g., subject and visit) where the source parameters are available. \strong{Note:} This is a wrapper function for the more generic \code{\link[admiral:derive_param_computed]{admiral::derive_param_computed()}}. diff --git a/man/derive_param_waisthip.Rd b/man/derive_param_waisthip.Rd index a3c7031..d5cd21a 100644 --- a/man/derive_param_waisthip.Rd +++ b/man/derive_param_waisthip.Rd @@ -85,7 +85,7 @@ The input dataset with the new parameter added. Note, a variable will only be populated in the new parameter rows if it is specified in \code{by_vars}. } \description{ -Adds a record for Waist to Hip Ratio using Waist Circumference and Hip Circumference +Adds a parameter for Waist to Hip Ratio using Waist Circumference and Hip Circumference for each by group (e.g., subject and visit) where the source parameters are available. \strong{Note:} This is a wrapper function for the more generic \code{\link[admiral:derive_param_computed]{admiral::derive_param_computed()}}. From 1d649f80f39707d0785e5e7db5c7b2e92a3b08b7 Mon Sep 17 00:00:00 2001 From: Andrii Yurovskyi Date: Wed, 30 Oct 2024 16:38:55 +0100 Subject: [PATCH 26/28] Fix lintr issues after applying suggestions from code review --- R/derive_advs_params.R | 5 +++-- man/derive_param_waisthip.Rd | 5 +++-- 2 files changed, 6 insertions(+), 4 deletions(-) diff --git a/R/derive_advs_params.R b/R/derive_advs_params.R index 7e3e6b4..2651c28 100644 --- a/R/derive_advs_params.R +++ b/R/derive_advs_params.R @@ -1,7 +1,8 @@ #' Adds a Parameter for Waist to Hip Ratio #' -#' @description Adds a parameter for Waist to Hip Ratio using Waist Circumference and Hip Circumference -#' for each by group (e.g., subject and visit) where the source parameters are available. +#' @description Adds a parameter for Waist to Hip Ratio using Waist Circumference and +#' Hip Circumference for each by group (e.g., subject and visit) where the source parameters +#' are available. #' #' **Note:** This is a wrapper function for the more generic [`admiral::derive_param_computed()`]. #' diff --git a/man/derive_param_waisthip.Rd b/man/derive_param_waisthip.Rd index d5cd21a..fd9bf7f 100644 --- a/man/derive_param_waisthip.Rd +++ b/man/derive_param_waisthip.Rd @@ -85,8 +85,9 @@ The input dataset with the new parameter added. Note, a variable will only be populated in the new parameter rows if it is specified in \code{by_vars}. } \description{ -Adds a parameter for Waist to Hip Ratio using Waist Circumference and Hip Circumference -for each by group (e.g., subject and visit) where the source parameters are available. +Adds a parameter for Waist to Hip Ratio using Waist Circumference and +Hip Circumference for each by group (e.g., subject and visit) where the source parameters +are available. \strong{Note:} This is a wrapper function for the more generic \code{\link[admiral:derive_param_computed]{admiral::derive_param_computed()}}. } From 058e6a50a70d8801c6c54b809794f3c31a9d38e7 Mon Sep 17 00:00:00 2001 From: Andrii Yurovskyi Date: Wed, 30 Oct 2024 17:08:11 +0100 Subject: [PATCH 27/28] Unit tests for get_conv_factor --- tests/testthat/test-get_conv_factor.R | 20 ++++++++++++++++++++ 1 file changed, 20 insertions(+) create mode 100644 tests/testthat/test-get_conv_factor.R diff --git a/tests/testthat/test-get_conv_factor.R b/tests/testthat/test-get_conv_factor.R new file mode 100644 index 0000000..cc5474d --- /dev/null +++ b/tests/testthat/test-get_conv_factor.R @@ -0,0 +1,20 @@ +test_that("get_conv_factor Test 1: Direct conversion factor for length (to cm)", { + expect_equal( + get_conv_factor("in", "cm"), + 2.54 + ) +}) + +test_that("get_conv_factor Test 2: Indirect conversion factor for length (via cm)", { + expect_equal( + get_conv_factor("ft", "in"), + 12 + ) +}) + +test_that("get_conv_factor Test 3: Inconvertible units", { + expect_equal( + get_conv_factor("cm", "kg"), + NA_real_ + ) +}) From 59084330090f2434c1821bfbd01eb4cfb3ef629c Mon Sep 17 00:00:00 2001 From: Andrii Yurovskyi Date: Wed, 30 Oct 2024 21:37:15 +0100 Subject: [PATCH 28/28] One more test to reach 100% test coverage --- tests/testthat/test-derive_param_ratio.R | 29 ++++++++++++++++++++++++ 1 file changed, 29 insertions(+) diff --git a/tests/testthat/test-derive_param_ratio.R b/tests/testthat/test-derive_param_ratio.R index 9661059..9acb368 100644 --- a/tests/testthat/test-derive_param_ratio.R +++ b/tests/testthat/test-derive_param_ratio.R @@ -215,3 +215,32 @@ test_that( ) } ) + +test_that( + "derive_param_ratio Test 5: Both input parameters are constant", + { + input <- tribble( + ~USUBJID, ~PARAMCD, ~PARAM, ~AVAL, ~AVALU, ~VISIT, + "01-101-1001", "HEIGHT", "Height (cm)", 147, "cm", "SCREENING", + "01-101-1001", "WSTCIR", "Waist Circumference (cm)", 110, "cm", "SCREENING", + "01-101-1002", "HEIGHT", "Height (cm)", 163, "cm", "SCREENING", + "01-101-1002", "WSTCIR", "Waist Circumference (cm)", 120, "cm", "SCREENING" + ) + + expect_error( + derive_param_ratio( + input, + by_vars = exprs(USUBJID, VISIT), + numerator_code = "WSTCIR", + denominator_code = "HEIGHT", + set_values_to = exprs( + PARAMCD = "WAISTHGT", + PARAM = "Waist to Height Ratio" + ), + constant_numerator = TRUE, + constant_denominator = TRUE, + constant_by_vars = exprs(USUBJID) + ) + ) + } +)