norm.score.sen.IxJ: Normal Approximation Sensitivity Analysis for I by J Tables

Description

This function implements normal approximation methods for sensitivity analysis in I by J contingency tables under the generic bias model. It computes asymptotically valid p-values for score test statistics based on the product of treatment and outcome scores, providing rapid analysis for large tables.

Usage

norm.score.sen.IxJ(
  obs.table,
  gamma,
  delta,
  row = "treatment",
  treatment.scores,
  outcome.scores,
  shared_divisor = 1e+06,
  u_space = NULL,
  verbose = FALSE
)

Value

A list containing:

T_obs: The observed test statistic value.
RCT.mean: Mean of the test statistic under RCT (gamma = 0) or (Gamma = 1).
max.mean: Mean of the test statistic under the sensitivity model at maximizer.
RCT.var: Variance of the test statistic under RCT.
max.var: Variance of the test statistic under the sensitivity model at maximizer.
RCT.prob: P-value under RCT (no unmeasured confounding).
max.prob: Maximum p-value across all u-allocations (sensitivity bound).
maximizer: The u-allocation vector that yields max.prob.
treatment.scores: The treatment scores used in the analysis.
outcome.scores: The outcome scores used in the analysis.

Arguments

obs.table: A matrix or table object representing the observed contingency table.
gamma: a nonnegative scalar.
delta: a binary vector to treatment levels. Its length must match the number of treatments (rows of obs.table if row = "treatment", or columns if row = "outcome").
row: A string indicating whether rows represent "outcome" or "treatment". Must be either "outcome" or "treatment". Default is "treatment".
treatment.scores: A numeric vector of scores for treatments. Must be monotone (either increasing or decreasing). Higher scores typically indicate more intense treatments. Length must equal the number of treatments.
outcome.scores: A numeric vector of scores for outcomes. Must be monotone (either increasing or decreasing). Higher scores typically indicate better outcomes. Length must equal the number of outcomes.
shared_divisor: Numeric value used for numerical stability in calculations. Default is 1e6.
u_space: A numeric matrix where each row is a candidate u_allocation. If NULL (default), corner allocations are generated automatically for tables with J <= 5 outcomes.
verbose: Logical; if TRUE, prints progress messages including the current u-allocation and p-value at each step. Default is FALSE.

Details

For an I by J table, the test statistic is a weighted sum of cell counts where weights are products of treatment and outcome scores: \(T = \sum w_i v_j N_{ij}\) across all cells.

The method computes:

Mean and variance of the test statistic under the generic bias model
Standardized z-scores assuming asymptotic normality
the one-sided upper tailed probability

When u_space is not provided, the function automatically generates corner u allocations which often contain the worst-case scenarios for sensitivity analysis.

Examples

Run this code

# 2 by 3 table example with ordinal scores
obs.table <- matrix(c(10, 20, 30, 15, 25, 10), nrow = 2, byrow = TRUE)
treatment.scores <- c(0, 1)    # Control vs Treatment
outcome.scores <- c(0, 1, 2)   # Ordinal outcomes

result <- norm.score.sen.IxJ(obs.table = obs.table,
                      gamma = 0.5,
                      delta = c(0, 1),
                      treatment.scores = treatment.scores,
                      outcome.scores = outcome.scores
                      )

# 3 by 3 table with customized scores
obs.table <- matrix(data=c(10,30,10,14,15,24,4,5,15), nrow = 3)
treatment.scores <- c(0, 0.5, 1)  # Three treatment levels
outcome.scores <- c(0, 1, 2)   # three outcome levels

result <- norm.score.sen.IxJ(obs.table = obs.table,
                      gamma = 0.5,
                      delta = c(0, 0, 1),
                      treatment.scores = treatment.scores,
                      outcome.scores = outcome.scores
                      )