diff --git a/NEWS.md b/NEWS.md index 788b98978f..8059eced6f 100644 --- a/NEWS.md +++ b/NEWS.md @@ -4,6 +4,7 @@ ## Updates of Existing Functions - The functions `derive_param_bmi()` and `derive_param_bsa()` are updated to have the option of producing more values at visits when only weight is collected (#1228). +- The functions `derive_var_age_years()` and `compute_age_years()` are updated to return an `NA` age in the case that the age unit is missing. (#2001) The argument `unit` for `derive_vars_aage()` is also changed to `age_unit` for consistency between these age-related functions. (#2025) ## Breaking Changes - The following functions, which were deprecated in previous `{admiral}` versions, have been removed: (#1950) diff --git a/R/compute_age_years.R b/R/compute_age_years.R index 10afc698bb..529a864fad 100644 --- a/R/compute_age_years.R +++ b/R/compute_age_years.R @@ -14,10 +14,12 @@ #' as `"years"` and `"Years"`). #' #' Permitted Values: `"years"`, `"months"`, `"weeks"`, `"days"`, `"hours"`, `"minutes"`, -#' `"seconds"`. +#' `"seconds"`, `NA_character_`. #' -#' @details Returns a numeric vector of ages in years as doubles. Note, underlying -#' computations assume an equal number of days in each year (365.25). +#' @details Returns a numeric vector of ages in years as doubles. Note +#' that passing `NA_character_` as a unit will result in an `NA` value for the outputted +#' age. Also note, underlying computations assume an equal number of days in each +#' year (365.25). #' #' @return The ages contained in `age` converted to years. #' @@ -34,8 +36,8 @@ #' ) #' #' compute_age_years( -#' age = c(10, 520, 3650), -#' age_unit = c("YEARS", "WEEKS", "DAYS") +#' age = c(10, 520, 3650, 1000), +#' age_unit = c("YEARS", "WEEKS", "DAYS", NA_character_) #' ) #' compute_age_years <- function(age, @@ -57,9 +59,16 @@ compute_age_years <- function(age, )) } + if (length(age_unit) == 1) { + age_unit_rep <- rep(age_unit, length(age)) + } else { + age_unit_rep <- age_unit + } + age_years <- time_length( - duration(age, - units = tolower(age_unit) + duration( + num = if_else(is.na(age_unit_rep), NA_real_, age), + units = if_else(is.na(age_unit_rep), "years", tolower(age_unit_rep)) ), unit = "years" ) diff --git a/R/derive_vars_aage.R b/R/derive_vars_aage.R index c8c041562c..575fecc10b 100644 --- a/R/derive_vars_aage.R +++ b/R/derive_vars_aage.R @@ -27,7 +27,7 @@ #' #' Default: `RANDDT` #' -#' @param unit Unit +#' @param age_unit Age unit #' #' The age is derived in the specified unit #' @@ -35,6 +35,8 @@ #' #' Permitted Values: 'years', 'months', 'weeks', 'days', 'hours', 'minutes', 'seconds' #' +#' @param unit *Deprecated*, please use `age_unit` instead. +#' #' @details The age is derived as the integer part of the duration from start to #' end date in the specified unit. When 'years' or 'months' are specified in the `out_unit` #' parameter, because of the underlying `lubridate::time_length()` function that is used @@ -64,12 +66,18 @@ derive_vars_aage <- function(dataset, start_date = BRTHDT, end_date = RANDDT, - unit = "years") { + unit = "years", + age_unit = "years") { + if (!missing(unit)) { + deprecate_warn("0.12.0", "derive_vars_aage(unit = )", "derive_vars_aage(age_unit = )") + age_unit <- unit + } + start_date <- assert_symbol(enexpr(start_date)) end_date <- assert_symbol(enexpr(end_date)) assert_data_frame(dataset, required_vars = expr_c(start_date, end_date)) assert_character_scalar( - unit, + age_unit, values = c("years", "months", "weeks", "days", "hours", "minutes", "seconds") ) @@ -79,7 +87,7 @@ derive_vars_aage <- function(dataset, new_var_unit = AAGEU, start_date = !!start_date, end_date = !!end_date, - out_unit = unit, + out_unit = age_unit, add_one = FALSE, trunc_out = TRUE ) diff --git a/docs/pkgdown.yml b/docs/pkgdown.yml index 8492dafdf7..2e9fb51fe5 100644 --- a/docs/pkgdown.yml +++ b/docs/pkgdown.yml @@ -19,8 +19,8 @@ articles: queries_dataset: queries_dataset.html questionnaires: questionnaires.html visits_periods: visits_periods.html -last_built: 2023-05-31T14:16Z +last_built: 2023-07-19T10:42Z urls: - reference: https://pharmaverse.github.io/admiral/cran-release/reference - article: https://pharmaverse.github.io/admiral/cran-release/articles + reference: https://pharmaverse.github.io/admiral/cran-release/reference/ + article: https://pharmaverse.github.io/admiral/cran-release/articles/ diff --git a/man/compute_age_years.Rd b/man/compute_age_years.Rd index b4f4cfff56..6c1d05c440 100644 --- a/man/compute_age_years.Rd +++ b/man/compute_age_years.Rd @@ -19,7 +19,7 @@ permitted values are cases insensitive (e.g. \code{"YEARS"} is treated the same as \code{"years"} and \code{"Years"}). Permitted Values: \code{"years"}, \code{"months"}, \code{"weeks"}, \code{"days"}, \code{"hours"}, \code{"minutes"}, -\code{"seconds"}.} +\code{"seconds"}, \code{NA_character_}.} } \value{ The ages contained in \code{age} converted to years. @@ -28,8 +28,10 @@ The ages contained in \code{age} converted to years. Converts a set of age values from the specified time unit to years. } \details{ -Returns a numeric vector of ages in years as doubles. Note, underlying -computations assume an equal number of days in each year (365.25). +Returns a numeric vector of ages in years as doubles. Note +that passing \code{NA_character_} as a unit will result in an \code{NA} value for the outputted +age. Also note, underlying computations assume an equal number of days in each +year (365.25). } \examples{ compute_age_years( @@ -38,8 +40,8 @@ compute_age_years( ) compute_age_years( - age = c(10, 520, 3650), - age_unit = c("YEARS", "WEEKS", "DAYS") + age = c(10, 520, 3650, 1000), + age_unit = c("YEARS", "WEEKS", "DAYS", NA_character_) ) } diff --git a/man/derive_vars_aage.Rd b/man/derive_vars_aage.Rd index 6c43f19929..2b3fa6c496 100644 --- a/man/derive_vars_aage.Rd +++ b/man/derive_vars_aage.Rd @@ -8,7 +8,8 @@ derive_vars_aage( dataset, start_date = BRTHDT, end_date = RANDDT, - unit = "years" + unit = "years", + age_unit = "years" ) } \arguments{ @@ -35,7 +36,9 @@ vector to a date object. Default: \code{RANDDT}} -\item{unit}{Unit +\item{unit}{\emph{Deprecated}, please use \code{age_unit} instead.} + +\item{age_unit}{Age unit The age is derived in the specified unit diff --git a/tests/testthat/test-compute_age_years.R b/tests/testthat/test-compute_age_years.R index 00a4a9a539..e96d04bff6 100644 --- a/tests/testthat/test-compute_age_years.R +++ b/tests/testthat/test-compute_age_years.R @@ -16,10 +16,10 @@ test_that("compute_age_years Test 1: compute_age_years() works when `age_unit` i ## Test 2: compute_age_years() works when `age_unit` is a vector ---- test_that("compute_age_years Test 2: compute_age_years() works when `age_unit` is a vector", { - age_input <- c(28, 1461, 10227) - age_unit_input <- c("YEARS", "WEEKS", "DAYS") + age_input <- c(28, 1461, 10227, 32) + age_unit_input <- c("YEARS", "WEEKS", "DAYS", NA_character_) - expected_output <- rep(28, 3) + expected_output <- c(28, 28, 28, NA) expect_equal( compute_age_years( diff --git a/tests/testthat/test-derive_vars_aage.R b/tests/testthat/test-derive_vars_aage.R index 0116ae8c83..23248b082c 100644 --- a/tests/testthat/test-derive_vars_aage.R +++ b/tests/testthat/test-derive_vars_aage.R @@ -10,9 +10,21 @@ test_that("derive_vars_aage Test 1: duration and unit variable are added", { expect_dfs_equal(derive_vars_aage(input), expected_output, keys = c("BRTHDT", "RANDDT")) }) +## Test 2: duration and unit variable are added ---- +test_that("derive_vars_aage Test 2: Error is thrown when age_unit is not proper unit", { + input <- tibble::tribble( + ~BRTHDT, ~RANDDT, + ymd("1999-09-09"), ymd("2020-02-20") + ) + expect_error( + derive_vars_aage(input, age_unit = "centuries"), + "`age_unit` must be one of 'years', 'months', 'weeks', 'days', 'hours', 'minutes' or 'seconds' but is 'centuries'" # nolint + ) +}) + # derive_var_age_years ---- -## Test 2: derive_var_age_years works as expected when AGEU exists ---- -test_that("derive_var_age_years Test 2: derive_var_age_years works as expected when AGEU exists", { +## Test 3: derive_var_age_years works as expected when AGEU exists ---- +test_that("derive_var_age_years Test 3: derive_var_age_years works as expected when AGEU exists", { input <- tibble::tibble( AGE = c(12, 24, 36, 48, 60), AGEU = c("months", "months", "months", "months", "months") @@ -26,9 +38,9 @@ test_that("derive_var_age_years Test 2: derive_var_age_years works as expected w expect_dfs_equal(derive_var_age_years(input, AGE, new_var = AAGE), expected_output, keys = "AGE") }) -## Test 3: derive_var_age_years works as expected when AGEU doesn't exist and +## Test 4: derive_var_age_years works as expected when AGEU doesn't exist and ## `age_unit` is used ---- -test_that("derive_var_age_years Test 3: derive_var_age_years works as expected +test_that("derive_var_age_years Test 4: derive_var_age_years works as expected when AGEU doesn't exist and `age_unit` is used", { input <- tibble::tibble(AGE = c(12, 24, 36, 48, 60)) @@ -43,8 +55,8 @@ test_that("derive_var_age_years Test 3: derive_var_age_years works as expected ) }) -## Test 4: Error is thrown when age_unit is not proper unit ---- -test_that("derive_var_age_years Test 4: Error is thrown when age_unit is not proper unit", { +## Test 5: Error is thrown when age_unit is not proper unit ---- +test_that("derive_var_age_years Test 5: Error is thrown when age_unit is not proper unit", { input <- data.frame(AGE = c(12, 24, 36, 48)) expect_error( derive_var_age_years(input, AGE, age_unit = "month", new_var = AAGE), @@ -52,17 +64,17 @@ test_that("derive_var_age_years Test 4: Error is thrown when age_unit is not pro ) }) -## Test 5: Error is issued if age_unit is missing ---- -test_that("derive_var_age_years Test 5: Error is issued if age_unit is missing", { +## Test 6: Error is issued if age_unit is missing ---- +test_that("derive_var_age_years Test 6: Error is issued if age_unit is missing", { input <- data.frame(AGE = c(12, 24, 36, 48)) expect_error( derive_var_age_years(input, AGE, new_var = AAGE) ) }) -## Test 6: Warning is issued if age_unit is not null, but the 'unit' variable +## Test 7: Warning is issued if age_unit is not null, but the 'unit' variable ## corresponding to age_var stores more than one unique value. ---- -test_that("derive_var_age_years Test 6: Warning is issued if age_unit is not +test_that("derive_var_age_years Test 7: Warning is issued if age_unit is not null, but the 'unit' variable corresponding to age_var stores more than one unique value.", { input <- tibble::tribble( @@ -81,8 +93,8 @@ test_that("derive_var_age_years Test 6: Warning is issued if age_unit is not }) -## Test 7: Error is issued if age_unit consists of more than one unique value. ---- -test_that("derive_var_age_years Test 7: Error is issued if age_unit consists of +## Test 8: Error is issued if age_unit consists of more than one unique value. ---- +test_that("derive_var_age_years Test 8: Error is issued if age_unit consists of more than one unique value.", { input <- tibble::tribble( ~AGE, ~AGEU, @@ -99,10 +111,10 @@ test_that("derive_var_age_years Test 7: Error is issued if age_unit consists of ) }) -## Test 8: The 'unit' variable corresponding to age_var will be considered as +## Test 9: The 'unit' variable corresponding to age_var will be considered as ## storing one unique unit, if values differ only by case, i.e. ## 'months', 'Months', 'MONTHS' considered same unit, etc. ---- -test_that("derive_var_age_years Test 8: The 'unit' variable corresponding to +test_that("derive_var_age_years Test 9: The 'unit' variable corresponding to age_var will be considered as storing one unique unit, if values differ only by case, i.e. 'months', 'Months', 'MONTHS' considered same unit, etc.", { @@ -135,10 +147,10 @@ test_that("derive_var_age_years Test 8: The 'unit' variable corresponding to ) }) -## Test 9: Warning is issued if age_unit is not null, but the 'unit' variable -## corresponding to age_var stores one unique unit that is not -## equivalent to age_unit. ---- -test_that("derive_var_age_years Test 9: Warning is issued if age_unit is not +## Test 10: Warning is issued if age_unit is not null, but the 'unit' variable +## corresponding to age_var stores one unique unit that is not +## equivalent to age_unit. ---- +test_that("derive_var_age_years Test 10: Warning is issued if age_unit is not null, but the 'unit' variable corresponding to age_var stores one unique unit that is not equivalent to age_unit.", { input <- tibble::tribble(