Mean-Difference IVWC Inference for KK Matching-on-the-Fly Designs

Fits a compound (inverse-variance-weighted combination, "IVWC") mean-difference estimator of the treatment effect for continuous responses under a DesignSeqOneByOne-family KK matching-on-the-fly design (see DesignSeqOneByOneKK14 and DesignSeqOneByOneKK21). Such a design produces two structurally different kinds of subjects: subjects successfully matched into pairs during the sequential design, and unmatched "reservoir" subjects randomized independently. This estimator combines both: $$\hat\beta_T = w^* \bar d + (1 - w^*)\, \bar r, \qquad w^* = \frac{\widehat{\mathrm{Var}}(\bar r)}{\widehat{\mathrm{Var}}(\bar r) + \widehat{\mathrm{Var}}(\bar d)},$$ where \(\bar d\) is the mean within-pair (treated minus control) difference among matched subjects and \(\bar r\) is the treated-minus-control difference in means among reservoir subjects, weighted inversely by their estimated variances (see $compute_asymp_confidence_interval() for the full variance formula and the fallback behavior when only one of the two sub-estimates is usable). Inference is Wald-only: this class has no likelihood tier (likelihood_tier = "none") and provides asymptotic Wald, randomization, and bootstrap (including Bayesian bootstrap) confidence intervals and p-values, but no score/likelihood-ratio/gradient tests.

Legacy status

Legacy class. Not fully tested in comprehensive_tests.R; prefer a more actively maintained KK continuous-response inference class (e.g. InferenceContinKKOLSIVWC) for new analyses unless this specific unadjusted mean-difference estimator is required.

References

Kapelner, A., and Krieger, A. M. (2014). "Matching on-the-fly: Sequential allocation with higher power and efficiency." Biometrics, 70(2), 378-388, doi:10.1111/biom.12148 , for the KK matching-on-the-fly design this estimator targets, and for the inverse-variance combination of matched-pair and reservoir estimates.

Super class

Inference -> InferenceAllKKMeanDiffIVWC

Methods

Public methods

• InferenceAllKKMeanDiffIVWC$new()

• InferenceAllKKMeanDiffIVWC$compute_estimate()

• InferenceAllKKMeanDiffIVWC$compute_asymp_confidence_interval()

• InferenceAllKKMeanDiffIVWC$compute_asymp_two_sided_pval()

• InferenceAllKKMeanDiffIVWC$clone()

+ inherited public methods from Inference

• Inference$capabilities()
• Inference$compute_exact_confidence_interval()
• Inference$compute_exact_two_sided_pval_for_treatment_effect()
• Inference$duplicate()
• Inference$get_analysis_data()
• Inference$get_covariates()
• Inference$get_design_object()
• Inference$get_model_formula()
• Inference$get_nonestimable_reason()
• Inference$get_nonestimable_stage()
• Inference$get_optimization_alg()
• Inference$get_response()
• Inference$get_response_type()
• Inference$get_treatment()
• Inference$is_nonestimable()
• Inference$set_optimization_alg()
• Inference$set_seed()
• Inference$supports()

---

InferenceAllKKMeanDiffIVWC$new()

Usage

InferenceAllKKMeanDiffIVWC$new(
  des_obj,
  verbose = FALSE,
  harden = TRUE,
  model_formula = NULL,
  smart_cold_start_default = NULL
)

Arguments

des_obj

A completed Design object whose entire n subjects are assigned and response y is recorded within.

verbose

Whether to print progress messages.

harden

Whether to apply robustness measures (default TRUE). When TRUE, the inference methods employ defensive strategies including QR-based rank reduction of the design matrix, progressive correlation-threshold dropping, and fallback fits (e.g.\ robust survival regression, treatment-only models) to avoid crashes on ill-conditioned data. When FALSE, the vanilla algorithm runs on the full design matrix as supplied; any rank deficiency or convergence failure will surface as an error rather than being silently worked around. Set to FALSE when you want to verify that the raw model converges without intervention.

model_formula

Optional formula for covariate adjustment. If NULL (default), the formula from the design object is used and its pre-computed design matrix is reused. If a formula is provided, a new design matrix is constructed from the design's imputed covariates.

smart_cold_start_default

Whether to use smart cold start values by default for likelihood-based models. Explicit starts always override this object-level policy. NULL (default) consults the global cold-start dispatch policy.

---

InferenceAllKKMeanDiffIVWC$compute_estimate()

Usage

InferenceAllKKMeanDiffIVWC$compute_estimate(estimate_only = FALSE)

Arguments

estimate_only

If TRUE, skip variance component calculations.

---

InferenceAllKKMeanDiffIVWC$compute_asymp_confidence_interval()

Usage

InferenceAllKKMeanDiffIVWC$compute_asymp_confidence_interval(alpha = 0.05)

Arguments

alpha

Significance level.

---

InferenceAllKKMeanDiffIVWC$compute_asymp_two_sided_pval()

Usage

InferenceAllKKMeanDiffIVWC$compute_asymp_two_sided_pval(delta = 0)

Arguments

delta

Null treatment effect.

---

InferenceAllKKMeanDiffIVWC$clone()

The objects of this class are cloneable with this method.

Usage

InferenceAllKKMeanDiffIVWC$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Examples

if (FALSE) { # \dontrun{
seq_des = DesignSeqOneByOneKK14$new(n = 6, response_type = "continuous")
seq_des$add_one_subject_to_experiment_and_assign(MASS::biopsy[1, 2 : 10])
seq_des$add_one_subject_to_experiment_and_assign(MASS::biopsy[2, 2 : 10])
seq_des$add_one_subject_to_experiment_and_assign(MASS::biopsy[3, 2 : 10])
seq_des$add_one_subject_to_experiment_and_assign(MASS::biopsy[4, 2 : 10])
seq_des$add_one_subject_to_experiment_and_assign(MASS::biopsy[5, 2 : 10])
seq_des$add_one_subject_to_experiment_and_assign(MASS::biopsy[6, 2 : 10])
seq_des$add_all_subject_responses(c(4.71, 1.23, 4.78, 6.11, 5.95, 8.43))

seq_des_inf = InferenceAllKKMeanDiffIVWC$
  new(seq_des)
seq_des_inf$compute_estimate()
seq_des_inf$compute_asymp_confidence_interval()
seq_des_inf$compute_asymp_two_sided_pval()
} # }