R/statistics-help.R

In R4VN: Health Data Analysis and Publication-Ready Reporting

#' Immediate Contingency Tables
#'
#' Creates an immediate contingency table from typed counts. The immediate mode
#' uses the same calculation engine as the corresponding R4VN analyses when values are supplied
#' directly, for example `tab(sex, outcome, data = dat, chi = TRUE)`.
#'
#' @param ... Numeric row vectors, a matrix, or a table. For `anovai()`, each
#'   argument is a group summary in the form `c(n, mean, sd)`.
#' @param row.names,col.names Optional row and column labels.
#' @param percent Percentage denominator: `"none"`, `"row"`, `"col"`, or
#'   `"total"`.
#' @param row,col,cell,total Logical shortcuts for row, column, or total-cell
#'   percentages. Only one may be `TRUE`.
#' @param exp Show expected counts.
#' @param chi Show Pearson's chi-squared test.
#' @param fisher Show Fisher's exact test.
#' @param lr Show the likelihood-ratio chi-squared test.
#' @param residual Show Pearson residuals.
#' @param adjresidual Show adjusted residuals.
#' @param correct Apply Yates's correction for a 2 by 2 Pearson test.
#' @param digits Number of decimal places for estimates.
#' @param p_digits Number of decimal places for p-values.
#' @param workspace Workspace passed to [stats::fisher.test()].
#' @param show Logical; open the formatted result in the Viewer. Default `TRUE`.
#' @param console Logical; also print the traditional text result in the Console. Default `FALSE`.
#'
#' @return Invisibly returns an object of class `r4vn_stat`.
#' @examples
#' tabi(c(2, 3), c(5, 6), c(8, 9), row = TRUE,
#'      exp = TRUE, chi = TRUE, fisher = TRUE)
#' @name tabi
NULL

#' Student and Welch t Tests
#'
#' `ttesti()` calculates one- or two-sample t tests from summary statistics.
#' `ttest()` performs the same analysis from variables and reports group
#' sample size, mean, standard error, standard deviation, and confidence interval.
#' `ttest(..., effect = TRUE)` additionally reports Cohen's d and Hedges' g.
#' With `by = vars(province, sex, treatment)`, province and sex are nested
#' strata and treatment is the innermost two-group comparison.
#'
#' @usage
#' ttesti(
#'   n1, mean1, sd1, n2 = NULL, mean2 = NULL, sd2 = NULL, mu = 0, equal = FALSE,
#'   paired = FALSE, r = NULL, alternative = c("two.sided", "less", "greater"),
#'   level = 0.95, digits = 3, p_digits = 3, show = TRUE, console = FALSE
#' )
#' @usage
#' ttest(
#'   x, y = NULL, by = NULL, data = NULL, mu = 0, equal = FALSE, paired = FALSE,
#'   alternative = c("two.sided", "less", "greater"), level = 0.95,
#'   effect = FALSE, digits = 3, p_digits = 3, show = TRUE, console = FALSE
#' )
#'
#' @param n1,mean1,sd1 Sample size, mean, and standard deviation for group 1.
#' @param n2,mean2,sd2 Optional sample size, mean, and standard deviation for group 2.
#' @param mu Null mean or null mean difference.
#' @param equal Use the equal-variance two-sample t test.
#' @param paired Perform a paired analysis.
#' @param r Correlation between paired measurements when only summaries are available.
#' @param alternative Alternative hypothesis: `"two.sided"`, `"less"`, or `"greater"`.
#' @param level Confidence level as a proportion.
#' @param digits,p_digits Decimal places for estimates and p-values.
#' @param show Logical; open the formatted result in the Viewer. Default `TRUE`.
#' @param console Logical; also print the traditional text result in the Console. Default `FALSE`.
#' @param x,y Numeric variables. `y` is optional.
#' @param by Optional two-level grouping variable. `by = vars(a, b, group)`
#'   performs the test within nested `a > b` strata using `group` as the
#'   innermost comparison.
#' @param data Data frame. If `NULL`, the active data set is used.
#' @param effect Logical; for `ttest()`, add standardized effect sizes.
#'
#' @return Invisibly returns an object of class `r4vn_stat`.
#' @examples
#' ttesti(40, 12, 3, mu = 10)
#' ttesti(40, 12, 3, 35, 14, 4)
#' \donttest{
#' d <- data.frame(score = c(10,12,11,18,17,20,9,13,12,19,21,18),
#'                 treatment = rep(c("Control","Intervention"), each = 6),
#'                 province = rep(c("A","B"), each = 3, times = 2))
#' ttest(score, by = treatment, data = d, effect = TRUE)
#' ttest(score, by = vars(province, treatment), data = d, effect = TRUE)
#' }
#' @name ttest
NULL

