Closes #2001 Added processing for missing age_units in compute_age_years

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)

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"
   )

R/derive_vars_aage.R

@@ -27,14 +27,16 @@
 #'
 #'   Default: `RANDDT`
 #'
-#' @param unit Unit
+#' @param age_unit Age unit
 #'
 #'   The age is derived in the specified unit
 #'
 #'   Default: 'years'
 #'
 #'   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
   )

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/
 

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(

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,26 +55,26 @@ 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),
     "`age_unit` must be one of 'years', 'months', 'weeks', 'days', 'hours', 'minutes' or 'seconds' but is 'month'" # nolint
   )
 })
 
-## 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(