Title:	Extra Analysis Results Data Utilities
Version:	0.2.5
Description:	Create extra Analysis Results Data (ARD) summary objects. The package supplements the simple ARD functions from the 'cards' package, exporting functions to put statistical results in the ARD format. These objects are used and re-used to construct summary tables, visualizations, and written reports.
License:	Apache License 2.0
URL:	https://github.com/insightsengineering/cardx, https://insightsengineering.github.io/cardx/
BugReports:	https://github.com/insightsengineering/cardx/issues
Depends:	R (≥ 4.2)
Imports:	cards (≥ 0.6.1), cli (≥ 3.6.1), dplyr (≥ 1.1.2), glue (≥ 1.6.2), lifecycle (≥ 1.0.3), rlang (≥ 1.1.1), tidyr (≥ 1.3.0)
Suggests:	aod (≥ 1.3.3), broom (≥ 1.0.8), broom.helpers (≥ 1.17.0), broom.mixed (≥ 0.2.9), car (≥ 3.1-2), effectsize (≥ 0.8.8), emmeans (≥ 1.7.3), geepack (≥ 1.3.2), ggsurvfit (≥ 1.1.0), lme4 (≥ 1.1-37), parameters (≥ 0.20.2), smd (≥ 0.6.6), survey (≥ 4.2), survival (≥ 3.6-4), testthat (≥ 3.2.0), withr (≥ 2.5.0)
Config/Needs/website:	insightsengineering/nesttemplate
Config/testthat/edition:	3
Config/testthat/parallel:	true
Encoding:	UTF-8
Language:	en-US
RoxygenNote:	7.3.2
NeedsCompilation:	no
Packaged:	2025-07-03 14:28:25 UTC; sjobergd
Author:	Daniel D. Sjoberg [aut, cre], Abinaya Yogasekaram [aut], Emily de la Rua [aut], F. Hoffmann-La Roche AG [cph, fnd]
Maintainer:	Daniel D. Sjoberg <danield.sjoberg@gmail.com>
Repository:	CRAN
Date/Publication:	2025-07-03 14:50:02 UTC

cardx: Extra Analysis Results Data Utilities

Description

Create extra Analysis Results Data (ARD) summary objects. The package supplements the simple ARD functions from the 'cards' package, exporting functions to put statistical results in the ARD format. These objects are used and re-used to construct summary tables, visualizations, and written reports.

Author(s)

Maintainer: Daniel D. Sjoberg danield.sjoberg@gmail.com (ORCID)

Authors:

• Abinaya Yogasekaram abinaya.yogasekaram@contractors.roche.com

• Emily de la Rua emily.de_la_rua@contractors.roche.com

Other contributors:

• F. Hoffmann-La Roche AG [copyright holder, funder]

See Also

Useful links:

• https://github.com/insightsengineering/cardx

• https://insightsengineering.github.io/cardx/

• Report bugs at https://github.com/insightsengineering/cardx/issues

Perform Value Checks

Description

Check the validity of the values passed in ard_dichotomous(value).

Usage

.check_dichotomous_value(data, value)

Arguments

Value

returns invisible if check is successful, throws an error message if not.

Examples

cardx:::.check_dichotomous_value(mtcars, list(cyl = 4))

Extract data from wald.test object

Description

Extract data from wald.test object

Usage

.extract_wald_results(wald_test)

Arguments

Value

a data frame containing the wald test results.

Convert Cohen's D Test to ARD

Description

Convert Cohen's D Test to ARD

Usage

.format_cohens_d_results(by, variable, lst_tidy, paired, ...)

Arguments

Value

ARD data frame

Examples

cardx:::.format_cohens_d_results(
  by = "ARM",
  variable = "AGE",
  paired = FALSE,
  lst_tidy =
    cards::eval_capture_conditions(
      effectsize::hedges_g(data[[variable]] ~ data[[by]], paired = FALSE) |>
        parameters::standardize_names(style = "broom")
    )
)

Convert Hedge's G Test to ARD

Description

Convert Hedge's G Test to ARD

Usage

.format_hedges_g_results(by, variable, lst_tidy, paired, ...)

Arguments

Value

ARD data frame

Examples

cardx:::.format_hedges_g_results(
  by = "ARM",
  variable = "AGE",
  paired = FALSE,
  lst_tidy =
    cards::eval_capture_conditions(
      effectsize::hedges_g(data[[variable]] ~ data[[by]], paired = FALSE) |>
        parameters::standardize_names(style = "broom")
    )
)

Convert McNemar's test to ARD

Description

Convert McNemar's test to ARD

Usage

.format_mcnemartest_results(by, variable, lst_tidy, ...)

Arguments

Value

ARD data frame

Examples

cardx:::.format_mcnemartest_results(
  by = "ARM",
  variable = "AGE",
  lst_tidy =
    cards::eval_capture_conditions(
      stats::mcnemar.test(cards::ADSL[["SEX"]], cards::ADSL[["EFFFL"]]) |>
        broom::tidy()
    )
)

Convert mood test results to ARD

Description

Convert mood test results to ARD

Usage

.format_moodtest_results(by, variable, lst_tidy, ...)

Arguments

Value

ARD data frame

Examples

cardx:::.format_moodtest_results(
  by = "SEX",
  variable = "AGE",
  lst_tidy =
    cards::eval_capture_conditions(
      stats::mood.test(ADSL[["AGE"]] ~ ADSL[["SEX"]]) |>
        broom::tidy()
    )
)

Convert Poisson test to ARD

Description

Convert Poisson test to ARD

Usage

.format_poissontest_results(by = NULL, variables, lst_tidy, ...)

Arguments

Value

ARD data frame

Examples

cardx:::.format_poissontest_results(
  by = "ARM",
  variables = c("CNSR", "AVAL"),
  lst_tidy =
    cards::eval_capture_conditions(
      stats::poisson.test(sum(cards::ADTTE[["CNSR"]]), sum(cards::ADTTE[["AVAL"]])) |>
        broom::tidy()
    )
)

Convert prop.test to ARD

Description

Convert prop.test to ARD

Usage

.format_proptest_results(by, variable, lst_tidy, ...)

Arguments

Value

ARD data frame

Convert Tidied Survival Fit to ARD

Description

Convert Tidied Survival Fit to ARD

Usage

.format_survfit_results(tidy_survfit)

Value

an ARD data frame of class 'card'

Examples

cardx:::.format_survfit_results(
  broom::tidy(survival::survfit(survival::Surv(AVAL, CNSR) ~ TRTA, cards::ADTTE))
)

Convert t-test to ARD

Description

Convert t-test to ARD

Usage

.format_ttest_results(by = NULL, variable, lst_tidy, paired, ...)

Arguments

Value

ARD data frame

Examples

