Randomization-based Confidence Intervals — InferenceRandCI • EDI: Experimental Design and Inference

Abstract class for randomization-based confidence interval inference.

References

Tsiatis, A. A. (1990). Estimating regression parameters using linear rank tests for censored data. The Annals of Statistics, 18(1), 354-372, doi:10.1214/aos/1176347504 . Wei, L. J., Ying, Z., and Lin, D. Y. (1990). Linear regression analysis of censored survival data based on rank tests. Biometrika, 77(4), 845-851, doi:10.1093/biomet/77.4.845 . Jin, Z., Lin, D. Y., Wei, L. J., and Ying, Z. (2003). Rank-based inference for the accelerated failure time model. Biometrika, 90(2), 341-353, doi:10.1093/biomet/90.2.341 .

Super classes

Inference -> InferenceRand -> InferenceRandCI

Methods

Public methods

InferenceRandCI$compute_rand_two_sided_pval()
InferenceRandCI$compute_rand_confidence_interval()
InferenceRandCI$clone()

+ inherited public methods from InferenceRand

+ inherited public methods from Inference

`InferenceRandCI$compute_rand_two_sided_pval()`

Compute a randomization-based two-sided p-value for the treatment effect.

Usage

InferenceRandCI$compute_rand_two_sided_pval(
  r = 501,
  delta = 0,
  transform_responses = "none",
  na.rm = TRUE,
  show_progress = TRUE,
  permutations = NULL,
  type = NULL,
  args_for_type = NULL,
  zero_one_logit_clamp = .Machine$double.eps
)

Arguments

r: Number of randomization vectors.
delta: Null treatment effect value.
transform_responses: Response transformation to apply during the test. For survival responses the default "log" multiplies the recorded times of the units treated under each reference allocation by $e^\delta$, event and censoring times alike, with censoring indicators unchanged – the rank-based AFT residual construction (Tsiatis 1990; Wei, Ying and Lin 1990; Jin, Lin, Wei and Ying 2003); see compute_rand_confidence_interval() for the assumptions.
na.rm: Whether to remove non-finite simulated statistics.
show_progress: Whether to show progress.
permutations: Optional pre-generated assignment draws.
type: Optional incidence-specific exact randomization type.
args_for_type: Optional arguments keyed by type.
zero_one_logit_clamp: The clamping amount for exact 0 and 1 values when logging

Returns

A two-sided p-value.

`InferenceRandCI$compute_rand_confidence_interval()`

Computes a randomization-based confidence interval by inverting the randomization test: the interval is the set of $\delta$ for which the two-sided randomization p-value of the sharp null "treatment effect $= \delta$" is at least alpha. For each candidate $\delta$ the control potential outcomes are first imputed under that sharp null by removing the hypothesised effect from the units that were actually treated; then, for each reference allocation $w_b$, the effect is applied to the units treated under $w_b$ — on the response type's scale (additive for continuous responses, multiplicative $e^\delta$ for counts and survival times, a logit shift for proportions) — the estimator is recomputed, and the observed estimate is compared with the resulting reference distribution. This is the impute-then-permute construction of Rosenbaum (2002, ch. 2) and Imbens and Rubin (2015, ch. 5): $y_{sim} = y - \delta w_{obs} + \delta w_b$ on the additive scale. For mean-difference, OLS, Lin, and verified KK OLS one-likelihood estimators, EDI computes one full $\delta=0$ null distribution and reuses its exact per-permutation affine shifts throughout the CI search; other estimators retain the general refit-at-each-$\delta$ path.

