Core function renames (#315)

**What changes are proposed in this pull request?**
* The following functions have been renamed.
    - `ard_continuous()` to `ard_summary()`
    - `ard_categorical()` to `ard_tabulate()`
    - `ard_dichotomous()` to `ard_tabulate_value()`
    - `ard_categorical_max()` to `ard_tabulate_max()`


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


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

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

@@ -22,7 +22,7 @@ BugReports: https://github.com/insightsengineering/cardx/issues
 Depends:
     R (>= 4.2)
 Imports:
-    cards (>= 0.6.1.9008),
+    cards (>= 0.6.1.9016),
     cli (>= 3.6.1),
     dplyr (>= 1.1.2),
     glue (>= 1.6.2),

NAMESPACE

@@ -15,8 +15,11 @@ S3method(ard_regression_basic,data.frame)
 S3method(ard_regression_basic,default)
 S3method(ard_stats_anova,anova)
 S3method(ard_stats_anova,data.frame)
+S3method(ard_summary,survey.design)
 S3method(ard_survival_survfit,data.frame)
 S3method(ard_survival_survfit,survfit)
+S3method(ard_tabulate,survey.design)
+S3method(ard_tabulate_value,survey.design)
 S3method(ard_total_n,survey.design)
 S3method(construct_model,data.frame)
 S3method(construct_model,survey.design)
@@ -28,7 +31,6 @@ export(ard_attributes)
 export(ard_car_anova)
 export(ard_car_vif)
 export(ard_categorical)
-export(ard_categorical_abnormal)
 export(ard_categorical_ci)
 export(ard_categorical_max)
 export(ard_continuous)
@@ -62,12 +64,17 @@ export(ard_stats_t_test)
 export(ard_stats_t_test_onesample)
 export(ard_stats_wilcox_test)
 export(ard_stats_wilcox_test_onesample)
+export(ard_summary)
 export(ard_survey_svychisq)
 export(ard_survey_svyranktest)
 export(ard_survey_svyttest)
 export(ard_survival_survdiff)
 export(ard_survival_survfit)
 export(ard_survival_survfit_diff)
+export(ard_tabulate)
+export(ard_tabulate_abnormal)
+export(ard_tabulate_max)
+export(ard_tabulate_value)
 export(ard_total_n)
 export(bt)
 export(bt_strip)
@@ -95,6 +102,9 @@ importFrom(cards,ard_categorical)
 importFrom(cards,ard_continuous)
 importFrom(cards,ard_dichotomous)
 importFrom(cards,ard_missing)
+importFrom(cards,ard_summary)
+importFrom(cards,ard_tabulate)
+importFrom(cards,ard_tabulate_value)
 importFrom(cards,ard_total_n)
 importFrom(dplyr,"%>%")
 importFrom(dplyr,across)

NEWS.md

@@ -1,8 +1,14 @@
 # cardx 0.2.5.9002
 
-* Added function `ard_categorical_abnormal()` to calculate ARDs for abnormality analyses. (#310)
+* The following functions have been renamed.
+    - `ard_continuous()` to `ard_summary()`
+    - `ard_categorical()` to `ard_tabulate()`
+    - `ard_dichotomous()` to `ard_tabulate_value()`
+    - `ard_categorical_max()` to `ard_tabulate_max()`
 
-* Adding `strata` argument to `ard_categorical_max()`. (#445, @jtalboys)
+* Added function `ard_tabulate_abnormal()` to calculate ARDs for abnormality analyses. (#310)
+
+* Adding `strata` argument to `ard_tabulate_max()`. (#445, @jtalboys)
 
 * Added function `ard_incidence_rate()` to calculate ARDs for incidence rate estimation. (#234)
 

R/add_total_n.survey.design.R

@@ -3,7 +3,7 @@
 #' Returns the total N for a survey object.
 #' The placeholder variable name returned in the object is `"..ard_total_n.."`
 #'
-#' @inheritParams ard_dichotomous.survey.design
+#' @inheritParams ard_tabulate_value.survey.design
 #' @inheritParams rlang::args_dots_empty
 #'
 #' @return an ARD data frame of class 'card'
@@ -22,7 +22,7 @@ ard_total_n.survey.design <- function(data, ...) {
   data <- stats::update(data, ..ard_total_n.. = TRUE)
 
   data |>
-    ard_dichotomous(
+    ard_tabulate_value(
       variables = "..ard_total_n..",
       statistic = list(..ard_total_n.. = c("N", "N_unweighted"))
     ) |>

R/ard_categorical_ci.R

@@ -2,7 +2,7 @@
 #'
 #' Calculate confidence intervals for proportions.
 #'
-#' @inheritParams cards::ard_categorical
+#' @inheritParams cards::ard_tabulate
 #' @param variables ([`tidy-select`][dplyr::dplyr_tidy_select])\cr
 #'   columns to include in summaries. Columns must be class `<logical>`
 #'   or `<numeric>` values coded as `c(0,1)`.
@@ -11,7 +11,7 @@
 #' @param denominator (`string`)\cr
 #'   Must be one of `'column'` (default), `'row'`, and `'cell'`, which specifies
 #'   the direction of the calculation/denominator. Argument is similar to
-#'   `cards::ard_categorical(denominator)`.
+#'   `cards::ard_tabulate(denominator)`.
 #' @param conf.level (scalar `numeric`)\cr
 #'   a scalar in `(0,1)` indicating the confidence level.
 #'   Default is `0.95`

R/ard_categorical_ci.survey.design.R

@@ -3,7 +3,7 @@
 #' Confidence intervals for categorical variables calculated via
 #' [`survey::svyciprop()`].
 #'
-#' @inheritParams ard_continuous.survey.design
+#' @inheritParams ard_summary.survey.design
 #' @inheritParams ard_categorical_ci.data.frame
 #' @param method (`string`)\cr
 #'   Method passed to `survey::svyciprop(method)`

R/ard_continuous.survey.design.R

@@ -23,7 +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 ard_tabulate.survey.design
 #' @inheritParams rlang::args_dots_empty
 #'
 #' @section statistic argument:
@@ -42,26 +42,26 @@
 #' data(api, package = "survey")
 #' dclus1 <- survey::svydesign(id = ~dnum, weights = ~pw, data = apiclus1, fpc = ~fpc)
 #'
-#' ard_continuous(
+#' ard_summary(
 #'   data = dclus1,
 #'   variables = api00,
 #'   by = stype
 #' )
-ard_continuous.survey.design <- function(data, variables, by = NULL,
-                                         statistic = everything() ~ c("median", "p25", "p75"),
-                                         fmt_fun = NULL,
-                                         stat_label = NULL,
-                                         fmt_fn = deprecated(),
-                                         ...) {
+ard_summary.survey.design <- function(data, variables, by = NULL,
+                                      statistic = everything() ~ c("median", "p25", "p75"),
+                                      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)"
+      what = "ard_summary(fmt_fn)",
+      with = "ard_summary(fmt_fun)"
     )
     fmt_fun <- fmt_fn
   }
@@ -85,7 +85,7 @@ ard_continuous.survey.design <- function(data, variables, by = NULL,
   )
   cards::fill_formula_selectors(
     data$variables[variables],
-    statistic = formals(asNamespace("cardx")[["ard_continuous.survey.design"]])[["statistic"]] |> eval()
+    statistic = formals(asNamespace("cardx")[["ard_summary.survey.design"]])[["statistic"]] |> eval()
   )
   cards::check_list_elements(
     x = statistic,

R/ard_continuous_ci.survey.design.R

@@ -4,7 +4,7 @@
 #' Confidence limits are calculated with `survey::svymean()` and `survey::svyquantile()`.
 #'
 #'
-#' @inheritParams ard_continuous.survey.design
+#' @inheritParams ard_summary.survey.design
 #' @param method (`string`)\cr
 #'   Method for confidence interval calculation.
 #'   When `"svymean"`, the calculation is computed via `survey::svymean()`.

R/ard_incidence_rate.R

@@ -29,7 +29,7 @@
 #'   confidence interval type for the estimated incidence rate.
 #'
 #'   One of: `normal` (default), `normal-log`, `exact`, or `byar`.
-#' @inheritParams cards::ard_continuous
+#' @inheritParams cards::ard_summary
 #'
 #' @return an ARD data frame of class 'card'
 #' @export

R/ard_missing.survey.design.R

@@ -2,7 +2,7 @@
 #'
 #' Compute Analysis Results Data (ARD) for statistics related to data missingness for survey objects
 #'
-#' @inheritParams ard_categorical.survey.design
+#' @inheritParams ard_tabulate.survey.design
 #'
 #' @return an ARD data frame of class 'card'
 #' @export
@@ -95,7 +95,7 @@ ard_missing.survey.design <- function(data,
 
   # calculate results ----------------------------------------------------------
   result <-
-    ard_categorical(
+    ard_tabulate(
       data = data,
       variables = all_of(paste0("lgl_", variables)),
       by = any_of(by),