cardx:::.format_ttest_results(
  by = "ARM",
  variable = "AGE",
  paired = FALSE,
  lst_tidy =
    cards::eval_capture_conditions(
      stats::t.test(ADSL[["AGE"]] ~ ADSL[["ARM"]], paired = FALSE) |>
        broom::tidy()
    )
)

Convert Wilcoxon test to ARD

Description

Convert Wilcoxon test to ARD

Usage

.format_wilcoxtest_results(by = NULL, variable, lst_tidy, paired, ...)

Arguments

Value

ARD data frame

Examples

# Pre-processing ADSL to have grouping factor (ARM here) with 2 levels
ADSL <- cards::ADSL |>
  dplyr::filter(ARM %in% c("Placebo", "Xanomeline High Dose")) |>
  ard_stats_wilcox_test(by = "ARM", variables = "AGE")

cardx:::.format_wilcoxtest_results(
  by = "ARM",
  variable = "AGE",
  paired = FALSE,
  lst_tidy =
    cards::eval_capture_conditions(
      stats::wilcox.test(ADSL[["AGE"]] ~ ADSL[["ARM"]], paired = FALSE) |>
        broom::tidy()
    )
)

Convert long paired data to wide

Description

Convert long paired data to wide

Usage

.paired_data_pivot_wider(data, by, variable, id)

Arguments

Value

a wide data frame

Examples

cards::ADSL[c("ARM", "AGE")] |>
  dplyr::filter(ARM %in% c("Placebo", "Xanomeline High Dose")) |>
  dplyr::mutate(.by = ARM, USUBJID = dplyr::row_number()) |>
  dplyr::arrange(USUBJID, ARM) |>
  cardx:::.paired_data_pivot_wider(by = "ARM", variable = "AGE", id = "USUBJID")

Convert Nested Lists to Column

Description

Some arguments, such as stat_label, are passed as nested lists. This function properly unnests these lists and adds them to the results data frame.

Usage

.process_nested_list_as_df(x, arg, new_column, unlist = FALSE)

Arguments

Value

a data frame

Examples

ard <- ard_categorical(cards::ADSL, by = "ARM", variables = "AGEGR1")

cardx:::.process_nested_list_as_df(ard, NULL, "new_col")

Process Survival Fit For Quantile Estimates

Description

Process Survival Fit For Quantile Estimates

Usage

.process_survfit_probs(x, probs)

Arguments

Value

a tibble

Examples

survival::survfit(survival::Surv(AVAL, CNSR) ~ TRTA, cards::ADTTE) |>
  cardx:::.process_survfit_probs(probs = c(0.25, 0.75))

Process Survival Fit For Time Estimates

Description

Process Survival Fit For Time Estimates

Usage

.process_survfit_time(x, times, type, start.time = NULL)

Arguments

Value

a tibble

Examples

survival::survfit(survival::Surv(AVAL, CNSR) ~ TRTA, cards::ADTTE) |>
  cardx:::.process_survfit_time(times = c(60, 180), type = "risk")

Helper Function for the Estimation of Stratified Quantiles

Description

This function wraps the estimation of stratified percentiles when we assume the approximation for large numbers. This is necessary only in the case proportions for each strata are unequal.

Usage

.strata_normal_quantile(vars, weights, conf.level)

Arguments

Value

Stratified quantile.

See Also

proportion_ci_strat_wilson()

Examples

strata_data <- table(data.frame(
  "f1" = sample(c(TRUE, FALSE), 100, TRUE),
  "f2" = sample(c("x", "y", "z"), 100, TRUE),
  stringsAsFactors = TRUE
))
ns <- colSums(strata_data)
ests <- strata_data["TRUE", ] / ns
vars <- ests * (1 - ests) / ns
weights <- rep(1 / length(ns), length(ns))

cardx:::.strata_normal_quantile(vars, weights, 0.95)

ARD-flavor of unique()

Description

Essentially a wrapper for unique(x) |> sort() with NA levels removed. For factors, all levels are returned even if they are unobserved. Similarly, logical vectors always return c(TRUE, FALSE), even if both levels are not observed.

Usage

.unique_and_sorted(x, useNA = c("no", "always"))

Arguments

Value

a vector

Examples

cards:::.unique_and_sorted(factor(letters[c(5, 5:1)], levels = letters))

cards:::.unique_and_sorted(c(FALSE, TRUE, TRUE, FALSE))

cards:::.unique_and_sorted(c(5, 5:1))

Helper Function for the Estimation of Weights for proportion_ci_strat_wilson()

Description

This function wraps the iteration procedure that allows you to estimate the weights for each proportional strata. This assumes to minimize the weighted squared length of the confidence interval.

Usage

.update_weights_strat_wilson(
  vars,
  strata_qnorm,
  initial_weights,
  n_per_strata,
  max.iterations = 50,
  conf.level = 0.95,
  tol = 0.001
)

Arguments

Value

A list of 3 elements: n_it, weights, and diff_v.

See Also

For references and details see proportion_ci_strat_wilson().

Examples

vs <- c(0.011, 0.013, 0.012, 0.014, 0.017, 0.018)
sq <- 0.674
ws <- rep(1 / length(vs), length(vs))
ns <- c(22, 18, 17, 17, 14, 12)

cardx:::.update_weights_strat_wilson(vs, sq, ws, ns, 100, 0.95, 0.001)

ARD Wald Test

Description

Function takes a regression model object and calculates Wald statistical test using aod::wald.test().

Usage

ard_aod_wald_test(
  x,
  tidy_fun = broom.helpers::tidy_with_broom_or_parameters,
  ...
)

Arguments

Value

data frame

Examples

lm(AGE ~ ARM, data = cards::ADSL) |>
  ard_aod_wald_test()

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.

Usage

## S3 method for class 'survey.design'
ard_attributes(data, variables = everything(), label = NULL, ...)

Arguments

Value

an ARD data frame of class 'card'

Examples

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 ANOVA from car Package

Description

Function takes a regression model object and calculated ANOVA using car::Anova().

Usage

ard_car_anova(x, ...)

Arguments

Value

data frame

Examples

lm(AGE ~ ARM, data = cards::ADSL) |>
  ard_car_anova()

glm(vs ~ factor(cyl) + factor(am), data = mtcars, family = binomial) |>
  ard_car_anova(test.statistic = "Wald")

Regression VIF ARD

Description

Function takes a regression model object and returns the variance inflation factor (VIF) using car::vif() and converts it to a ARD structure

Usage

ard_car_vif(x, ...)

Arguments

Value

data frame

Examples

lm(AGE ~ ARM + SEX, data = cards::ADSL) |>
  ard_car_vif()

ARD Categorical Survey Statistics

Description

Compute tabulations on survey-weighted data.

The counts and proportion ("N", "n", "p") are calculated using survey::svytable(), and the standard errors and design effect ("p.std.error", "deff") are calculated using survey::svymean().

