Package {BBMBC}

BBMBC: Beta-Binomial Models for Vaccine-Specific Memory B Cell Frequency and Power Calculations

Description

Provides tools to model overdispersed vaccine-specific memory B cell frequencies using Beta-Binomial generalized linear models, specifically designed for analyzing vaccine-induced cellular immune responses. Includes method-of-moments dispersion estimation, likelihood ratio testing across experimental arms, and Monte Carlo simulation frameworks to calculate statistical power and Type I error rates. The methodologies are directly motivated by the analysis of immunology data in 'Vaccination with mRNA-encoded membrane-anchored HIV envelope trimers elicited tier 2 neutralizing antibodies in a phase 1 clinical trial' (Parks et al. 2025) doi:10.1126/scitranslmed.ady6831.

Author(s)

Maintainer: Andrew Shin ashin2@uw.edu

Authors:

• Andrew Shin ashin2@uw.edu

Calculate Statistical Power for Beta-Binomial Models (Parallelized)

Description

Simulates overdispersed cell frequency data under the alternative hypothesis to estimate the statistical power of a Beta-Binomial generalized linear model.

Usage

calc_power_bb(
  n_0 = 20,
  n_1 = 20,
  p_base = 0.005,
  fold_change = 2,
  rho_0 = 0.006,
  rho_1 = 0.006,
  alpha = 0.05,
  min_cells = 1e+05,
  max_cells = 1e+06,
  seed = 2025,
  n_sims = 1000,
  n_cores = min(2, max(1, parallel::detectCores() - 1))
)

Arguments

Value

A list of class power_result containing the estimated statistical power, convergence metrics, and the input parameters used.

Examples

# Evaluate statistical power across a range of sample sizes
sample_sizes <- c(10, 15, 20, 25)
power_results <- numeric(length(sample_sizes))
names(power_results) <- paste0("N=", sample_sizes, "/arm")

for (i in seq_along(sample_sizes)) {
  n <- sample_sizes[i]

  # Run simulation for the current sample size
  # Note: n_sims = 100 is used here for demonstration speed.
  # For formal analysis, use n_sims = 1000 or higher.
  pwr_res <- calc_power_bb(
    n_0 = n, n_1 = n,
    p_base = 0.005,
    fold_change = 2.0,
    rho_0 = 0.006, rho_1 = 0.006,
    n_sims = 100,
    n_cores = 1
  )

  power_results[i] <- pwr_res$power
}

# Print the resulting power curve estimates
print(power_results)

Estimate Overdispersion (Rho) via Method of Moments

Description

Calculates a rapid empirical estimate of the intra-class correlation (overdispersion parameter, rho) for proportion data. This method of moments estimator uses the ratio of the sample variance of the proportions to the theoretical maximum variance of a true binomial distribution with the same mean.

Usage

calc_rho_mom(props, na.rm = TRUE)

Arguments

Value

A numeric value representing the estimated overdispersion parameter (rho). Returns NA if the sample mean is exactly 0 or 1, as the denominator becomes 0.

Examples

# Simulate 100 proportions with a known mean of 0.2 and overdispersion of 0.05
set.seed(123)
p_base <- 0.2
rho_true <- 0.05
shape1 <- p_base * (1 - rho_true) / rho_true
shape2 <- (1 - p_base) * (1 - rho_true) / rho_true

sim_props <- stats::rbeta(100, shape1, shape2)

# Estimate rho empirically
estimated_rho <- calc_rho_mom(sim_props)
print(estimated_rho)

Calculate Type I Error for Beta-Binomial Models

Description

Simulates immunology data under the null hypothesis of equal means (no biological difference in cell frequency) using parallel processing. Handles balanced/unbalanced sample sizes and dynamic overdispersion.

Usage

calc_t1_bb(
  n_0 = 20,
  n_1 = 20,
  p_base = 0.005,
  rho_0 = 0.006,
  rho_1 = 0.006,
  alpha = 0.05,
  min_cells = 1e+05,
  max_cells = 1e+06,
  seed = 2026,
  n_sims = 1000,
  n_cores = min(2, max(1, parallel::detectCores() - 1))
)

Arguments

Value

A list of class t1_error_result containing the estimated Type I error rate, convergence metrics, and the input parameters.

Examples

# Run small simulation example
res <- calc_t1_bb(
  n_0 = 10, n_1 = 10,
  rho_0 = 0.006, rho_1 = 0.006,
  n_sims = 10,
  n_cores = 1
)
print(res$type_1_error_rate)

Beta-Binomial Likelihood Ratio Test for Group Differences

Description

Performs a Likelihood Ratio Test (LRT) using Beta-Binomial models to evaluate whether the underlying proportion of events differs significantly between two groups.

Usage

test_diff_bb(
  data,
  success_col,
  total_col,
  group_col,
  unequal_dispersion = FALSE
)

Arguments

Value

A list of class bb_test_result containing p-value, chi-square statistic, degrees of freedom, log-odds ratio, and its standard error.

Examples

set.seed(2025)
trial_data <- data.frame(
  arm = rep(c("Control", "Vaccine"), each = 15),
  total_bcells = as.integer(stats::runif(30, 100000, 500000))
)
trial_data$target_cells <- ifelse(
  trial_data$arm == "Control",
  stats::rbinom(15, trial_data$total_bcells, stats::rbeta(15, 5, 995)),
  stats::rbinom(15, trial_data$total_bcells, stats::rbeta(15, 10, 990))
)

result <- test_diff_bb(
  data = trial_data,
  success_col = "target_cells",
  total_col = "total_bcells",
  group_col = "arm",
  unequal_dispersion = FALSE
)
print(result$p_value)