sensitivityIxJ (version 0.1.5)

sampling.general.sen.IxJ: Monte Carlo Sensitivity Analysis for General Permutation-Invariant Test Statistics in I by J Tables

Description

This function implements a sampling-based approach to sensitivity analysis for general (permutation-invariant) test statistics in I by J contingency tables under the generic bias model. It uses Sequential Importance Sampling (SIS) from Eisinger and Chen (2017) to approximate p-values when exact enumeration is computationally infeasible.

Usage

sampling.general.sen.IxJ(
  obs.table,
  gamma,
  delta,
  row = "treatment",
  mc.iteration = 5000,
  transform.fun,
  verbose = FALSE,
  u_space = NULL
)

Value

A list containing:

rct.prob

Estimated probability under RCT (all u-allocations zero)

max.prob

Maximum estimated probability across all u-allocations

maximizer

The u-allocation vector yielding max.prob

obs.stat

Observed test statistic value from transform.fun

obs.table

The input observed table

gamma

Extracted gamma value from the generic bias model

delta

The delta vector

Arguments

obs.table

A matrix or table object representing the observed contingency table.

gamma

a nonnegative scalar

delta

A binary vector with no more than two unique values, corresponding to treatment levels. The length must match the number of treatments (rows if row = "treatment", columns if row = "outcome").

row

A string indicating whether rows represent "outcome" or "treatment". Must be either "outcome" or "treatment". Default is "treatment".

mc.iteration

Integer specifying the number of Monte Carlo iterations for each u-allocation. Higher values increase accuracy but require more computation time. Default is 5000.

transform.fun

A user-defined function that takes a contingency table and returns a numeric test statistic. This function should be permutation-invariant within treatment groups.

verbose

Logical flag indicating whether to print progress messages showing current u-allocation and estimated probabilities. Default is FALSE.

u_space

Optional matrix where each row represents a candidate u-allocation. If NULL, a default set of corner allocations is generated. Each row should have length equal to the number of outcomes.

Details

This function performs Monte Carlo sensitivity analysis for arbitrary test statistics that are permutation-invariant. Unlike the score test version, this function can handle any user-defined test statistic through the transform.fun parameter.

The algorithm:

1. Generates tables using Sequential Importance Sampling (SIS)

2. Evaluates the test statistic on each sampled table

3. Estimates p-values using importance weights

4. Searches over u-allocations to find the maximum p-value

When u_space is not provided, the function generates default corner allocations that explore extreme cases in the unmeasured confounder space.

References

Eisinger, R. D., & Chen, Y. (2017). Sampling for Conditional Inference on Contingency Tables. Journal of Computational and Graphical Statistics, 26(1), 79–87.

See Also

exact.general.sen.IxJ for exact computation when feasible, sampling.score.sen.IxJ for score tests with ordinal data,

Examples

# \donttest{
# Example with custom test statistic emphasizing corner cells
obs.table <- matrix(c(10, 5, 8, 12), ncol = 2, byrow = TRUE)

# Define test statistic: sum of diagonal elements
diag_stat <- function(tb) {
  sum(diag(tb))
}

# Run sensitivity analysis
result <- sampling.general.sen.IxJ(
  obs.table = obs.table,
  gamma = 0.5,
  delta = c(0, 1),
  transform.fun = diag_stat,
  mc.iteration = 5000,
  verbose = TRUE
)

# Custom u-space example
custom_u <- matrix(c(0, 0,
                    5, 0,
                    0, 8,
                    5, 8), ncol = 2, byrow = TRUE)

result_custom <- sampling.general.sen.IxJ(
  obs.table = obs.table,
  gamma = 0.5,
  delta = c(0, 1),
  transform.fun = diag_stat,
  u_space = custom_u
)
# }