The unweighted statistics are calculated with cards::ard_categorical.data.frame().

Usage

## S3 method for class 'survey.design'
ard_categorical(
  data,
  variables,
  by = NULL,
  statistic = everything() ~ c("n", "N", "p", "p.std.error", "deff", "n_unweighted",
    "N_unweighted", "p_unweighted"),
  denominator = c("column", "row", "cell"),
  fmt_fun = NULL,
  stat_label = everything() ~ list(p = "%", p.std.error = "SE(%)", deff =
    "Design Effect", n_unweighted = "Unweighted n", N_unweighted = "Unweighted N",
    p_unweighted = "Unweighted %"),
  fmt_fn = deprecated(),
  ...
)

Arguments

Value

an ARD data frame of class 'card'

Examples

svy_titanic <- survey::svydesign(~1, data = as.data.frame(Titanic), weights = ~Freq)

ard_categorical(svy_titanic, variables = c(Class, Age), by = Survived)

ARD Proportion Confidence Intervals

Description

Calculate confidence intervals for proportions.

Usage

ard_categorical_ci(data, ...)

## S3 method for class 'data.frame'
ard_categorical_ci(
  data,
  variables,
  by = dplyr::group_vars(data),
  method = c("waldcc", "wald", "clopper-pearson", "wilson", "wilsoncc", "strat_wilson",
    "strat_wilsoncc", "agresti-coull", "jeffreys"),
  denominator = c("column", "row", "cell"),
  conf.level = 0.95,
  value = list(where(is_binary) ~ 1L, where(is.logical) ~ TRUE),
  strata = NULL,
  weights = NULL,
  max.iterations = 10,
  ...
)

Arguments

Value

an ARD data frame

Examples

# compute CI for binary variables
ard_categorical_ci(mtcars, variables = c(vs, am), method = "wilson")

# compute CIs for each level of a categorical variable
ard_categorical_ci(mtcars, variables = cyl, method = "jeffreys")

ARD survey categorical CIs

Description

Confidence intervals for categorical variables calculated via survey::svyciprop().

Usage

## S3 method for class 'survey.design'
ard_categorical_ci(
  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),
  ...
)

Arguments

Value

ARD data frame

Examples

data(api, package = "survey")
dclus1 <- survey::svydesign(id = ~dnum, weights = ~pw, data = apiclus1, fpc = ~fpc)

ard_categorical_ci(dclus1, variables = sch.wide)
ard_categorical_ci(dclus1, variables = sch.wide, value = sch.wide ~ "Yes", method = "xlogit")

ARD to Calculate Categorical Occurrence Rates by Maximum Level Per Unique ID

Description

Function calculates categorical variable level occurrences rates by maximum level per unique ID. Each variable in variables is evaluated independently and then results for all variables are stacked. Only the highest-ordered level will be counted for each unique ID. Unordered, non-numeric variables will be converted to factor and the default level order used for ordering.

Usage

ard_categorical_max(
  data,
  variables,
  id,
  by = dplyr::group_vars(data),
  statistic = everything() ~ c("n", "p", "N"),
  denominator = NULL,
  strata = NULL,
  fmt_fun = NULL,
  stat_label = everything() ~ cards::default_stat_labels(),
  quiet = FALSE,
  fmt_fn = deprecated(),
  ...
)

Arguments

Value

an ARD data frame of class 'card'

Examples

# Occurrence Rates by Max Level (Highest Severity) --------------------------
ard_categorical_max(
  cards::ADAE,
  variables = c(AESER, AESEV),
  id = USUBJID,
  by = TRTA,
  denominator = cards::ADSL
)

ARD Continuous Survey Statistics

Description

Returns an ARD of weighted statistics using the {survey} package.

Usage

## S3 method for class 'survey.design'
ard_continuous(
  data,
  variables,
  by = NULL,
  statistic = everything() ~ c("median", "p25", "p75"),
  fmt_fun = NULL,
  stat_label = NULL,
  fmt_fn = deprecated(),
  ...
)

Arguments

Value

an ARD data frame of class 'card'

statistic argument

The following statistics are available: 'mean', 'median', 'min', 'max', 'sum', 'var', 'sd', 'mean.std.error', 'deff', 'p##', where 'p##' is are the percentiles and ⁠##⁠ is an integer between 0 and 100.

Examples

data(api, package = "survey")
dclus1 <- survey::svydesign(id = ~dnum, weights = ~pw, data = apiclus1, fpc = ~fpc)

ard_continuous(
  data = dclus1,
  variables = api00,
  by = stype
)

ARD continuous CIs

Description

One-sample confidence intervals for continuous variable means and medians.

Usage

ard_continuous_ci(data, ...)

## S3 method for class 'data.frame'
ard_continuous_ci(
  data,
  variables,
  by = dplyr::group_vars(data),
  conf.level = 0.95,
  method = c("t.test", "wilcox.test"),
  ...
)

Arguments

Value

ARD data frame

Examples

ard_continuous_ci(mtcars, variables = c(mpg, hp), method = "wilcox.test")
ard_continuous_ci(mtcars, variables = mpg, by = am, method = "t.test")

ARD survey continuous CIs

Description

One-sample confidence intervals for continuous variables' means and medians. Confidence limits are calculated with survey::svymean() and survey::svyquantile().

Usage

## S3 method for class 'survey.design'
ard_continuous_ci(
  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),
  ...
)

Arguments

Value

ARD data frame

Examples

data(api, package = "survey")
dclus1 <- survey::svydesign(id = ~dnum, weights = ~pw, data = apiclus1, fpc = ~fpc)

ard_continuous_ci(dclus1, variables = api00)
ard_continuous_ci(dclus1, variables = api00, method = "svymedian.xlogit")

ARD Dichotomous Survey Statistics

Description

Compute Analysis Results Data (ARD) for dichotomous summary statistics.

Usage

## S3 method for class 'survey.design'
ard_dichotomous(
  data,
  variables,
  by = NULL,
  value = cards::maximum_variable_value(data$variables[variables]),
  statistic = everything() ~ c("n", "N", "p", "p.std.error", "deff", "n_unweighted",
    "N_unweighted", "p_unweighted"),
  denominator = c("column", "row", "cell"),
  fmt_fun = NULL,
  stat_label = everything() ~ list(p = "%", p.std.error = "SE(%)", deff =
    "Design Effect", n_unweighted = "Unweighted n", N_unweighted = "Unweighted N",
    p_unweighted = "Unweighted %"),
  fmt_fn = deprecated(),
  ...
)

Arguments

Value

an ARD data frame of class 'card'

Examples

survey::svydesign(ids = ~1, data = mtcars, weights = ~1) |>
  ard_dichotomous(by = vs, variables = c(cyl, am), value = list(cyl = 4))

ARD Cohen's D Test

Description

Analysis results data for paired and non-paired Cohen's D Effect Size Test using effectsize::cohens_d().