#' Tests of Standard Deviations and Variances
#'
#' Performs a one-sample chi-squared variance test or a two-sample F test.
#'
#' @param n1,sd1 Sample size and standard deviation for sample 1.
#' @param n2,sd2 Optional sample size and standard deviation for sample 2.
#' @param sd0 Null standard deviation for a one-sample test.
#' @param alternative Alternative hypothesis.
#' @param level Confidence level.
#' @param digits,p_digits Decimal places for estimates and p-values.
#' @param show Logical; open the formatted result in the Viewer. Default `TRUE`.
#' @param console Logical; also print the traditional text result in the Console. Default `FALSE`.
#' @param x,y Numeric variables.
#' @param by Optional two-level grouping variable.
#' @param data Data frame. If `NULL`, active data is used.
#'
#' @return Invisibly returns an object of class `r4vn_stat`.
#' @examples
#' sdtesti(40, 3, sd0 = 2.5)
#' sdtesti(40, 3, 35, 4)
#' @name sdtest
NULL

#' One-way ANOVA with Bartlett Test
#'
#' `anovai()` reconstructs one-way ANOVA from `c(n, mean, sd)` summaries.
#' `anova()` analyzes a numeric variable by a grouping variable. Bartlett's test
#' of equal variances is included by default. When the first argument is a fitted
#' model, the call is delegated to [stats::anova()]. For one-way ANOVA,
#' `posthoc` can request Tukey, Games-Howell, Scheffe, Bonferroni, or other
#' multiplicity-adjusted pairwise comparisons. Eta-squared and omega-squared remain reported by the
#' ANOVA engine. Hierarchical `by = vars(...)` is supported for data-based ANOVA.
#'
#' @usage
#' anovai(
#'   ..., group.names = NULL, bartlett = TRUE, level = 0.95,
#'   posthoc = c("none", "tukey", "games-howell", "scheffe", "bonferroni", "pairwise"),
#'   adjust = "holm", digits = 3, p_digits = 3, show = TRUE, console = FALSE
#' )
#' @usage
#' anova(
#'   object, ..., by = NULL, data = NULL, bartlett = TRUE, level = 0.95,
#'   posthoc = c("none", "tukey", "games-howell", "scheffe", "bonferroni", "pairwise"),
#'   adjust = "holm", digits = 3, p_digits = 3, show = TRUE, console = FALSE
#' )
#'
#' @param ... For `anovai()`, group summaries `c(n, mean, sd)`. For a fitted
#'   model, additional objects or arguments passed to [stats::anova()].
#' @param group.names Optional names for the summarized groups.
#' @param bartlett Include Bartlett's test of equal variances.
#' @param level Confidence level for group means.
#' @param digits,p_digits Decimal places for estimates and p-values.
#' @param show Logical; open the formatted result in the Viewer. Default `TRUE`.
#' @param console Logical; also print the traditional text result in the Console. Default `FALSE`.
#' @param object Numeric outcome variable or a fitted model object.
#' @param by Grouping variable for one-way ANOVA. `by = vars(region, sex, group)`
#'   uses region and sex as nested strata and group as the ANOVA factor.
#' @param data Data frame. If `NULL`, active data is used.
#' @param posthoc Post-hoc method: `"none"`, `"tukey"`, `"games-howell"`,
#'   `"scheffe"`, `"bonferroni"`, or `"pairwise"`. Games-Howell is useful when equal-variance
#'   assumptions are doubtful.
#'   `posthoc = "bonferroni"` provides Bonferroni-adjusted p-values and
#'   simultaneous confidence intervals.
#' @param adjust Multiplicity adjustment used by `posthoc = "pairwise"`; any
#'   method accepted by [stats::p.adjust()] may be used.
#'
#' @return A `r4vn_stat` object for one-way ANOVA, or the ordinary result from
#'   [stats::anova()] for fitted models.
#' @examples
#' anovai(c(n = 20, mean = 10, sd = 2),
#'        c(n = 25, mean = 15, sd = 4),
#'        c(n = 18, mean = 13, sd = 3), posthoc = "bonferroni")
#' \donttest{
#' d <- data.frame(score = c(10,12,11,18,17,20,25,24,27),
#'                 treatment = factor(rep(c("A","B","C"), each = 3)))
#' anova(score, by = treatment, data = d, posthoc = "games-howell")
#' }
#' @name anova_r4vn
NULL

