Fmt fn to fmt fun (#302)

**What changes are proposed in this pull request?**
* Updating any `fmt_fn` references to `fmt_fun` for consistency. 
* Any function with an argument `cardx::foo(fmt_fn)` has been updated to
`cardx::foo(fmt_fun)`. The old syntax will continue to function, but
with a deprecation warning to users.
* Importantly, the ARD column named `"fmt_fn"` has been updated to
`"fmt_fun"`. This change cannot be formally deprecated. For users who
were accessing the ARD object directly to modify this column instead of
using functions like `cards::update_ard_fmt_fun()`, this will be a
breaking change.



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

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.
- [ ] If a new `ard_*()` function was added, it passes the ARD
structural checks from `cards::check_ard_structure()`.
- [ ] If a new `ard_*()` function was added, `set_cli_abort_call()` has
been set.
- [ ] If a new `ard_*()` function was added and it depends on another
package (such as, `broom`), `is_pkg_installed("broom")` has been set in
the function call and the following added to the roxygen comments:
`@examplesIf do.call(asNamespace("cardx")$is_pkg_installed, list(pkg =
"broom""))`
- [ ] Code coverage is suitable for any new functions/features
(generally, 100% coverage for new code): `devtools::test_coverage()`

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

- [ ] If a bug was fixed, a unit test was added.
- [ ] 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 "`# cardx (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".

Author: ddsjoberg

DESCRIPTION

@@ -20,7 +20,7 @@ BugReports: https://github.com/insightsengineering/cardx/issues
 Depends:
     R (>= 4.2)
 Imports:
-    cards (>= 0.5.1),
+    cards (>= 0.6.0.9011),
     cli (>= 3.6.1),
     dplyr (>= 1.1.2),
     glue (>= 1.6.2),
@@ -44,6 +44,7 @@ Suggests:
     survival (>= 3.6-4),
     testthat (>= 3.2.0),
     withr (>= 2.5.0)
+Remotes: insightsengineering/cards
 Config/Needs/website: insightsengineering/nesttemplate
 Config/testthat/edition: 3
 Config/testthat/parallel: true

NAMESPACE

@@ -108,3 +108,4 @@ importFrom(dplyr,num_range)
 importFrom(dplyr,one_of)
 importFrom(dplyr,starts_with)
 importFrom(dplyr,where)
+importFrom(lifecycle,deprecated)

NEWS.md

@@ -1,5 +1,11 @@
 # cardx 0.2.4.9006
 
+* Updating any `fmt_fn` references to `fmt_fun` for consistency. 
+
+    * Any function with an argument `cardx::foo(fmt_fn)` has been updated to `cardx::foo(fmt_fun)`. The old syntax will continue to function, but with a deprecation warning to users.
+
+    * Importantly, the ARD column named `"fmt_fn"` has been updated to `"fmt_fun"`. This change cannot be formally deprecated. For users who were accessing the ARD object directly to modify this column instead of using functions like `cards::update_ard_fmt_fun()`, this will be a breaking change.
+    
 * Adding `strata` argument to `ard_categorical_max()`. (#445, @jtalboys)
 
 * Added function `ard_incidence_rate()` to calculate ARDs for incidence rate estimation. (#234)

R/ard_aod_wald_test.R

@@ -85,7 +85,7 @@ ard_aod_wald_test <- function(x, tidy_fun = broom.helpers::tidy_with_broom_or_pa
           .data$stat_name %in% "p.value" ~ "p-value",
           TRUE ~ .data$stat_name
         ),
-      fmt_fn =
+      fmt_fun =
         map(
           .data$stat,
           function(.x) {

R/ard_car_anova.R

@@ -54,7 +54,7 @@ ard_car_anova <- function(x, ...) {
           .data$stat_name %in% "p.value" ~ "p-value",
           TRUE ~ .data$stat_name
         ),
-      fmt_fn =
+      fmt_fun =
         map(
           .data$stat,
           function(.x) {

R/ard_car_vif.R

@@ -80,7 +80,7 @@ ard_car_vif <- function(x, ...) {
         "Adjusted GVIF",
         .data$stat_name
       ),
-      fmt_fn = map(
+      fmt_fun = map(
         .data$stat,
         function(.x) {
           # styler: off

R/ard_categorical.survey.design.R

@@ -23,7 +23,7 @@
 #'   a named list, a list of formulas,
 #'   or a single formula where the list element is a character vector of
 #'   statistic names to include. See default value for options.
-#' @param fmt_fn ([`formula-list-selector`][cards::syntax])\cr
+#' @param fmt_fun ([`formula-list-selector`][cards::syntax])\cr
 #'   a named list, a list of formulas,
 #'   or a single formula where the list element is a named list of functions
 #'   (or the RHS of a formula),
@@ -33,6 +33,7 @@
 #'   the list element is either a named list or a list of formulas defining the
 #'   statistic labels, e.g. `everything() ~ list(mean = "Mean", sd = "SD")` or
 #'   `everything() ~ list(mean ~ "Mean", sd ~ "SD")`.
+#' @param fmt_fn `r lifecycle::badge("deprecated")`
 #' @inheritParams rlang::args_dots_empty
 #'
 #' @return an ARD data frame of class 'card'
@@ -47,7 +48,7 @@ ard_categorical.survey.design <- function(data,
                                           by = NULL,
                                           statistic = everything() ~ c("n", "N", "p", "p.std.error", "deff", "n_unweighted", "N_unweighted", "p_unweighted"),
                                           denominator = c("column", "row", "cell"),
-                                          fmt_fn = NULL,
+                                          fmt_fun = NULL,
                                           stat_label = everything() ~ list(
                                             p = "%",
                                             p.std.error = "SE(%)",
@@ -56,12 +57,23 @@ ard_categorical.survey.design <- function(data,
                                             "N_unweighted" = "Unweighted N",
                                             "p_unweighted" = "Unweighted %"
                                           ),
+                                          fmt_fn = deprecated(),
                                           ...) {
   set_cli_abort_call()
   check_pkg_installed(pkg = "survey")
   check_dots_empty()
   deff <- TRUE # we may update in the future to make this an argument for users
 
+  # deprecated args ------------------------------------------------------------
+  if (lifecycle::is_present(fmt_fn)) {
+    lifecycle::deprecate_soft(
+      when = "0.2.5",
+      what = "ard_categorical(fmt_fn)",
+      with = "ard_categorical(fmt_fun)"
+    )
+    fmt_fun <- fmt_fn
+  }
+
   # process arguments ----------------------------------------------------------
   check_not_missing(variables)
   cards::process_selectors(
@@ -82,7 +94,7 @@ ard_categorical.survey.design <- function(data,
   cards::process_formula_selectors(
     data = data$variables[variables],
     statistic = statistic,
-    fmt_fn = fmt_fn,
+    fmt_fun = fmt_fun,
     stat_label = stat_label
   )
   cards::fill_formula_selectors(
@@ -181,21 +193,21 @@ ard_categorical.survey.design <- function(data,
           ~ map(.x, as.character)
         )
       ) |>
-      dplyr::select(-c("stat_label", "fmt_fn", "warning", "error")) |>
+      dplyr::select(-c("stat_label", "fmt_fun", "warning", "error")) |>
       dplyr::mutate(
         stat_name =
           dplyr::case_match(.data$stat_name, "n" ~ "n_unweighted", "N" ~ "N_unweighted", "p" ~ "p_unweighted")
       )
     cards <- cards |> dplyr::bind_rows(cards_unweighted) # styler: off
   }
 
-  # final processing of fmt_fn -------------------------------------------------
+  # final processing of fmt_fun ------------------------------------------------
   cards <- cards |>
     .process_nested_list_as_df(
-      arg = fmt_fn,
-      new_column = "fmt_fn"
+      arg = fmt_fun,
+      new_column = "fmt_fun"
     ) |>
-    .default_svy_cat_fmt_fn()
+    .default_svy_cat_fmt_fun()
 
   # merge in statistic labels --------------------------------------------------
   cards <- cards |>
@@ -506,15 +518,15 @@ case_switch <- function(..., .default = NULL) {
   return(.default)
 }
 
-.default_svy_cat_fmt_fn <- function(x) {
+.default_svy_cat_fmt_fun <- function(x) {
   x |>
     dplyr::mutate(
-      fmt_fn =
+      fmt_fun =
         pmap(
-          list(.data$stat_name, .data$stat, .data$fmt_fn),
-          function(stat_name, stat, fmt_fn) {
-            if (!is_empty(fmt_fn)) {
-              return(fmt_fn)
+          list(.data$stat_name, .data$stat, .data$fmt_fun),
+          function(stat_name, stat, fmt_fun) {
+            if (!is_empty(fmt_fun)) {
+              return(fmt_fun)
             }
             if (stat_name %in% c("p", "p_miss", "p_nonmiss", "p_unweighted")) {
               return(cards::label_round(digits = 1, scale = 100))
@@ -556,7 +568,7 @@ case_switch <- function(..., .default = NULL) {
 #'
 #' cardx:::.process_nested_list_as_df(ard, NULL, "new_col")
 .process_nested_list_as_df <- function(x, arg, new_column, unlist = FALSE) {
-  # add fmt_fn column if not already present
+  # add column if not already present
   if (!new_column %in% names(x)) {
     x[[new_column]] <- list(NULL)
   }

R/ard_categorical_ci.survey.design.R

@@ -142,7 +142,7 @@ ard_categorical_ci.survey.design <- function(data,
     tidyr::unnest("result") |>
     dplyr::mutate(
       stat_label = .data$stat_name,
-      fmt_fn = map(.data$stat, ~ case_switch(is.numeric(.x) ~ 2L, .default = as.character))
+      fmt_fun = map(.data$stat, ~ case_switch(is.numeric(.x) ~ 2L, .default = as.character))
     ) |>
     cards::as_card() |>
     cards::tidy_ard_column_order() |>

R/ard_categorical_max.R

@@ -17,6 +17,7 @@
 #'   calculations. See [cards::ard_categorical()] for more details on specifying denominators.
 #' @param quiet (scalar `logical`)\cr
 #'   Logical indicating whether to suppress additional messaging. Default is `FALSE`.
+#' @param fmt_fn `r lifecycle::badge("deprecated")`
 #'
 #' @return an ARD data frame of class 'card'
 #' @name ard_categorical_max
@@ -28,7 +29,7 @@
 #'   variables = c(AESER, AESEV),
 #'   id = USUBJID,
 #'   by = TRTA,
-#'   denominator = cards::ADSL |> dplyr::rename(TRTA = ARM)
+#'   denominator = cards::ADSL
 #' )
 NULL
 
@@ -41,12 +42,23 @@ ard_categorical_max <- function(data,
                                 statistic = everything() ~ c("n", "p", "N"),
                                 denominator = NULL,
                                 strata = NULL,
-                                fmt_fn = NULL,
+                                fmt_fun = NULL,
                                 stat_label = everything() ~ cards::default_stat_labels(),
                                 quiet = FALSE,
+                                fmt_fn = deprecated(),
                                 ...) {
   set_cli_abort_call()
 
+  # deprecated args ------------------------------------------------------------
+  if (lifecycle::is_present(fmt_fn)) {
+    lifecycle::deprecate_soft(
+      when = "0.2.5",
+      what = "ard_categorical_max(fmt_fn)",
+      with = "ard_categorical_max(fmt_fun)"
+    )
+    fmt_fun <- fmt_fn
+  }
+
   # check inputs ---------------------------------------------------------------
   check_not_missing(data)
   check_not_missing(variables)
@@ -79,7 +91,7 @@ ard_categorical_max <- function(data,
         strata = all_of(strata),
         statistic = statistic,
         denominator = denominator,
-        fmt_fn = fmt_fn,
+        fmt_fun = fmt_fun,
         stat_label = stat_label
       )
     }

R/ard_continuous.survey.design.R

@@ -13,7 +13,7 @@
 #'   a named list, a list of formulas,
 #'   or a single formula where the list element is a character vector of
 #'   statistic names to include. See below for options.
-#' @param fmt_fn ([`formula-list-selector`][cards::syntax])\cr
+#' @param fmt_fun ([`formula-list-selector`][cards::syntax])\cr
 #'   a named list, a list of formulas,
 #'   or a single formula where the list element is a named list of functions
 #'   (or the RHS of a formula),
@@ -23,6 +23,7 @@
 #'   the list element is either a named list or a list of formulas defining the
 #'   statistic labels, e.g. `everything() ~ list(mean = "Mean", sd = "SD")` or
 #'   `everything() ~ list(mean ~ "Mean", sd ~ "SD")`.
+#' @inheritParams ard_categorical.survey.design
 #' @inheritParams rlang::args_dots_empty
 #'
 #' @section statistic argument:
@@ -46,12 +47,23 @@
 #' )
 ard_continuous.survey.design <- function(data, variables, by = NULL,
                                          statistic = everything() ~ c("median", "p25", "p75"),
-                                         fmt_fn = NULL,
+                                         fmt_fun = NULL,
                                          stat_label = NULL,
+                                         fmt_fn = deprecated(),
                                          ...) {
   set_cli_abort_call()
   check_dots_empty()
 
+  # deprecated args ------------------------------------------------------------
+  if (lifecycle::is_present(fmt_fn)) {
+    lifecycle::deprecate_soft(
+      when = "0.2.5",
+      what = "ard_continuous(fmt_fn)",
+      with = "ard_continuous(fmt_fun)"
+    )
+    fmt_fun <- fmt_fn
+  }
+
   # check installed packages ---------------------------------------------------
   check_pkg_installed(pkg = "survey")
 
@@ -66,7 +78,7 @@ ard_continuous.survey.design <- function(data, variables, by = NULL,
   cards::process_formula_selectors(
     data$variables[variables],
     statistic = statistic,
-    fmt_fn = fmt_fn,
+    fmt_fun = fmt_fun,
     stat_label = stat_label
   )
   cards::fill_formula_selectors(
@@ -128,17 +140,17 @@ ard_continuous.survey.design <- function(data, variables, by = NULL,
   }
 
   # add formatting stats -------------------------------------------------------
-  df_stats$fmt_fn <- list(1L)
-  if (!is_empty(fmt_fn)) {
+  df_stats$fmt_fun <- list(1L)
+  if (!is_empty(fmt_fun)) {
     df_stats <-
       dplyr::rows_update(
         df_stats,
         dplyr::tibble(
-          variable = names(fmt_fn),
-          stat_name = map(.data$variable, ~ names(fmt_fn[[.x]])),
-          fmt_fn = map(.data$variable, ~ fmt_fn[[.x]] |> unname())
+          variable = names(fmt_fun),
+          stat_name = map(.data$variable, ~ names(fmt_fun[[.x]])),
+          fmt_fun = map(.data$variable, ~ fmt_fun[[.x]] |> unname())
         ) |>
-          tidyr::unnest(cols = c("stat_name", "fmt_fn")),
+          tidyr::unnest(cols = c("stat_name", "fmt_fun")),
         by = c("variable", "stat_name"),
         unmatched = "ignore"
       )