Usage

ard_effectsize_cohens_d(data, by, variables, conf.level = 0.95, ...)

ard_effectsize_paired_cohens_d(data, by, variables, id, conf.level = 0.95, ...)

Arguments

Details

For the ard_effectsize_cohens_d() function, the data is expected to be one row per subject. The data is passed as effectsize::cohens_d(data[[variable]]~data[[by]], data, paired = FALSE, ...).

For the ard_effectsize_paired_cohens_d() function, the data is expected to be one row per subject per by level. Before the effect size is calculated, the data are reshaped to a wide format to be one row per subject. The data are then passed as ⁠effectsize::cohens_d(x = data_wide[[<by level 1>]], y = data_wide[[<by level 2>]], paired = TRUE, ...)⁠.

Value

ARD data frame

Examples

cards::ADSL |>
  dplyr::filter(ARM %in% c("Placebo", "Xanomeline High Dose")) |>
  ard_effectsize_cohens_d(by = ARM, variables = AGE)

# constructing a paired data set,
# where patients receive both treatments
cards::ADSL[c("ARM", "AGE")] |>
  dplyr::filter(ARM %in% c("Placebo", "Xanomeline High Dose")) |>
  dplyr::mutate(.by = ARM, USUBJID = dplyr::row_number()) |>
  dplyr::arrange(USUBJID, ARM) |>
  dplyr::group_by(USUBJID) |>
  dplyr::filter(dplyr::n() > 1) |>
  ard_effectsize_paired_cohens_d(by = ARM, variables = AGE, id = USUBJID)

ARD Hedge's G Test

Description

Analysis results data for paired and non-paired Hedge's G Effect Size Test using effectsize::hedges_g().

Usage

ard_effectsize_hedges_g(data, by, variables, conf.level = 0.95, ...)

ard_effectsize_paired_hedges_g(data, by, variables, id, conf.level = 0.95, ...)

Arguments

Details

For the ard_effectsize_hedges_g() function, the data is expected to be one row per subject. The data is passed as effectsize::hedges_g(data[[variable]]~data[[by]], data, paired = FALSE, ...).

For the ard_effectsize_paired_hedges_g() function, the data is expected to be one row per subject per by level. Before the effect size is calculated, the data are reshaped to a wide format to be one row per subject. The data are then passed as ⁠effectsize::hedges_g(x = data_wide[[<by level 1>]], y = data_wide[[<by level 2>]], paired = TRUE, ...)⁠.

Value

ARD data frame

Examples

cards::ADSL |>
  dplyr::filter(ARM %in% c("Placebo", "Xanomeline High Dose")) |>
  ard_effectsize_hedges_g(by = ARM, variables = AGE)

# constructing a paired data set,
# where patients receive both treatments
cards::ADSL[c("ARM", "AGE")] |>
  dplyr::filter(ARM %in% c("Placebo", "Xanomeline High Dose")) |>
  dplyr::mutate(.by = ARM, USUBJID = dplyr::row_number()) |>
  dplyr::arrange(USUBJID, ARM) |>
  dplyr::group_by(USUBJID) |>
  dplyr::filter(dplyr::n() > 1) |>
  ard_effectsize_paired_hedges_g(by = ARM, variables = AGE, id = USUBJID)

ARD for LS Mean Difference

Description

This function calculates least-squares mean differences using the 'emmeans' package using the following

emmeans::emmeans(object = <regression model>, specs = ~ <primary covariate>) |>
  emmeans::contrast(method = "pairwise") |>
  summary(infer = TRUE, level = <confidence level>)

The arguments data, formula, method, method.args, package are used to construct the regression model via cardx::construct_model().

Usage

ard_emmeans_mean_difference(
  data,
  formula,
  method,
  method.args = list(),
  package = "base",
  response_type = c("continuous", "dichotomous"),
  conf.level = 0.95,
  primary_covariate = getElement(attr(stats::terms(formula), "term.labels"), 1L)
)

Arguments

Value

ARD data frame

Examples

ard_emmeans_mean_difference(
  data = mtcars,
  formula = mpg ~ am + cyl,
  method = "lm"
)

ard_emmeans_mean_difference(
  data = mtcars,
  formula = vs ~ am + mpg,
  method = "glm",
  method.args = list(family = binomial),
  response_type = "dichotomous"
)

ARD Incidence Rate

Description

Function takes a time at risk variable (time) and event count variable (count) and calculates the incidence rate in person-years.

Incidence rate is calculated as: Total number of events that occurred / Total person-time at risk

Usage

ard_incidence_rate(
  data,
  time,
  count = NULL,
  id = NULL,
  by = NULL,
  strata = NULL,
  n_person_time = 100,
  unit_label = "time",
  conf.level = 0.95,
  conf.type = c("normal", "normal-log", "exact", "byar")
)

Arguments

Details

The formulas used to calculate the confidence interval for each CI type are as follows, where x_i and t_i represent the number of events and follow-up time for subject i, respectively.

• byar: Byar's approximation of a Poisson CI. A continuity correction of 0.5 is included in the calculation.

  CI = (\sum{x_i} + 0.5) (1 - 1 / (9 \times (\sum{x_i} + 0.5)) \pm Z_{1 - \alpha / 2} / (3 \sqrt{\sum{x_i} + 0.5}))^3 / \sum{t_i}

• normal: Normal CI.

  CI = \sum{x_i} / \sum{t_i} \pm Z_{1 - \alpha / 2} \sqrt{\sum{x_i}} / \sum{t_i}

• normal-log: Normal-Log CI.

  CI = \exp(\log(\sum{x_i} / \sum{t_i}) \pm Z_{1 - \alpha / 2} / \sqrt{\sum{x_i}})

• exact: Exact CI for a Poisson mean.

  CI_{lower} = \chi^2_{\alpha / 2, 2\sum{x_i} + 2} / {2 \sum{t_i}}

  CI_{upper} = \chi^2_{1 - \alpha / 2, 2\sum{x_i} + 2} / {2 \sum{t_i}}

Value

an ARD data frame of class 'card'

Examples

set.seed(1)
data <- data.frame(
  USUBJID = 1:100,
  TRTA = sample(LETTERS[1:3], 100, replace = TRUE),
  AETTE1 = abs(rnorm(100, mean = 0.5)),
  AETOT1 = sample(0:20, 100, replace = TRUE)
)

data |>
  ard_incidence_rate(time = AETTE1, count = AETOT1, id = USUBJID, by = TRTA, unit_label = "years")

ARD Missing Survey Statistics

Description

Compute Analysis Results Data (ARD) for statistics related to data missingness for survey objects

Usage

