Updating CI functions (#181)

**What changes are proposed in this pull request?**
* Style this entry in a way that can be copied directly into `NEWS.md`.
(#<issue number>, @<username>)

Provide more detail here as needed.

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



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

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", 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"))`
- [ ] 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

NAMESPACE

@@ -2,7 +2,11 @@
 
 S3method(ard_attributes,survey.design)
 S3method(ard_categorical,survey.design)
+S3method(ard_categorical_ci,data.frame)
+S3method(ard_categorical_ci,survey.design)
 S3method(ard_continuous,survey.design)
+S3method(ard_continuous_ci,data.frame)
+S3method(ard_continuous_ci,survey.design)
 S3method(ard_dichotomous,survey.design)
 S3method(ard_missing,survey.design)
 S3method(ard_regression,default)
@@ -18,15 +22,16 @@ export(ard_attributes)
 export(ard_car_anova)
 export(ard_car_vif)
 export(ard_categorical)
+export(ard_categorical_ci)
 export(ard_continuous)
+export(ard_continuous_ci)
 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)
 export(ard_smd_smd)
@@ -46,8 +51,6 @@ export(ard_stats_t_test)
 export(ard_stats_t_test_onesample)
 export(ard_stats_wilcox_test)
 export(ard_stats_wilcox_test_onesample)
-export(ard_survey_categorical_ci)
-export(ard_survey_continuous_ci)
 export(ard_survey_svychisq)
 export(ard_survey_svyranktest)
 export(ard_survey_svyttest)

NEWS.md

@@ -18,7 +18,7 @@ ard_moodtest()          -> ard_stats_mood_test()
 
 ### New Features
 
-* The `ard_proportion_ci(value)` argument has been added. Previously, only binary variables (0/1 or TRUE/FALSE) could be summarized. When a value is not supplied, each level of the variable is summarized independently. By default, binary variables will have the 1/TRUE level summarized.
+* The `ard_categorical_ci(value)` argument has been added. Previously, only binary variables (0/1 or TRUE/FALSE) could be summarized. When a value is not supplied, each level of the variable is summarized independently. By default, binary variables will have the 1/TRUE level summarized.
 
 * Added the following functions for calculating Analysis Results Data (ARD).
   - `ard_stats_aov()` for calculating ANOVA results using `stats::aov()`. (#3)

R/ard_proportion_ci.R R/ard_categorical_ci.RR/ard_proportion_ci.R renamed to R/ard_categorical_ci.R

@@ -14,7 +14,7 @@
 #'   Default is `0.95`
 #' @param method (`string`)\cr
 #'   string indicating the type of confidence interval to calculate.
-#'   Must be one of `r formals(ard_proportion_ci)[["method"]] |> eval() |> shQuote("sh")`.
+#'   Must be one of `r formals(ard_categorical_ci)[["method"]] |> eval() |> shQuote("sh")`.
 #'   See `?proportion_ci` for details.
 #' @param strata,weights,max.iterations arguments passed to `proportion_ci_strat_wilson()`,
 #'   when `method='strat_wilson'`
@@ -25,29 +25,42 @@
 #'   columns coded as `0`/`1` and `TRUE`/`FALSE` will summarize the `1` and `TRUE` levels.
 #'
 #' @return an ARD data frame
-#' @export
+#' @name ard_categorical_ci
 #'
 #' @examplesIf do.call(asNamespace("cardx")$is_pkg_installed, list(pkg = "broom", reference_pkg = "cardx"))
 #' # compute CI for binary variables
-#' ard_proportion_ci(mtcars, variables = c(vs, am), method = "wilson")
+#' ard_categorical_ci(mtcars, variables = c(vs, am), method = "wilson")
 #'
 #' # compute CIs for each level of a categorical variable
-#' ard_proportion_ci(mtcars, variables = cyl, method = "jeffreys")
-ard_proportion_ci <- function(data,
-                              variables,
-                              by = dplyr::group_vars(data),
-                              method = c(
-                                "waldcc", "wald", "clopper-pearson",
-                                "wilson", "wilsoncc",
-                                "strat_wilson", "strat_wilsoncc",
-                                "agresti-coull", "jeffreys"
-                              ),
-                              conf.level = 0.95,
-                              value = list(where(is_binary) ~ 1L, where(is.logical) ~ TRUE),
-                              strata = NULL,
-                              weights = NULL,
-                              max.iterations = 10) {
+#' ard_categorical_ci(mtcars, variables = cyl, method = "jeffreys")
+NULL
+
+#' @rdname ard_categorical_ci
+#' @export
+ard_categorical_ci <- function(data, ...) {
+  check_not_missing(data)
+  UseMethod("ard_categorical_ci")
+}
+
+#' @rdname ard_categorical_ci
+#' @export
+ard_categorical_ci.data.frame <- function(data,
+                                          variables,
+                                          by = dplyr::group_vars(data),
+                                          method = c(
+                                            "waldcc", "wald", "clopper-pearson",
+                                            "wilson", "wilsoncc",
+                                            "strat_wilson", "strat_wilsoncc",
+                                            "agresti-coull", "jeffreys"
+                                          ),
+                                          conf.level = 0.95,
+                                          value = list(where(is_binary) ~ 1L, where(is.logical) ~ TRUE),
+                                          strata = NULL,
+                                          weights = NULL,
+                                          max.iterations = 10,
+                                          ...) {
   set_cli_abort_call()
+  check_dots_empty()
 
   # check installed packages ---------------------------------------------------
   check_pkg_installed(pkg = "broom", reference_pkg = "cardx")
@@ -137,8 +150,8 @@ ard_proportion_ci <- function(data,
   unique_levels <-
     # styler: off
     if (is.logical(data[[variable]])) c(TRUE, FALSE)
-    else if (is.factor(data[[variable]])) factor(levels(data[[variable]]), levels = levels(data[[variable]]))
-    else unique(data[[variable]]) |> sort()
+  else if (is.factor(data[[variable]])) factor(levels(data[[variable]]), levels = levels(data[[variable]]))
+  else unique(data[[variable]]) |> sort()
   # styler: on
 
   if (!is_empty(value) && !value %in% unique_levels) {

R/ard_survey_categorical_ci.R R/ard_categorical_ci.survey.design.RR/ard_survey_categorical_ci.R renamed to R/ard_categorical_ci.survey.design.R

@@ -4,10 +4,9 @@
 #' [`survey::svyciprop()`].
 #'
 #' @inheritParams ard_continuous.survey.design
+#' @inheritParams ard_categorical_ci.data.frame
 #' @param method (`string`)\cr
 #'   Method passed to `survey::svyciprop(method)`
-#' @param conf.level (scalar `numeric`)\cr
-#'   confidence level for confidence interval. Default is `0.95`.
 #' @param df (`numeric`)\cr
 #'   denominator degrees of freedom, passed to `survey::svyciprop(df)`.
 #'   Default is `survey::degf(data)`.
@@ -20,16 +19,18 @@
 #' data(api, package = "survey")
 #' dclus1 <- survey::svydesign(id = ~dnum, weights = ~pw, data = apiclus1, fpc = ~fpc)
 #'
-#' ard_survey_categorical_ci(dclus1, variables = sch.wide)
-#' ard_survey_categorical_ci(dclus1, variables = sch.wide, method = "xlogit")
-ard_survey_categorical_ci <- function(data,
-                                      variables,
-                                      by = NULL,
-                                      method = c("logit", "likelihood", "asin", "beta", "mean", "xlogit"),
-                                      conf.level = 0.95,
-                                      df = survey::degf(data),
-                                      ...) {
+#' ard_categorical_ci(dclus1, variables = sch.wide)
+#' ard_categorical_ci(dclus1, variables = sch.wide, value = sch.wide ~ "Yes", method = "xlogit")
+ard_categorical_ci.survey.design <- function(data,
+                                             variables,
+                                             by = NULL,
+                                             method = c("logit", "likelihood", "asin", "beta", "mean", "xlogit"),
+                                             conf.level = 0.95,
+                                             value = list(where(is_binary) ~ 1L, where(is.logical) ~ TRUE),
+                                             df = survey::degf(data),
+                                             ...) {
   set_cli_abort_call()
+  check_dots_empty()
 
   # check inputs ---------------------------------------------------------------
   check_not_missing(data)
@@ -41,6 +42,10 @@ ard_survey_categorical_ci <- function(data,
     variables = {{ variables }},
     by = {{ by }}
   )
+  cards::process_formula_selectors(
+    data = data$variables,
+    value = value
+  )
   check_scalar(by, allow_empty = TRUE)
   check_scalar_range(conf.level, range = c(0, 1))
   method <- arg_match(method)
@@ -54,11 +59,12 @@ ard_survey_categorical_ci <- function(data,
     conf.level = conf.level,
     method = method,
     df = df,
+    value = value,
     ...
   )
 }
 
-.calculate_ard_onesample_survey_ci <- function(FUN, data, variables, by, conf.level, ...) {
+.calculate_ard_onesample_survey_ci <- function(FUN, data, variables, by, conf.level, value, ...) {
   # return empty data frame if no variables to process -------------------------
   if (is_empty(variables)) return(dplyr::tibble()) # styler: off
 
@@ -72,14 +78,15 @@ ard_survey_categorical_ci <- function(data,
         variable = variable,
         by = by,
         conf.level = conf.level,
+        value = value[[variable]],
         ...
       )
     }
   ) |>
     dplyr::bind_rows()
 }
 
-.calculate_one_ard_categorical_survey_ci <- function(FUN, data, variable, by, conf.level, ...) {
+.calculate_one_ard_categorical_survey_ci <- function(FUN, data, variable, by, conf.level, value, ...) {
   variable_levels <- .unique_values_sort(data$variables, variable = variable)
   if (!is_empty(by)) {
     by_levels <- .unique_values_sort(data$variables, variable = by)
@@ -126,7 +133,7 @@ ard_survey_categorical_ci <- function(data,
           list(),
       warning = .data$lst_result["warning"] |> unname(),
       error = .data$lst_result["error"] |> unname(),
-      context = "survey_categorical_ci"
+      context = "categorical_ci"
     ) |>
     dplyr::select(-"lst_result") |>
     dplyr::ungroup() |>
@@ -137,6 +144,14 @@ ard_survey_categorical_ci <- function(data,
     ) |>
     cards::tidy_ard_column_order() %>%
     structure(., class = c("card", class(.)))
+
+  # if a value was passed for the variable, subset on those results
+  if (!is_empty(value)) {
+    df_full <- df_full |>
+      dplyr::filter(.data$variable_level %in% .env$value)
+  }
+
+  df_full
 }
 
 

R/ard_continuous_ci.R

@@ -0,0 +1,55 @@
+#' ARD continuous CIs
+#'
+#' One-sample confidence intervals for continuous variable means and medians.
+#'
+#' @inheritParams ard_stats_t_test
+#' @param method (`string`)\cr
+#'   a string indicating the method to use for the confidence interval
+#'   calculation. Must be one of `"t.test"` or `"wilcox.test"`
+#' @param ... arguments passed to `t.test()` or `wilcox.test()`
+#'
+#' @return ARD data frame
+#' @name ard_continuous_ci
+#'
+#' @examples
+#' ard_continuous_ci(mtcars, variables = c(mpg, hp), method = "wilcox.test")
+#' ard_continuous_ci(mtcars, variables = mpg, by = am, method = "t.test")
+NULL
+
+#' @rdname ard_continuous_ci
+#' @export
+ard_continuous_ci <- function(data, ...) {
+  check_not_missing(data)
+  UseMethod("ard_continuous_ci")
+}
+
+#' @rdname ard_continuous_ci
+#' @export
+ard_continuous_ci.data.frame <- function(data, variables, by = dplyr::group_vars(data), conf.level = 0.95, method = c("t.test", "wilcox.test"), ...) {
+  set_cli_abort_call()
+
+  # check inputs ---------------------------------------------------------------
+  method <- arg_match(method)
+
+  # calculate CIs --------------------------------------------------------------
+  switch(method,
+    "t.test" =
+      ard_stats_t_test_onesample(
+        data = data,
+        variables = {{ variables }},
+        by = {{ by }},
+        conf.level = conf.level,
+        ...
+      ),
+    "wilcox.test" =
+      ard_stats_wilcox_test_onesample(
+        data = data,
+        variables = {{ variables }},
+        by = {{ by }},
+        conf.level = conf.level,
+        conf.int = TRUE,
+        ...
+      )
+  ) |>
+    dplyr::mutate(context = "continuous_ci")
+}

R/ard_survey_continuous_ci.R R/ard_continuous_ci.survey.design.RR/ard_survey_continuous_ci.R renamed to R/ard_continuous_ci.survey.design.R

@@ -1,4 +1,4 @@
-#' ARD survey categorical CIs
+#' ARD survey continuous CIs
 #'
 #' One-sample confidence intervals for continuous variables' means and medians.
 #' Confidence limits are calculated with `survey::svymean()` and `survey::svyquantile()`.
@@ -23,15 +23,15 @@
 #' data(api, package = "survey")
 #' dclus1 <- survey::svydesign(id = ~dnum, weights = ~pw, data = apiclus1, fpc = ~fpc)
 #'
-#' ard_survey_continuous_ci(dclus1, variables = api00)
-#' ard_survey_continuous_ci(dclus1, variables = api00, method = "xlogit")
-ard_survey_continuous_ci <- function(data,
-                                     variables,
-                                     by = NULL,
-                                     method = c("svymean", "mean", "beta", "xlogit", "asin", "score"),
-                                     conf.level = 0.95,
-                                     df = survey::degf(data),
-                                     ...) {
+#' ard_continuous_ci(dclus1, variables = api00)
+#' ard_continuous_ci(dclus1, variables = api00, method = "svymedian.xlogit")
+ard_continuous_ci.survey.design <- function(data,
+                                            variables,
+                                            by = NULL,
+                                            method = c("svymean", "svymedian.mean", "svymedian.beta", "svymedian.xlogit", "svymedian.asin", "svymedian.score"),
+                                            conf.level = 0.95,
+                                            df = survey::degf(data),
+                                            ...) {
   set_cli_abort_call()
 
   # check inputs ---------------------------------------------------------------
@@ -183,7 +183,7 @@ ard_survey_continuous_ci <- function(data,
       svyquantile <-
         survey::svyquantile(
           x = reformulate2(variable), design = data, quantiles = 0.5,
-          na.rm = TRUE, interval.type = method
+          na.rm = TRUE, interval.type = str_remove(method, pattern = "^svymedian\\.")
         )
 
       lst_svyquantile <- svyquantile |>

R/ard_stats_t_test.R

@@ -14,7 +14,7 @@
 #'   column name of the subject or participant ID
 #' @param conf.level (scalar `numeric`)\cr
 #'   confidence level for confidence interval. Default is `0.95`.
-#' @param ... arguments passed to `t.test(...)`
+#' @param ... arguments passed to `t.test()`
 #'
 #' @return ARD data frame
 #' @name ard_stats_t_test

R/ard_stats_wilcox_test_onesample.R

@@ -42,7 +42,7 @@ ard_stats_wilcox_test_onesample <- function(data, variables, by = dplyr::group_v
     data = data,
     variables = all_of(variables),
     by = all_of(by),
-    statistic = all_of(variables) ~ list(t_test_onesample = \(x) stats::wilcox.test(x = x, conf.level = conf.level, ...) |> broom::tidy())
+    statistic = all_of(variables) ~ list(wilcox_test_onesample = \(x) stats::wilcox.test(x = x, conf.level = conf.level, ...) |> broom::tidy())
   ) |>
     cards::bind_ard(
       cards::ard_continuous(

R/proportion_ci.R

@@ -2,7 +2,7 @@
 #'
 #' Functions to calculate different proportion confidence intervals for use in `ard_proportion()`.
 #'
-#' @inheritParams ard_proportion_ci
+#' @inheritParams ard_categorical_ci
 #' @param x vector of a binary values, i.e. a logical vector, or numeric with values `c(0, 1)`
 #' @return Confidence interval of a proportion.
 #'

_pkgdown.yml

@@ -67,8 +67,8 @@ reference:
       - ard_dichotomous.survey.design
       - ard_missing.survey.design
       - ard_attributes.survey.design
-      - ard_survey_continuous_ci
-      - ard_survey_categorical_ci
+      - ard_continuous_ci.survey.design
+      - ard_categorical_ci.survey.design
       - ard_survey_svychisq
       - ard_survey_svyranktest
       - ard_survey_svyttest
@@ -81,7 +81,8 @@ reference:
 
   - subtitle: "Other ARD functions"
   - contents:
-      - ard_proportion_ci
+      - ard_continuous_ci.data.frame
+      - ard_categorical_ci.data.frame
       - ard_regression
       - ard_regression_basic