#' Proportions and Tests of Proportions
#'
#' Immediate and data-based commands for confidence intervals, exact binomial
#' tests, and one- or two-sample z tests of proportions. `prtest()` and
#' `prtesti()` support a one-sample null proportion through `p0`; `prtest()`
#' also supports hierarchical grouping.
#'
#' @usage
#' propi(
#'   events, total, p0 = NULL, method = c("all", "exact", "wilson", "wald"),
#'   alternative = c("two.sided", "less", "greater"), level = 0.95, digits = 3,
#'   p_digits = 3, show = TRUE, console = FALSE
#' )
#' @usage
#' bitesti(
#'   total, events, p = 0.5, alternative = c("two.sided", "less", "greater"),
#'   level = 0.95, digits = 3, p_digits = 3, show = TRUE, console = FALSE
#' )
#' @usage
#' prtesti(
#'   events1, n1, events2 = NULL, n2 = NULL, p0 = NULL,
#'   alternative = c("two.sided", "less", "greater"), level = 0.95, digits = 3,
#'   p_digits = 3, show = TRUE, console = FALSE
#' )
#' @usage
#' prop(
#'   x, data = NULL, event = NULL, p0 = NULL,
#'   method = c("all", "exact", "wilson", "wald"),
#'   alternative = c("two.sided", "less", "greater"), level = 0.95, digits = 3,
#'   p_digits = 3, show = TRUE, console = FALSE
#' )
#' @usage
#' bitest(
#'   x, p = 0.5, data = NULL, event = NULL,
#'   alternative = c("two.sided", "less", "greater"), level = 0.95, digits = 3,
#'   p_digits = 3, show = TRUE, console = FALSE
#' )
#' @usage
#' prtest(
#'   x, by = NULL, data = NULL, event = NULL, p0 = NULL,
#'   alternative = c("two.sided", "less", "greater"), level = 0.95, digits = 3,
#'   p_digits = 3, show = TRUE, console = FALSE
#' )
#'
#' @param events,total Number of events and total observations.
#' @param p0 Null proportion.
#' @param method Confidence interval method: `"all"`, `"exact"`, `"wilson"`,
#'   or `"wald"`.
#' @param alternative Alternative hypothesis.
#' @param level Confidence level.
#' @param digits,p_digits Decimal places for estimates and p-values.
#' @param show Logical; open the formatted result in the Viewer. Default `TRUE`.
#' @param console Logical; also print the traditional text result in the Console. Default `FALSE`.
#' @param x Binary variable.
#' @param data Data frame. If `NULL`, active data is used.
#' @param event Event level. The last observed level is used by default.
#' @param p Null probability for `bitesti()` and `bitest()`.
#' @param events1,n1 Events and total in sample 1.
#' @param events2,n2 Optional events and total in sample 2.
#' @param by Optional two-level grouping variable. For `prtest()`,
#'   `by = vars(region, sex, group)` performs the two-proportion comparison
#'   inside region and sex strata.
#'
#' @return Invisibly returns an object of class `r4vn_stat`.
#' @examples
#' propi(32, 100, p0 = .25)
#' bitesti(40, 23, p = 0.5)
#' prtesti(30, 100, p0 = .20)
#' prtesti(30, 100, 20, 80)
#' \donttest{
#' d <- data.frame(case = c(rep(1,30), rep(0,70), rep(1,20), rep(0,60)),
#'                 group = rep(c("A","B"), c(100,80)))
#' prtest(case, data = d, p0 = .25, event = 1)
#' prtest(case, by = group, data = d, event = 1)
#' }
#' @name proportion_tests
NULL