## S3 method for class 'survey.design'
ard_missing(
  data,
  variables,
  by = NULL,
  statistic = everything() ~ c("N_obs", "N_miss", "N_nonmiss", "p_miss", "p_nonmiss",
    "N_obs_unweighted", "N_miss_unweighted", "N_nonmiss_unweighted", "p_miss_unweighted",
    "p_nonmiss_unweighted"),
  fmt_fun = NULL,
  stat_label = everything() ~ list(N_obs = "Total N", N_miss = "N Missing", N_nonmiss =
    "N not Missing", p_miss = "% Missing", p_nonmiss = "% not Missing",
    N_obs_unweighted = "Total N (unweighted)", N_miss_unweighted =
    "N Missing (unweighted)", N_nonmiss_unweighted = "N not Missing (unweighted)",
    p_miss_unweighted = "% Missing (unweighted)", p_nonmiss_unweighted =
    "% not Missing (unweighted)"),
  fmt_fn = deprecated(),
  ...
)

Arguments

Value

an ARD data frame of class 'card'

Examples

svy_titanic <- survey::svydesign(~1, data = as.data.frame(Titanic), weights = ~Freq)

ard_missing(svy_titanic, variables = c(Class, Age), by = Survived)

Regression ARD

Description

Function takes a regression model object and converts it to a ARD structure using the broom.helpers package.

Usage

ard_regression(x, ...)

## Default S3 method:
ard_regression(x, tidy_fun = broom.helpers::tidy_with_broom_or_parameters, ...)

## S3 method for class 'data.frame'
ard_regression(
  x,
  formula,
  method,
  method.args = list(),
  package = "base",
  tidy_fun = broom.helpers::tidy_with_broom_or_parameters,
  ...
)

Arguments

Value

data frame

Examples

lm(AGE ~ ARM, data = cards::ADSL) |>
  ard_regression(add_estimate_to_reference_rows = TRUE)

ard_regression(
  x = cards::ADSL,
  formula = AGE ~ ARM,
  method = "lm"
)

Basic Regression ARD

Description

A function that takes a regression model and provides basic statistics in an ARD structure. The default output is simpler than ard_regression(). The function primarily matches regression terms to underlying variable names and levels. The default arguments used are

broom.helpers::tidy_plus_plus(
  add_reference_rows = FALSE,
  add_estimate_to_reference_rows = FALSE,
  add_n = FALSE,
  intercept = FALSE
)

Usage

ard_regression_basic(x, ...)

## Default S3 method:
ard_regression_basic(
  x,
  tidy_fun = broom.helpers::tidy_with_broom_or_parameters,
  stats_to_remove = c("term", "var_type", "var_label", "var_class", "label",
    "contrasts_type", "contrasts", "var_nlevels"),
  ...
)

## S3 method for class 'data.frame'
ard_regression_basic(
  x,
  formula,
  method,
  method.args = list(),
  package = "base",
  tidy_fun = broom.helpers::tidy_with_broom_or_parameters,
  stats_to_remove = c("term", "var_type", "var_label", "var_class", "label",
    "contrasts_type", "contrasts", "var_nlevels"),
  ...
)

Arguments

Value

data frame

Examples

lm(AGE ~ ARM, data = cards::ADSL) |>
  ard_regression_basic()

ard_regression_basic(
  x = cards::ADSL,
  formula = AGE ~ ARM,
  method = "lm"
)

ARD Standardized Mean Difference

Description

Standardized mean difference calculated via smd::smd() with na.rm = TRUE. Additionally, this function add a confidence interval to the SMD when std.error=TRUE, which the original smd::smd() does not include.

Usage

ard_smd_smd(data, by, variables, std.error = TRUE, conf.level = 0.95, ...)

Arguments

Value

ARD data frame

Examples

ard_smd_smd(cards::ADSL, by = SEX, variables = AGE)
ard_smd_smd(cards::ADSL, by = SEX, variables = AGEGR1)

ARD ANOVA

Description

Prepare ANOVA results from the stats::anova() function. Users may pass a pre-calculated stats::anova() object or a list of formulas. In the latter case, the models will be constructed using the information passed and models will be passed to stats::anova().

Usage

ard_stats_anova(x, ...)

## S3 method for class 'anova'
ard_stats_anova(x, method_text = "ANOVA results from `stats::anova()`", ...)

## S3 method for class 'data.frame'
ard_stats_anova(
  x,
  formulas,
  method,
  method.args = list(),
  package = "base",
  method_text = "ANOVA results from `stats::anova()`",
  ...
)

Arguments

Details

When a list of formulas is supplied to ard_stats_anova(), these formulas along with information from other arguments, are used to construct models and pass those models to stats::anova().

The models are constructed using rlang::exec(), which is similar to do.call().

rlang::exec(.fn = method, formula = formula, data = data, !!!method.args)

The above function is executed in withr::with_namespace(package), which allows for the use of ard_stats_anova(method) from packages, e.g. package = 'lme4' must be specified when method = 'glmer'. See example below.

Value

ARD data frame

Examples

anova(
  lm(mpg ~ am, mtcars),
  lm(mpg ~ am + hp, mtcars)
) |>
  ard_stats_anova()

ard_stats_anova(
  x = mtcars,
  formulas = list(am ~ mpg, am ~ mpg + hp),
  method = "glm",
  method.args = list(family = binomial)
)

ard_stats_anova(
  x = mtcars,
  formulas = list(am ~ 1 + (1 | vs), am ~ mpg + (1 | vs)),
  method = "glmer",
  method.args = list(family = binomial),
  package = "lme4"
)

ARD ANOVA

Description

Analysis results data for Analysis of Variance. Calculated with stats::aov()

Usage

ard_stats_aov(formula, data, ...)

Arguments

Value

ARD data frame

Examples

ard_stats_aov(AGE ~ ARM, data = cards::ADSL)

ARD Chi-squared Test

Description

Analysis results data for Pearson's Chi-squared Test. Calculated with chisq.test(x = data[[variable]], y = data[[by]], ...)

Usage

ard_stats_chisq_test(data, by, variables, ...)

Arguments

Value

ARD data frame

Examples

cards::ADSL |>
  ard_stats_chisq_test(by = "ARM", variables = "AGEGR1")

ARD Fisher's Exact Test

Description

Analysis results data for Fisher's Exact Test. Calculated with fisher.test(x = data[[variable]], y = data[[by]], ...)

Usage

ard_stats_fisher_test(data, by, variables, conf.level = 0.95, ...)

Arguments

Value

ARD data frame

Examples

cards::ADSL[1:30, ] |>
  ard_stats_fisher_test(by = "ARM", variables = "AGEGR1")

ARD Kruskal-Wallis Test

Description

Analysis results data for Kruskal-Wallis Rank Sum Test.

Calculated with kruskal.test(data[[variable]], data[[by]], ...)

Usage

ard_stats_kruskal_test(data, by, variables)

Arguments

Value

ARD data frame

Examples

cards::ADSL |>
  ard_stats_kruskal_test(by = "ARM", variables = "AGE")

