Skip to contents

Institutional Categorical Hypothesis Test for gtsummary and Batch Testing

Source: R/cbe_exact2x2.R
test_categorical.Rd

Standard categorical hypothesis testing engine conforming to the CBE statistical protocol. Operates as a drop-in custom test for add_p or as a standalone batch testing engine with optional furrr parallelization.

Usage

test_categorical(
  data,
  variable = NULL,
  by = NULL,
  test = c("auto", "exact", "chisq", "fisher"),
  correct = FALSE,
  B = 2000L,
  simulate.p.value = NULL,
  parallel = FALSE,
  n_chunks = 4L,
  group = NULL,
  type = NULL,
  test.args = NULL,
  adj.vars = NULL,
  conf.level = NULL,
  tbl = NULL,
  continuous_variable = NULL,
  ...
)

Arguments

data

Data frame supplied directly or by gtsummary.

variable

Character string column name for the feature being tested, a character vector of variable names for batch testing, or a two-sided formula of the form response ~ grouping_var or var1 + var2 ~ grouping_var. If NULL, all categorical/factor columns in data (excluding by) are tested.

by

Character string column name for the stratifying/grouping variable. Can be omitted when variable is a formula.

test

Hypothesis test engine: "auto" (default CBE hierarchy), "exact" (force Central Fisher exact test for 2x2 or simulated Fisher for RxC), "chisq" (force Pearson's Chi-squared test via chisq.test), or "fisher" (force fisher.test).

correct

Logical; whether to apply continuity correction when test = "chisq" (default FALSE following CBE standard protocol).

B

Integer; number of Monte Carlo replicates when Fisher's exact test with simulation is triggered (default 2000L).

simulate.p.value

Optional logical; if specified, explicitly enables or disables Monte Carlo simulation for Fisher's test. If NULL (default), auto-triggers simulation when table total exceeds 500 or any dimension exceeds 2.

parallel

Logical; whether to use furrr for parallel execution (for batch testing across multiple variables or chunking high-B simulations). Requires setting a plan beforehand.

n_chunks

Integer; number of chunks to partition B into when running parallel simulations with B >= 10000 (default 4L).

group, type, test.args, adj.vars, conf.level, tbl, continuous_variable

Unused; accepted and ignored so this function satisfies gtsummary's custom-test calling convention (see tests) without those arguments leaking into ... and reaching chisq.test/ fisher.test, neither of which accepts extra named arguments.

...

Additional arguments passed to exact2x2 or fisher.test.

Value

When variable is a single string (such as when called by gtsummary), returns a one-row tibble compliant with gtsummary's custom test specification (p.value, statistic, parameter, method). When variable is a vector or NULL, returns a tidy tibble of test results across all evaluated variables.

Details

The function follows a rigorous 4-rule hierarchy:

  1. 2x2 table with zero cell: Uses Central Fisher's exact test with mid-p adjustment (exact2x2 with midp = TRUE) to avoid extreme conservatism.

  2. 2x2 table without zero cell: Uses Central Fisher's exact test (exact2x2 with midp = FALSE).

  3. RxC table with sparse counts: If any expected cell count is less than 5, runs Fisher's exact test with Monte Carlo simulation (fisher.test with simulate.p.value = TRUE).

  4. RxC table with adequate counts: If all expected cell counts are at least 5, runs Pearson's Chi-squared test without continuity correction (chisq.test with correct = FALSE).

Examples

library(gtsummary)
trial |>
  tbl_summary(by = trt, include = c(response, death, grade)) |>
  add_p(test = all_categorical() ~ test_categorical) |>
  separate_p_footnotes()



  
Characteristic
      Drug A

N = 981		
      Drug B

N = 1021		
      p-value
    
Tumor Response
28 (29%)
33 (34%)
0.62
    Unknown
3
4

Patient Died
52 (53%)
60 (59%)
0.52
Grade




0.93
    I
35 (36%)
33 (32%)

    II
32 (33%)
36 (35%)

    III
31 (32%)
33 (32%)

1 n (%)
    
2 Central Fisher’s Exact Test
    
3 Pearson’s Chi-squared test
    

# Standalone batch testing across multiple features:
test_categorical(trial, variable = c("response", "death", "grade"), by = "trt")
#> # A tibble: 3 × 7
#>   variable by    p.value p.formatted statistic parameter method                 
#>   <chr>    <chr>   <dbl> <chr>           <dbl>     <dbl> <chr>                  
#> 1 response trt     0.637 p = 0.637       1.21         NA Central Fisher's Exact…
#> 2 death    trt     0.498 p = 0.498       1.26         NA Central Fisher's Exact…
#> 3 grade    trt     0.871 p = 0.871       0.277         2 Pearson's Chi-squared …

# Formula interface:
test_categorical(trial, response ~ trt)
#> # A tibble: 1 × 3
#>   p.value statistic method                     
#>     <dbl>     <dbl> <chr>                      
#> 1   0.637      1.21 Central Fisher's Exact Test