#' Confidence Intervals from Summaries or Variables
#'
#' Calculates confidence intervals for means, proportions, and variances.
#'
#' @param n Sample size.
#' @param mean,sd Mean and standard deviation.
#' @param events Number of events for a proportion.
#' @param variance Sample variance.
#' @param type `"auto"`, `"mean"`, `"proportion"`, or `"variance"`.
#' @param method Proportion confidence interval method.
#' @param level Confidence level.
#' @param digits Decimal places.
#' @param show Logical; open the formatted result in the Viewer. Default `TRUE`.
#' @param console Logical; also print the traditional text result in the Console. Default `FALSE`.
#' @param x Variable to analyze.
#' @param data Data frame. If `NULL`, active data is used.
#' @param event Event level for a binary variable.
#'
#' @return Invisibly returns an object of class `r4vn_stat`.
#' @examples
#' cii(50, mean = 10, sd = 2)
#' cii(100, events = 45, type = "proportion", method = "wilson")
#' @name ci_r4vn
NULL

#' Standardized Mean Differences
#'
#' Calculates Cohen's d, Hedges' g, and Glass's delta.
#'
#' @param n1,mean1,sd1 Summary statistics for group 1.
#' @param n2,mean2,sd2 Summary statistics for group 2.
#' @param level Confidence level.
#' @param digits Decimal places.
#' @param show Logical; open the formatted result in the Viewer. Default `TRUE`.
#' @param console Logical; also print the traditional text result in the Console. Default `FALSE`.
#' @param x Numeric variable.
#' @param by Two-level grouping variable.
#' @param data Data frame. If `NULL`, active data is used.
#'
#' @return Invisibly returns an object of class `r4vn_stat`.
#' @examples
#' esizei(40, 12, 3, 35, 14, 4)
#' @name esize
NULL

#' z Tests with Known Standard Deviations
#'
#' Performs one- or two-sample z tests when population standard deviations are known.
#'
#' @param n1,mean1,sd1 Summary statistics for sample 1.
#' @param n2,mean2,sd2 Optional summary statistics for sample 2.
#' @param mu Null mean or mean difference.
#' @param alternative Alternative hypothesis.
#' @param level Confidence level.
#' @param digits,p_digits Decimal places for estimates and p-values.
#' @param show Logical; open the formatted result in the Viewer. Default `TRUE`.
#' @param console Logical; also print the traditional text result in the Console. Default `FALSE`.
#' @param x,y Numeric variables.
#' @param sigma1,sigma2 Known population standard deviations.
#' @param by Optional two-level grouping variable.
#' @param data Data frame. If `NULL`, active data is used.
#'
#' @return Invisibly returns an object of class `r4vn_stat`.
#' @examples
#' ztesti(100, 52, 10, mu = 50)
#' @name ztest
NULL