ARD Cochran-Mantel-Haenszel Chi-Squared Test

Description

Analysis results data for Cochran-Mantel-Haenszel Chi-Squared Test for count data. Calculated with mantelhaen.test(x = data[[variables]], y = data[[by]], z = data[[strata]], ...).

Usage

ard_stats_mantelhaen_test(data, by, variables, strata, ...)

Arguments

Value

ARD data frame

Examples

cards::ADSL |>
  ard_stats_mantelhaen_test(by = "ARM", variables = "AGEGR1", strata = "SEX")

ARD McNemar's Test

Description

Analysis results data for McNemar's statistical test. We have two functions depending on the structure of the data.

• ard_stats_mcnemar_test() is the structure expected by stats::mcnemar.test()

• ard_stats_mcnemar_test_long() is one row per ID per group

Usage

ard_stats_mcnemar_test(data, by, variables, ...)

ard_stats_mcnemar_test_long(data, by, variables, id, ...)

Arguments

Details

For the ard_stats_mcnemar_test() function, the data is expected to be one row per subject. The data is passed as stats::mcnemar.test(x = data[[variable]], y = data[[by]], ...). Please use table(x = data[[variable]], y = data[[by]]) to check the contingency table.

Value

ARD data frame

Examples

cards::ADSL |>
  ard_stats_mcnemar_test(by = "SEX", variables = "EFFFL")

set.seed(1234)
cards::ADSL[c("USUBJID", "TRT01P")] |>
  dplyr::mutate(TYPE = "PLANNED") |>
  dplyr::rename(TRT01 = TRT01P) %>%
  dplyr::bind_rows(dplyr::mutate(., TYPE = "ACTUAL", TRT01 = sample(TRT01))) |>
  ard_stats_mcnemar_test_long(
    by = TYPE,
    variable = TRT01,
    id = USUBJID
  )

ARD Mood Test

Description

Analysis results data for Mood two sample test of scale. Note this not to be confused with the Brown-Mood test of medians.

Usage

ard_stats_mood_test(data, by, variables, ...)

Arguments

Details

For the ard_stats_mood_test() function, the data is expected to be one row per subject. The data is passed as mood.test(data[[variable]] ~ data[[by]], ...).

Value

ARD data frame

Examples

cards::ADSL |>
  ard_stats_mood_test(by = "SEX", variables = "AGE")

ARD One-way Test

Description

Analysis results data for Testing Equal Means in a One-Way Layout. calculated with oneway.test()

Usage

ard_stats_oneway_test(formula, data, ...)

Arguments

Value

ARD data frame

Examples

ard_stats_oneway_test(AGE ~ ARM, data = cards::ADSL)

ARD Poisson Test

Description

Analysis results data for exact tests of a simple null hypothesis about the rate parameter in Poisson distribution, or the comparison of two rate parameters.

Usage

ard_stats_poisson_test(
  data,
  variables,
  na.rm = TRUE,
  by = NULL,
  conf.level = 0.95,
  ...
)

Arguments

Details

• For the ard_stats_poisson_test() function, the data is expected to be one row per subject.

• If by is not specified, an exact Poisson test of the rate parameter will be performed. Otherwise, a Poisson comparison of two rate parameters will be performed on the levels of by. If by has more than 2 levels, an error will occur.

Value

an ARD data frame of class 'card'

Examples

# Exact test of rate parameter against null hypothesis
cards::ADTTE |>
  ard_stats_poisson_test(variables = c(CNSR, AVAL))

# Comparison test of ratio of 2 rate parameters against null hypothesis
cards::ADTTE |>
  dplyr::filter(TRTA %in% c("Placebo", "Xanomeline High Dose")) |>
  ard_stats_poisson_test(by = TRTA, variables = c(CNSR, AVAL))

ARD 2-sample proportion test

Description

Analysis results data for a 2-sample test or proportions using stats::prop.test().

Usage

ard_stats_prop_test(data, by, variables, conf.level = 0.95, ...)

Arguments

Value

ARD data frame

Examples

mtcars |>
  ard_stats_prop_test(by = vs, variables = am)

ARD t-test

Description

Analysis results data for paired and non-paired t-tests.

Usage

ard_stats_t_test(data, variables, by = NULL, conf.level = 0.95, ...)

ard_stats_paired_t_test(data, by, variables, id, conf.level = 0.95, ...)

Arguments

Details

For the ard_stats_t_test() function, the data is expected to be one row per subject. The data is passed as t.test(data[[variable]] ~ data[[by]], paired = FALSE, ...).

For the ard_stats_paired_t_test() function, the data is expected to be one row per subject per by level. Before the t-test is calculated, the data are reshaped to a wide format to be one row per subject. The data are then passed as ⁠t.test(x = data_wide[[<by level 1>]], y = data_wide[[<by level 2>]], paired = TRUE, ...)⁠.

Value

ARD data frame

Examples

cards::ADSL |>
  dplyr::filter(ARM %in% c("Placebo", "Xanomeline High Dose")) |>
  ard_stats_t_test(by = ARM, variables = c(AGE, BMIBL))

# constructing a paired data set,
# where patients receive both treatments
cards::ADSL[c("ARM", "AGE")] |>
  dplyr::filter(ARM %in% c("Placebo", "Xanomeline High Dose")) |>
  dplyr::mutate(.by = ARM, USUBJID = dplyr::row_number()) |>
  dplyr::arrange(USUBJID, ARM) |>
  ard_stats_paired_t_test(by = ARM, variables = AGE, id = USUBJID)

ARD one-sample t-test

Description

Analysis results data for one-sample t-tests. Result may be stratified by including the by argument.

Usage

ard_stats_t_test_onesample(
  data,
  variables,
  by = dplyr::group_vars(data),
  conf.level = 0.95,
  ...
)

Arguments

Value

ARD data frame

Examples

cards::ADSL |>
  ard_stats_t_test_onesample(by = ARM, variables = AGE)

ARD Wilcoxon Rank-Sum Test

Description

Analysis results data for paired and non-paired Wilcoxon Rank-Sum tests.

Usage

ard_stats_wilcox_test(data, variables, by = NULL, conf.level = 0.95, ...)

ard_stats_paired_wilcox_test(data, by, variables, id, conf.level = 0.95, ...)

Arguments

Details

For the ard_stats_wilcox_test() function, the data is expected to be one row per subject. The data is passed as wilcox.test(data[[variable]] ~ data[[by]], paired = FALSE, ...).

For the ard_stats_paired_wilcox_test() function, the data is expected to be one row per subject per by level. Before the test is calculated, the data are reshaped to a wide format to be one row per subject. The data are then passed as ⁠wilcox.test(x = data_wide[[<by level 1>]], y = data_wide[[<by level 2>]], paired = TRUE, ...)⁠.

Value

ARD data frame

Examples

