adding replace_null_statistic() (#186)

**What changes are proposed in this pull request?**
* Added the `replace_null_statistic()` function. (#185)

**Reference GitHub issue associated with pull request.** _e.g., 'closes
#<issue number>'_
closes #185 


--------------------------------------------------------------------------------

Pre-review Checklist (if item does not apply, mark is as complete)
- [ ] **All** GitHub Action workflows pass with a ✅
- [ ] PR branch has pulled the most recent updates from master branch:
`usethis::pr_merge_main()`
- [ ] If a bug was fixed, a unit test was added.
- [ ] Code coverage is suitable for any new functions/features
(generally, 100% coverage for new code): `devtools::test_coverage()`
- [ ] Request a reviewer

Reviewer Checklist (if item does not apply, mark is as complete)

- [ ] If a bug was fixed, a unit test was added.
- [ ] Run `pkgdown::build_site()`. Check the R console for errors, and
review the rendered website.
- [ ] Code coverage is suitable for any new functions/features:
`devtools::test_coverage()`

When the branch is ready to be merged:
- [ ] Update `NEWS.md` with the changes from this pull request under the
heading "`# cards (development version)`". If there is an issue
associated with the pull request, reference it in parentheses at the end
update (see `NEWS.md` for examples).
- [ ] **All** GitHub Action workflows pass with a ✅
- [ ] Approve Pull Request
- [ ] Merge the PR. Please use "Squash and merge" or "Rebase and merge".

NAMESPACE

@@ -46,6 +46,7 @@ export(one_of)
 export(print_ard_conditions)
 export(process_formula_selectors)
 export(process_selectors)
+export(replace_null_statistic)
 export(round5)
 export(shuffle_ard)
 export(starts_with)

R/replace_null_statistic.R

@@ -0,0 +1,45 @@
+#' Replace NULL Statistics with Specified Value
+#'
+#' When a statistical summary function errors, the `"statistic"` column will be
+#' `NULL`. It is, however, sometimes useful to replace these values with a
+#' non-`NULL` value, e.g. `NA`.
+#'
+#'
+#' @param x (`data.frame`)\cr
+#'   an ARD data frame of class 'card'
+#' @param value (usually a `scalar`)\cr
+#'   The value to replace `NULL` values with. Default is `NA`.
+#' @param rows ([`data-masking`][rlang::args_data_masking])\cr
+#'   Expression that return a logical value, and are defined in terms of the variables in `.data`.
+#'   Only rows for which the condition evaluates to `TRUE` are replaced.
+#'   Default is `TRUE`, which applies to all rows.
+#'
+#' @return an ARD data frame of class 'card'
+#' @export
+#'
+#' @examples
+#' # the quantile functions error because the input is character, while the median function returns NA
+#' data.frame(x = rep_len(NA_character_, 10)) |>
+#'   ard_continuous(
+#'     variables = x,
+#'     statistics = ~ continuous_variable_summary_fns(c("median", "p25", "p75"))
+#'   ) |>
+#'   replace_null_statistic(rows = !is.null(error))
+replace_null_statistic <- function(x, value = NA, rows = TRUE) {
+  # check inputs ---------------------------------------------------------------
+  check_class(x, "card")
+
+  # replace NULL values --------------------------------------------------------
+  x |>
+    dplyr::rowwise() |>
+    dplyr::mutate(
+      # styler: off
+      statistic =
+        if (is.null(.data$statistic) && {{ rows }}) list(.env$value)
+        else list(.data$statistic)
+      # styler: on
+    ) |>
+    # restore previous grouping structure and original class of x
+    dplyr::group_by(dplyr::pick(dplyr::group_vars(x))) |>
+    structure(class = class(x))
+}

_pkgdown.yml

@@ -45,6 +45,7 @@ reference:
       - shuffle_ard
       - as_nested_list
       - get_ard_statistics
+      - replace_null_statistic
   - subtitle: "Data Summary Functions"
     contents:
       - continuous_variable_summary_fns

tests/testthat/test-replace_null_statistic.R

@@ -0,0 +1,18 @@
+test_that("replace_null_statistic() works", {
+  expect_error(
+    ard_with_missing_stats <-
+      data.frame(x = rep_len(NA_character_, 10)) |>
+      ard_continuous(
+        variables = x,
+        statistics = ~ continuous_variable_summary_fns(c("median", "p25", "p75"))
+      ) |>
+      replace_null_statistic(rows = !is.null(error)),
+    NA
+  )
+
+  # all results should now be NA_character
+  expect_equal(
+    ard_with_missing_stats$statistic |> unlist() |> unique(),
+    NA_character_
+  )
+})