Making ard_survey_svycontinuous() a S3 method (#150)

**What changes are proposed in this pull request?**
Converted `ard_survey_svycontinuous()` to a S3 method
`ard_continuous.survey.design()`.



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

Pre-review Checklist (if item does not apply, mark is as complete)
- [x] **All** GitHub Action workflows pass with a ✅
- [x] PR branch has pulled the most recent updates from master branch:
`usethis::pr_merge_main()`
- [x] If a bug was fixed, a unit test was added.
- [x] If a new `ard_*()` function was added, it passes the ARD
structural checks from `cards::check_ard_structure()`.
- [x] If a new `ard_*()` function was added, `set_cli_abort_call()` has
been set.
- [x] If a new `ard_*()` function was added and it depends on another
package (such as, `broom`), `is_pkg_installed("broom", reference_pkg =
"cardx")` 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"",
reference_pkg = "cardx"))`
- [x] 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".

DESCRIPTION

@@ -18,7 +18,7 @@ BugReports: https://github.com/insightsengineering/cardx/issues
 Depends:
     R (>= 4.1)
 Imports:
-    cards (>= 0.1.0.9014),
+    cards (>= 0.1.0.9026),
     cli (>= 3.6.1),
     dplyr (>= 1.1.2),
     glue (>= 1.6.2),
@@ -33,13 +33,13 @@ Suggests:
     effectsize (>= 0.6.0),
     emmeans (>= 1.7.3),
     geepack (>= 1.3.2),
-    ggsurvfit (>= 1.0.0),
+    ggsurvfit (>= 1.1.0),
     lme4 (>= 1.1-31),
     parameters (>= 0.20.2),
     smd (>= 0.6.6),
     spelling,
     survey (>= 4.1),
-    survival (>= 3.2-11),
+    survival (>= 3.6-4),
     testthat (>= 3.2.0),
     withr (>= 2.5.0)
 Remotes: 

NAMESPACE

@@ -1,5 +1,7 @@
 # Generated by roxygen2: do not edit by hand
 
+S3method(ard_attributes,survey.design)
+S3method(ard_continuous,survey.design)
 S3method(ard_regression,default)
 S3method(ard_stats_anova,anova)
 S3method(ard_stats_anova,data.frame)
@@ -9,13 +11,18 @@ export("%>%")
 export(all_of)
 export(any_of)
 export(ard_aod_wald_test)
+export(ard_attributes)
 export(ard_car_anova)
 export(ard_car_vif)
+export(ard_categorical)
+export(ard_continuous)
+export(ard_dichotomous)
 export(ard_effectsize_cohens_d)
 export(ard_effectsize_hedges_g)
 export(ard_effectsize_paired_cohens_d)
 export(ard_effectsize_paired_hedges_g)
 export(ard_emmeans_mean_difference)
+export(ard_missing)
 export(ard_proportion_ci)
 export(ard_regression)
 export(ard_regression_basic)
@@ -35,7 +42,6 @@ export(ard_stats_prop_test)
 export(ard_stats_t_test)
 export(ard_stats_wilcox_test)
 export(ard_survey_svychisq)
-export(ard_survey_svycontinuous)
 export(ard_survey_svyranktest)
 export(ard_survey_svyttest)
 export(ard_survival_survdiff)
@@ -60,6 +66,11 @@ export(reformulate2)
 export(starts_with)
 export(where)
 import(rlang)
+importFrom(cards,ard_attributes)
+importFrom(cards,ard_categorical)
+importFrom(cards,ard_continuous)
+importFrom(cards,ard_dichotomous)
+importFrom(cards,ard_missing)
 importFrom(dplyr,"%>%")
 importFrom(dplyr,across)
 importFrom(dplyr,all_of)

NEWS.md

@@ -30,7 +30,8 @@ ard_moodtest()          -> ard_stats_mood_test()
   - `ard_regression_basic()` for basic regression models. The function focuses on matching terms to underlying variables names. (#46)
   - `ard_smd_smd()` for calculating standardized mean differences using `smd::smd()`. (#4)
   - `ard_survival_survfit()` for survival analyses using `survival::survfit()`. (#43)
-  - `ard_survey_svycontinuous()` for calculating univariate summary statistics from weighted/survey data using many functions from the {survey} package. (#68)
+  - `ard_continuous.survey.design()` for calculating univariate summary statistics from weighted/survey data using many functions from the {survey} package. (#68)
+  - `ard_attributes.survey.design()` for summarizing labels and attributes from weighted/survey data using many functions from the {survey} package.
   - `ard_survey_svychisq()` for weighted/survey chi-squared test using `survey::svychisq()`. (#72)
   - `ard_survey_svyttest()` for weighted/survey t-tests using `survey::svyttest()`. (#70)
   - `ard_survey_svyranktest()` for weighted/survey rank tests using `survey::svyranktest()`. (#71)

R/ard_attributes.survey.design.R

@@ -0,0 +1,37 @@
+#' ARD Attributes
+#'
+#' @description
+#' Add variable attributes to an ARD data frame.
+#' - The `label` attribute will be added for all columns, and when no label
+#'   is specified and no label has been set for a column using the `label=` argument,
+#'   the column name will be placed in the label statistic.
+#' - The `class` attribute will also be returned for all columns.
+#' - Any other attribute returned by `attributes()` will also be added, e.g. factor levels.
+#'
+#' @rdname ard_attributes
+#' @param data (`survey.design`)\cr
+#'   a design object often created with [`survey::svydesign()`].
+#' @param variables ([`tidy-select`][dplyr::dplyr_tidy_select])\cr
+#'   variables to include
+#' @param label (named `list`)\cr
+#'   named list of variable labels, e.g. `list(cyl = "No. Cylinders")`.
+#'   Default is `NULL`
+#' @inheritParams rlang::args_dots_empty
+#'
+#' @return an ARD data frame of class 'card'
+#' @export
+#'
+#' @examplesIf do.call(asNamespace("cardx")$is_pkg_installed, list(pkg = "survey", reference_pkg = "cardx"))
+#' data(api, package = "survey")
+#' dclus1 <- survey::svydesign(id = ~dnum, weights = ~pw, data = apiclus1, fpc = ~fpc)
+#'
+#' ard_attributes(
+#'   data = dclus1,
+#'   variables = c(sname, dname),
+#'   label = list(sname = "School Name", dname = "District Name")
+#' )
+ard_attributes.survey.design <- function(data, variables = everything(), label = NULL, ...) {
+  set_cli_abort_call()
+
+  cards::ard_attributes(data = data[["variables"]], variables = {{ variables }}, label = label, ...)
+}

R/ard_survey_svycontinuous.R → R/ard_continuous.survey.design.R

@@ -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 rlang::args_dots_empty
 #'
 #' @section statistic argument:
 #'
@@ -38,16 +39,18 @@
 #' data(api, package = "survey")
 #' dclus1 <- survey::svydesign(id = ~dnum, weights = ~pw, data = apiclus1, fpc = ~fpc)
 #'
-#' ard_survey_svycontinuous(
+#' ard_continuous(
 #'   data = dclus1,
 #'   variables = api00,
 #'   by = stype
 #' )
-ard_survey_svycontinuous <- function(data, variables, by = NULL,
-                                     statistic = everything() ~ c("median", "p25", "p75"),
-                                     fmt_fn = NULL,
-                                     stat_label = NULL) {
+ard_continuous.survey.design <- function(data, variables, by = NULL,
+                                         statistic = everything() ~ c("median", "p25", "p75"),
+                                         fmt_fn = NULL,
+                                         stat_label = NULL,
+                                         ...) {
   set_cli_abort_call()
+  check_dots_empty()
 
   # check installed packages ---------------------------------------------------
   check_pkg_installed(pkg = "survey", reference_pkg = "cardx")
@@ -68,7 +71,7 @@ ard_survey_svycontinuous <- function(data, variables, by = NULL,
   )
   cards::fill_formula_selectors(
     data$variables[variables],
-    statistic = formals(ard_survey_svycontinuous)[["statistic"]] |> eval()
+    statistic = formals(asNamespace("cardx")[["ard_continuous.survey.design"]])[["statistic"]] |> eval()
   )
   cards::check_list_elements(
     x = statistic,

R/reexports.R

@@ -1,3 +1,24 @@
+# cards ------------------------------------------------------------------------
+#' @importFrom cards ard_continuous
+#' @export
+cards::ard_continuous
+
+#' @importFrom cards ard_categorical
+#' @export
+cards::ard_categorical
+
+#' @importFrom cards ard_dichotomous
+#' @export
+cards::ard_dichotomous
+
+#' @importFrom cards ard_missing
+#' @export
+cards::ard_missing
+
+#' @importFrom cards ard_attributes
+#' @export
+cards::ard_attributes
+
 # dplyr ------------------------------------------------------------------------
 #' @export
 #' @importFrom dplyr %>%

_pkgdown.yml

@@ -60,8 +60,9 @@ reference:
 
   - subtitle: "{survey} package"
   - contents:
+      - ard_continuous.survey.design
+      - ard_attributes.survey.design
       - ard_survey_svychisq
-      - ard_survey_svycontinuous
       - ard_survey_svyranktest
       - ard_survey_svyttest
 

tests/testthat/_snaps/ard_survey_svycontinuous.md → tests/testthat/_snaps/ard_continuous.survey.design.md

@@ -1,4 +1,4 @@
-# unstratified ard_survey_svycontinuous() works
+# unstratified ard_continuous.survey.design() works
 
     Code
       ard_uni_svy_cont
@@ -19,12 +19,11 @@
     Message
       i 2 more variables: warning, error
 
-# ard_survey_svycontinuous(fmt_fn)
+# ard_continuous.survey.design(fmt_fn)
 
     Code
-      ard_survey_svycontinuous(dclus1, variables = api00, statistic = ~ c("mean",
-        "median", "min", "max"), fmt_fn = list(api00 = list(mean = 2, median = "xx.xx",
-        min = as.character)))
+      ard_continuous(dclus1, variables = api00, statistic = ~ c("mean", "median",
+        "min", "max"), fmt_fn = list(api00 = list(mean = 2, median = "xx.xx", min = as.character)))
     Message
       {cards} data frame: 4 x 8
     Output
@@ -36,12 +35,12 @@
     Message
       i 2 more variables: warning, error
 
-# ard_survey_svycontinuous(stat_label)
+# ard_continuous.survey.design(stat_label)
 
     Code
-      ard_survey_svycontinuous(dclus1, variables = api00, statistic = ~ c("mean",
-        "median", "min", "max"), stat_label = list(api00 = list(mean = "MeAn",
-        median = "MEDian", min = "MINimum")))
+      ard_continuous(dclus1, variables = api00, statistic = ~ c("mean", "median",
+        "min", "max"), stat_label = list(api00 = list(mean = "MeAn", median = "MEDian",
+        min = "MINimum")))
     Message
       {cards} data frame: 4 x 8
     Output

tests/testthat/test-ard_attributes.survey.design.R

@@ -0,0 +1,17 @@
+skip_if_not(is_pkg_installed("survey", reference_pkg = "cardx"))
+
+test_that("ard_attributes.survey.design() works", {
+  data(api, package = "survey")
+  dclus1 <- survey::svydesign(id = ~dnum, weights = ~pw, data = apiclus1, fpc = ~fpc)
+
+  expect_snapshot({
+    attr(dclus1$variables$sname, "label") <- "School Name"
+
+    ard_attributes(
+      dclus1,
+      variables = c(sname, dname),
+      label = list(dname = "District Name")
+    ) |>
+      as.data.frame()
+  })
+})