cards::ADSL |>
  dplyr::filter(ARM %in% c("Placebo", "Xanomeline High Dose")) |>
  ard_stats_wilcox_test(by = "ARM", variables = "AGE")

# constructing a paired data set,
# where patients receive both treatments
cards::ADSL[c("ARM", "AGE")] |>
  dplyr::filter(ARM %in% c("Placebo", "Xanomeline High Dose")) |>
  dplyr::mutate(.by = ARM, USUBJID = dplyr::row_number()) |>
  dplyr::arrange(USUBJID, ARM) |>
  ard_stats_paired_wilcox_test(by = ARM, variables = AGE, id = USUBJID)

ARD one-sample Wilcox Rank-sum

Description

Analysis results data for one-sample Wilcox Rank-sum. Result may be stratified by including the by argument.

Usage

ard_stats_wilcox_test_onesample(
  data,
  variables,
  by = dplyr::group_vars(data),
  conf.level = 0.95,
  ...
)

Arguments

Value

ARD data frame

Examples

cards::ADSL |>
  ard_stats_wilcox_test_onesample(by = ARM, variables = AGE)

ARD Survey Chi-Square Test

Description

Analysis results data for survey Chi-Square test using survey::svychisq(). Only two-way comparisons are supported.

Usage

ard_survey_svychisq(data, by, variables, statistic = "F", ...)

Arguments

Value

ARD data frame

Examples

data(api, package = "survey")
dclus1 <- survey::svydesign(id = ~dnum, weights = ~pw, data = apiclus1, fpc = ~fpc)

ard_survey_svychisq(dclus1, variables = sch.wide, by = comp.imp, statistic = "F")

ARD Survey rank test

Description

Analysis results data for survey wilcox test using survey::svyranktest().

Usage

ard_survey_svyranktest(data, by, variables, test, ...)

Arguments

Value

ARD data frame

Examples

data(api, package = "survey")
dclus2 <- survey::svydesign(id = ~ dnum + snum, fpc = ~ fpc1 + fpc2, data = apiclus2)

ard_survey_svyranktest(dclus2, variables = enroll, by = comp.imp, test = "wilcoxon")
ard_survey_svyranktest(dclus2, variables = enroll, by = comp.imp, test = "vanderWaerden")
ard_survey_svyranktest(dclus2, variables = enroll, by = comp.imp, test = "median")
ard_survey_svyranktest(dclus2, variables = enroll, by = comp.imp, test = "KruskalWallis")

ARD Survey t-test

Description

Analysis results data for survey t-test using survey::svyttest().

Usage

ard_survey_svyttest(data, by, variables, conf.level = 0.95, ...)

Arguments

Value

ARD data frame

Examples

data(api, package = "survey")
dclus2 <- survey::svydesign(id = ~ dnum + snum, fpc = ~ fpc1 + fpc2, data = apiclus2)

ard_survey_svyttest(dclus2, variables = enroll, by = comp.imp, conf.level = 0.9)

ARD for Difference in Survival

Description

Analysis results data for comparison of survival using survival::survdiff().

Usage

ard_survival_survdiff(formula, data, rho = 0, ...)

Arguments

Value

an ARD data frame of class 'card'

Examples

library(survival)
library(ggsurvfit)

ard_survival_survdiff(Surv_CNSR(AVAL, CNSR) ~ TRTA, data = cards::ADTTE)

ARD Survival Estimates

Description

Analysis results data for survival quantiles and x-year survival estimates, extracted from a survival::survfit() model.

Usage

ard_survival_survfit(x, ...)

## S3 method for class 'survfit'
ard_survival_survfit(x, times = NULL, probs = NULL, type = NULL, ...)

## S3 method for class 'data.frame'
ard_survival_survfit(
  x,
  y,
  variables = NULL,
  times = NULL,
  probs = NULL,
  type = NULL,
  method.args = list(conf.int = 0.95, conf.type = "log"),
  ...
)

Arguments

Details

• Only one of either the times or probs parameters can be specified.

• Times should be provided using the same scale as the time variable used to fit the provided survival fit model.

Value

an ARD data frame of class 'card'

Formula Specification

When passing a survival::survfit() object to ard_survival_survfit(), the survfit() call must use an evaluated formula and not a stored formula. Including a proper formula in the call allows the function to accurately identify all variables included in the estimation. See below for examples:

library(cardx)
library(survival)

# include formula in `survfit()` call
survfit(Surv(time, status) ~ sex, lung) |> ard_survival_survfit(time = 500)

# you can also pass a data frame to `ard_survival_survfit()` as well.
lung |>
  ard_survival_survfit(y = Surv(time, status), variables = "sex", time = 500)

You cannot, however, pass a stored formula, e.g. survfit(my_formula, lung), but you can use stored formulas with rlang::inject(survfit(!!my_formula, lung)).

Variable Classes

When the survfit method is called, the class of the stratifying variables will be returned as a factor.

When the data frame method is called, the original classes are retained in the resulting ARD.

Examples

library(survival)
library(ggsurvfit)

survfit(Surv_CNSR(AVAL, CNSR) ~ TRTA, data = cards::ADTTE) |>
  ard_survival_survfit(times = c(60, 180))

survfit(Surv_CNSR(AVAL, CNSR) ~ TRTA, data = cards::ADTTE, conf.int = 0.90) |>
  ard_survival_survfit(probs = c(0.25, 0.5, 0.75))

cards::ADTTE |>
  ard_survival_survfit(y = Surv_CNSR(AVAL, CNSR), variables = c("TRTA", "SEX"), times = 90)

# Competing Risks Example ---------------------------
set.seed(1)
ADTTE_MS <- cards::ADTTE %>%
  dplyr::mutate(
    CNSR = dplyr::case_when(
      CNSR == 0 ~ "censor",
      runif(dplyr::n()) < 0.5 ~ "death from cancer",
      TRUE ~ "death other causes"
    ) %>% factor()
  )

survfit(Surv(AVAL, CNSR) ~ TRTA, data = ADTTE_MS) %>%
  ard_survival_survfit(times = c(60, 180))

ARD Survival Differences

Description

Calculate differences in the Kaplan-Meier estimator of survival using the results from survival::survfit().

Usage

ard_survival_survfit_diff(x, times, conf.level = 0.95)

Arguments

Value

an ARD data frame of class 'card'

Examples

library(ggsurvfit)
library(survival)

survfit(Surv_CNSR() ~ TRTA, data = cards::ADTTE) |>
  ard_survival_survfit_diff(times = c(25, 50))

ARD Total N

Description

Returns the total N for a survey object. The placeholder variable name returned in the object is "..ard_total_n.."

Usage

## S3 method for class 'survey.design'
ard_total_n(data, ...)

Arguments

Value

an ARD data frame of class 'card'

Examples

svy_titanic <- survey::svydesign(~1, data = as.data.frame(Titanic), weights = ~Freq)