#' Epidemiological 2 by 2 Analysis
#'
#' `epii()` analyzes typed 2 by 2 counts. `epi()` analyzes binary outcome and
#' exposure variables. With `by`, stratum-specific estimates, a Mantel-Haenszel
#' common odds ratio, a pooled risk ratio, homogeneity, and interaction tests are
#' displayed. The stratified output also reports the crude-versus-Mantel-Haenszel
#' OR difference as both `100*(ORcrude-ORMH)/ORMH` and
#' `100*(ORcrude-ORMH)/ORcrude`. `cci()`/`cc()` and `csi()`/`cs()` are familiar aliases.
#'
#' The 2 by 2 layout is exposure by outcome: `a` exposed cases, `b` exposed
#' noncases, `c` unexposed cases, and `d` unexposed noncases.
#'
#' @param a,b,c,d Cell counts of a 2 by 2 table. `a` may also be a 2 by 2 matrix.
#' @param by For `epii()`, a list of 2 by 2 tables or a 2 by 2 by K array. For
#'   `epi()`, an optional stratification variable. Hierarchical syntax is
#'   supported: `by = vars(province, sex)` repeats the epidemiological analysis
#'   within province and uses sex as the innermost Mantel-Haenszel stratum. With
#'   three or more variables, every variable before the final one is an ordered
#'   outer stratum and the final variable is the MH stratification variable.
#' @param level Confidence level.
#' @param correction Continuity correction used for log-scale confidence
#'   intervals when a cell is zero.
#' @param digits,p_digits Decimal places for estimates and p-values.
#' @param show Logical; open the formatted result in the Viewer. Default `TRUE`.
#' @param console Logical; also print the traditional text result in the Console. Default `FALSE`.
#' @param outcome Binary outcome variable.
#' @param exposure Binary exposure variable.
#' @param data Data frame. If `NULL`, active data is used.
#' @param event Outcome event level; defaults to the last observed level.
#' @param exposed Exposure level; defaults to the last observed level.
#' @param ... Additional arguments passed to `epii()` by immediate aliases.
#'
#' @return Invisibly returns an object of class `r4vn_stat`.
#' @examples
#' epii(40, 10, 20, 30)
#' epii(by = list(
#'   Female = c(12, 18, 8, 32),
#'   Male = c(28, 12, 12, 18)
#' ))
#' @name epi
NULL

#' Matched Case-control Analysis
#'
#' Calculates the matched odds ratio from the discordant pairs and an exact
#' conditional confidence interval and p-value.
#'
#' @param a,b,c,d Matched-pair table cells. The matched odds ratio is `b/c`.
#' @param level Confidence level.
#' @param digits,p_digits Decimal places for estimates and p-values.
#' @param show Logical; open the formatted result in the Viewer. Default `TRUE`.
#' @param console Logical; also print the traditional text result in the Console. Default `FALSE`.
#' @param case,control Paired binary exposure variables for cases and controls.
#' @param data Data frame. If `NULL`, active data is used.
#' @param exposed Exposure level; defaults to the last observed level.
#'
#' @return Invisibly returns an object of class `r4vn_stat`.
#' @examples
#' mcci(20, 14, 5, 31)
#' @name mcc
NULL

#' Incidence-rate Comparison
#'
#' Compares incidence rates from typed cases and person-time or from variables.
#'
#' @param cases.exposed,cases.unexposed Number of cases in exposed and unexposed groups.
#' @param time.exposed,time.unexposed Person-time in exposed and unexposed groups.
#' @param level Confidence level.
#' @param digits,p_digits Decimal places for estimates and p-values.
#' @param show Logical; open the formatted result in the Viewer. Default `TRUE`.
#' @param console Logical; also print the traditional text result in the Console. Default `FALSE`.
#' @param cases Nonnegative case-count variable.
#' @param exposure Binary exposure variable.
#' @param time Nonnegative person-time variable.
#' @param data Data frame. If `NULL`, active data is used.
#' @param exposed Exposure level; defaults to the last observed level.
#'
#' @return Invisibly returns an object of class `r4vn_stat`.
#' @examples
#' iri(41, 15, 28010, 19017)
#' @name ir
NULL