Merge 2b805a2 into edb15c2

NAMESPACE

@@ -29,6 +29,7 @@ export(ard_hierarchical)
 export(ard_hierarchical_count)
 export(ard_missing)
 export(ard_stack)
+export(ard_total_n)
 export(as_nested_list)
 export(bind_ard)
 export(cards_select)

NEWS.md

@@ -1,5 +1,7 @@
 # cards 0.1.0.9037
 
+* Added new function `ard_total_n()` for calculating the total N in a data frame. (#236)
+
 * The API for `ard_continuous(statistic)` and `ard_missing(statistic)` arguments has been updated. Previously, the RHS of these argument's passed lists would be either `continuous_summary_fns()` and `missing_summary_fns()`. Now these arguments accept simple character vectors of the statistic names. For example, `ard_categorical(statistic = everything() ~ c("n", "p", "N"))` and `ard_missing(statistic = everything() ~ c("N_obs", "N_miss", "N_nonmiss", "p_miss", "p_nonmiss"))`. (#223) 
 
 * Added the `nest_for_ard(include_data)` argument to either include or exclude the subsetted data frames in a list-column in the returned tibble.

R/ard_stack.R

@@ -27,10 +27,12 @@
 #' @param .shuffle (`logical`)\cr
 #'   logical indicating whether to perform `shuffle_ard()` on the final result.
 #'   Default is `FALSE`.
+#' @param .total_n (`logical`)\cr
+#'   logical indicating whether to include of `ard_total_n()` in the returned ARD.
 #'
 #' @return  a transformed ARD data frame (of class 'card' if `.shuffle = FALSE`)
-#'
 #' @export
+#'
 #' @examples
 #' ard_stack(
 #'   data = ADSL,
@@ -55,6 +57,7 @@ ard_stack <- function(data,
                       .overall = FALSE,
                       .missing = FALSE,
                       .attributes = FALSE,
+                      .total_n = FALSE,
                       .shuffle = FALSE) {
   set_cli_abort_call()
 
@@ -69,6 +72,7 @@ ard_stack <- function(data,
   check_scalar_logical(.missing)
   check_scalar_logical(.attributes)
   check_scalar_logical(.shuffle)
+  check_scalar_logical(.total_n)
 
   if (is_empty(.by) && isTRUE(.overall)) {
     cli::cli_inform(
@@ -128,6 +132,14 @@ ard_stack <- function(data,
     )
   }
 
+  # total n
+  if (isTRUE(.total_n)) {
+    ard_full <- bind_ard(
+      ard_full,
+      ard_total_n(data)
+    )
+  }
+
   # order
   ard_full <- tidy_ard_row_order(ard_full)
 

R/ard_total_n.R

@@ -0,0 +1,24 @@
+#' ARD Total N
+#'
+#' Returns the total N for the data frame.
+#' The placeholder variable name returned in the object is `"..ard_total_n.."`
+#'
+#' @inheritParams ard_dichotomous
+#'
+#' @return an ARD data frame of class 'card'
+#' @export
+#'
+#' @examples
+#' ard_total_n(ADSL)
+ard_total_n <- function(data) {
+  # process inputs -------------------------------------------------------------
+  set_cli_abort_call()
+  check_data_frame(data)
+
+  # calculate total N ----------------------------------------------------------
+  data |>
+    dplyr::mutate(..ard_total_n.. = TRUE) |>
+    ard_dichotomous(variables = "..ard_total_n..", statistic = list(..ard_total_n.. = "N")) |>
+    dplyr::mutate(context = "total_n") |>
+    dplyr::select(-all_ard_variables("levels"))
+}

_pkgdown.yml

@@ -29,6 +29,7 @@ reference:
       - ard_hierarchical
       - ard_dichotomous
       - ard_missing
+      - ard_total_n
       - ard_complex
       - ard_stack
 

tests/testthat/_snaps/ard_total_n.md

@@ -0,0 +1,16 @@
+# ard_total_n() works
+
+    Code
+      as.data.frame(ard_total_n(ADSL))
+    Output
+               variable context stat_name stat_label stat fmt_fn warning error
+      1 ..ard_total_n.. total_n         N          N  254      0    NULL  NULL
+
+---
+
+    Code
+      ard_total_n(letters)
+    Condition
+      Error in `ard_total_n()`:
+      ! The `data` argument must be class <data.frame>, not a character vector.
+

tests/testthat/test-ard_stack.R

@@ -190,6 +190,19 @@ test_that("ard_stack() .shuffle argument", {
   )
 })
 
+test_that("ard_stack() adding total N", {
+  expect_equal(
+    ard_stack(
+      mtcars,
+      .by = am,
+      ard_continuous(variables = mpg),
+      .total_n = TRUE
+    ) |>
+      tail(n = 1) |>
+      dplyr::select(-all_ard_groups(), -all_ard_variables("levels")),
+    ard_total_n(mtcars)
+  )
+})
 
 test_that("ard_stack() works with namespaced functions", {
   expect_equal(

tests/testthat/test-ard_total_n.R

@@ -0,0 +1,11 @@
+test_that("ard_total_n() works", {
+  expect_snapshot(
+    ard_total_n(ADSL) |>
+      as.data.frame()
+  )
+
+  expect_snapshot(
+    error = TRUE,
+    ard_total_n(letters)
+  )
+})