ard_total_n(svy_titanic)

Construction Helpers

Description

These functions help construct calls to various types of models.

Usage

construct_model(data, ...)

## S3 method for class 'data.frame'
construct_model(
  data,
  formula,
  method,
  method.args = list(),
  package = "base",
  env = caller_env(),
  ...
)

## S3 method for class 'survey.design'
construct_model(
  data,
  formula,
  method,
  method.args = list(),
  package = "survey",
  env = caller_env(),
  ...
)

reformulate2(
  termlabels,
  response = NULL,
  intercept = TRUE,
  env = parent.frame(),
  pattern_term = NULL,
  pattern_response = NULL
)

bt(x, pattern = NULL)

bt_strip(x)

Arguments

Details

• construct_model(): Builds models of the form ⁠method(data = data, formula = formula, method.args!!!)⁠. If the package argument is specified, that package is temporarily attached when the model is evaluated.

• reformulate2(): This is a copy of reformulate() except that variable names that contain a space are wrapped in backticks.

• bt(): Adds backticks to a character vector.

• bt_strip(): Removes backticks from a string if it begins and ends with a backtick.

Value

depends on the calling function

Examples

construct_model(
  data = mtcars,
  formula = am ~ mpg + (1 | vs),
  method = "glmer",
  method.args = list(family = binomial),
  package = "lme4"
) |>
  broom.mixed::tidy()

construct_model(
  data = mtcars |> dplyr::rename(`M P G` = mpg),
  formula = reformulate2(c("M P G", "cyl"), response = "hp"),
  method = "lm"
) |>
  ard_regression() |>
  dplyr::filter(stat_name %in% c("term", "estimate", "p.value"))

Functions for Calculating Proportion Confidence Intervals

Description

Functions to calculate different proportion confidence intervals for use in ard_proportion().

Usage

proportion_ci_wald(x, conf.level = 0.95, correct = FALSE)

proportion_ci_wilson(x, conf.level = 0.95, correct = FALSE)

proportion_ci_clopper_pearson(x, conf.level = 0.95)

proportion_ci_agresti_coull(x, conf.level = 0.95)

proportion_ci_jeffreys(x, conf.level = 0.95)

proportion_ci_strat_wilson(
  x,
  strata,
  weights = NULL,
  conf.level = 0.95,
  max.iterations = 10L,
  correct = FALSE
)

is_binary(x)

Arguments

Value

Confidence interval of a proportion.

Functions

• proportion_ci_wald(): Calculates the Wald interval by following the usual textbook definition for a single proportion confidence interval using the normal approximation.

  \hat{p} \pm z_{\alpha/2} \sqrt{\frac{\hat{p}(1 - \hat{p})}{n}}

• proportion_ci_wilson(): Calculates the Wilson interval by calling stats::prop.test(). Also referred to as Wilson score interval.

  \frac{\hat{p} + \frac{z^2_{\alpha/2}}{2n} \pm z_{\alpha/2} \sqrt{\frac{\hat{p}(1 - \hat{p})}{n} + \frac{z^2_{\alpha/2}}{4n^2}}}{1 + \frac{z^2_{\alpha/2}}{n}}

• proportion_ci_clopper_pearson(): Calculates the Clopper-Pearson interval by calling stats::binom.test(). Also referred to as the exact method.

  \left( \frac{k}{n} \pm z_{\alpha/2} \sqrt{\frac{\frac{k}{n}(1-\frac{k}{n})}{n} + \frac{z^2_{\alpha/2}}{4n^2}} \right) / \left( 1 + \frac{z^2_{\alpha/2}}{n} \right)

• proportion_ci_agresti_coull(): Calculates the Agresti-Coull interval (created by ⁠Alan Agresti⁠ and ⁠Brent Coull⁠) by (for 95% CI) adding two successes and two failures to the data and then using the Wald formula to construct a CI.

  \left( \frac{\tilde{p} + z^2_{\alpha/2}/2}{n + z^2_{\alpha/2}} \pm z_{\alpha/2} \sqrt{\frac{\tilde{p}(1 - \tilde{p})}{n} + \frac{z^2_{\alpha/2}}{4n^2}} \right)

• proportion_ci_jeffreys(): Calculates the Jeffreys interval, an equal-tailed interval based on the non-informative Jeffreys prior for a binomial proportion.

  \left( \text{Beta}\left(\frac{k}{2} + \frac{1}{2}, \frac{n - k}{2} + \frac{1}{2}\right)_\alpha, \text{Beta}\left(\frac{k}{2} + \frac{1}{2}, \frac{n - k}{2} + \frac{1}{2}\right)_{1-\alpha} \right)

• proportion_ci_strat_wilson(): Calculates the stratified Wilson confidence interval for unequal proportions as described in Xin YA, Su XG. Stratified Wilson and Newcombe confidence intervals for multiple binomial proportions. Statistics in Biopharmaceutical Research. 2010;2(3).

  \frac{\hat{p}_j + \frac{z^2_{\alpha/2}}{2n_j} \pm z_{\alpha/2} \sqrt{\frac{\hat{p}_j(1 - \hat{p}_j)}{n_j} + \frac{z^2_{\alpha/2}}{4n_j^2}}}{1 + \frac{z^2_{\alpha/2}}{n_j}}

• is_binary(): Helper to determine if vector is binary (logical or 0/1)

Examples

x <- c(
  TRUE, TRUE, TRUE, TRUE, TRUE,
  FALSE, FALSE, FALSE, FALSE, FALSE
)

proportion_ci_wald(x, conf.level = 0.9)
proportion_ci_wilson(x, correct = TRUE)
proportion_ci_clopper_pearson(x)
proportion_ci_agresti_coull(x)
proportion_ci_jeffreys(x)

# Stratified Wilson confidence interval with unequal probabilities

set.seed(1)
rsp <- sample(c(TRUE, FALSE), 100, TRUE)
strata_data <- data.frame(
  "f1" = sample(c("a", "b"), 100, TRUE),
  "f2" = sample(c("x", "y", "z"), 100, TRUE),
  stringsAsFactors = TRUE
)
strata <- interaction(strata_data)
n_strata <- ncol(table(rsp, strata)) # Number of strata

proportion_ci_strat_wilson(
  x = rsp, strata = strata,
  conf.level = 0.90
)

# Not automatic setting of weights
proportion_ci_strat_wilson(
  x = rsp, strata = strata,
  weights = rep(1 / n_strata, n_strata),
  conf.level = 0.90
)

Objects exported from other packages

Description

These objects are imported from other packages. Follow the links below to see their documentation.

cards

ard_attributes, ard_categorical, ard_continuous, ard_dichotomous, ard_missing, ard_total_n

dplyr

%>%, all_of, any_of, contains, ends_with, everything, last_col, matches, num_range, one_of, starts_with, where