Survival responses. The sharp null is an accelerated-failure-time (AFT) effect: for units treated under $w_b$ the recorded time is multiplied by $e^\delta$ — both event times and censoring times — and the censoring indicator is carried over unchanged. Equivalently, the test is run on the residual times $\log y_i - \delta w_i$ of every observation, censored or not. This is the residual construction underlying rank-based inference for the AFT model: Tsiatis (1990) shows that linear rank statistics computed on these residuals have mean zero at the true $\delta$ under independent censoring, even though the residual censoring distribution then depends on treatment; Wei, Ying and Lin (1990) invert exactly this family of tests to obtain confidence intervals for AFT regression coefficients; Jin, Lin, Wei and Ying (2003) give the modern estimation and inference machinery for the same model. The alternative of rescaling only the event times and re-deriving the censoring indicator is not identifiable, because a unit's censoring time is unobserved whenever its event was. Two assumptions therefore apply: (i) independent censoring ($C \perp T \mid w$) for the asymptotic validity of the inverted test, and (ii) for the finite-sample exactness of the permutation version specifically, that censoring times are on the same accelerated clock as event times ($C_i(1) = e^\delta C_i(0)$), which is plausible for health-driven dropout and does not hold for calendar-time administrative censoring; under administrative censoring the interval is asymptotically, not exactly, valid. Because $\delta$ is a log time-ratio, this construction is coherent only for classes whose estimand is on that scale (the Weibull AFT, marginal Weibull, Weibull-frailty, and rank-regression classes); classes whose estimand is a log hazard ratio cannot invert an AFT shift without a parametric link between the two scales and refuse this method (the six classes in EDI_LOG_HAZARD_RATIO_INFERENCE_CLASSES — the Cox family — which also do not advertise the randomization_ci capability, so InferenceSuite never offers it for them; their randomization p-value and randomization-bootstrap CI are unaffected).

Usage

InferenceRandCI$compute_rand_confidence_interval(
  alpha = 0.05,
  r = 501,
  pval_epsilon = 0.005,
  show_progress = TRUE,
  type = NULL,
  args_for_type = NULL,
  ci_search_control = NULL
)

Arguments

alpha: Significance level.
r: Number of randomization vectors.
pval_epsilon: Bisection tolerance.
show_progress: Show progress.
type: Optional incidence-specific exact randomization type.
args_for_type: Optional arguments keyed by type.
ci_search_control: Optional control list for randomization-CI search. Supported entries are fallback, seed, max_radius_se_mult (default 25), max_radius_scale_mult (default 6), max_expansions (default 7), seed_boot_B, Monte Carlo settings mc_enable, mc_batch_size, mc_min_draws, and mc_conf_level, midpoint-cache settings pval_cache_enable and pval_cache_resolution, and model-fit reuse settings fit_warm_start_enable and fit_reuse_factorizations. Set mc_enable = FALSE to force full enumeration of all requested randomization draws. The search radius is max(max_radius_se_mult * se_guess, max_radius_scale_mult * sd(y)). When the randomization p-value does not drop below alpha anywhere within the search radius (e.g. the test has low power or the design has few unique permutations), a conservative CI bound is returned at the search boundary rather than NA. This guarantees a valid (though possibly wide) interval. Each such event emits a message() and increments the private field rand_ci_conservative_count for monitoring. high_precision_confirm (default TRUE) re-checks each converged bound with one full-enumeration (no early stopping) p-value evaluation and, only if that disagrees with the early-stopped bisection's conclusion, spends a short additional full-precision re-bisection to correct it – a final high-precision confirmation pass that catches sequential-Monte-Carlo early-stopping noise the cheap bisection has no way to notice on its own; see high_precision_confirm_and_refine_ci_bound()'s own comment for the full rationale and R/package_metadata/new_feature_plans/ for the deeper, not-yet-implemented redesign (anytime-valid confidence sequences) this pass is a pragmatic stopgap for.

Returns

Randomization CI. Bounds may be conservative (wider than necessary) when the p-value inversion cannot be completed within the search radius; see ci_search_control for details.

`InferenceRandCI$clone()`

The objects of this class are cloneable with this method.

Usage

InferenceRandCI$clone(deep = FALSE)

Arguments

deep: Whether to make a deep clone.