OLS Combined-Likelihood Inference for KK Designs

Fits a single stacked OLS regression over matched-pair differences and reservoir observations for KK matching-on-the-fly designs with continuous responses, using the treatment indicator and, optionally, all recorded covariates as predictors. Note that warm starts are disabled for this class as OLS is a closed-form estimator and does not benefit from initialization.

Computes the randomization distribution of the treatment effect estimate under the sharp null.

Whether compute_rand_two_sided_pval() is actually usable on this instance right now – FALSE exactly when it would stop(): an incidence-response instance with no custom randomization statistic and a design not eligible for design-randomization-based incidence inference (see private$should_use_design_randomization_for_incidence()). TRUE for every other case, including every non-incidence response type. Public, self-contained (only reads already-set instance state, no side effects), so InferenceSuite can check this before attempting the sentinel instead of relying on the stop() being silently swallowed into a pval = NA "ok" row – the single source of truth for both this check and compute_rand_two_sided_pval()'s own guard, so the two can never drift apart.

Computes a randomization-based p-value.

Value

When debug = FALSE (default), a numeric vector of length r. When debug = TRUE, a list with: values, errors (list of character vectors, one per iteration), warnings (list of character vectors, one per iteration), num_errors, num_warnings, prop_iterations_with_errors, prop_iterations_with_warnings, and prop_illegal_values.

A single logical.

Randomization p-value.

Details

Model. Let \(m\) be the number of matched pairs and \(n_R = n_{RT} + n_{RC}\) the number of unmatched reservoir subjects. The design matrix stacks two blocks: \(m\) matched-pair difference rows (each row's response is the within-pair outcome difference, coded with an implicit unit treatment column and covariate differences \(X_{d}\)), and \(n_R\) reservoir rows (raw covariates plus a treatment/matching-status indicator column). The stacked regression is fit by ordinary least squares (lm.fit), and \(\hat\beta_T\) is the coefficient on the treatment/matched-difference column, i.e. an additive mean-difference estimand on the outcome's natural scale. If only matched pairs exist, j_treat = 1; if only reservoir data exist, j_treat = 2; if both exist, the combined design uses j_treat = 2. If neither matched pairs nor a treatment-and-control-populated reservoir exist, the estimate is marked nonestimable ("no_usable_matched_or_reservoir_data").

Variance. Standard errors use the HC2 heteroskedasticity-consistent sandwich estimator (ols_hc2_post_fit_cpp), not the classical OLS variance, so the Wald confidence interval/p-value are robust to heteroskedasticity across the matched/reservoir blocks.

Likelihood tier. likelihood_tier = "full": this is a genuine Gaussian likelihood (not a quasi-likelihood or partial likelihood), so score, gradient, and likelihood-ratio testing types are available in addition to Wald, and an exact (not higher-order-accurate) Bartlett correction reproduces base R's lm() classical partial F-test exactly under the classical homoskedastic-Gaussian-errors assumption (a stronger assumption than the HC2-robust Wald path uses, so the two paths need not agree numerically).

Assumptions. Continuous response; independent matched pairs and/or independent reservoir subjects; no censoring (assertNoCensoring() is enforced); a KK matching-on-the-fly design (DesignSeqOneByOneKK14 or subclass).

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 . (KK14 in REFERENCES.md.)

See also

InferenceContinKKOLSIVWC for the inverse-variance-weighted-combination alternative to this one-likelihood combined-fit approach; analogous Python API: statsmodels GLM/OLS.

Super class

Inference -> InferenceContinKKOLSOneLik

Methods

Public methods

• InferenceContinKKOLSOneLik$approximate_randomization_distribution_beta_hat_T()

• InferenceContinKKOLSOneLik$supports_rand_pval_for_incidence()

• InferenceContinKKOLSOneLik$compute_rand_two_sided_pval()

• InferenceContinKKOLSOneLik$clone()

+ inherited public methods from Inference

• Inference$capabilities()
• Inference$compute_asymp_confidence_interval()
• Inference$compute_asymp_two_sided_pval()
• Inference$compute_estimate()
• 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$initialize()
• Inference$is_nonestimable()
• Inference$set_optimization_alg()
• Inference$set_seed()
• Inference$supports()

---

InferenceContinKKOLSOneLik$approximate_randomization_distribution_beta_hat_T()

Usage

InferenceContinKKOLSOneLik$approximate_randomization_distribution_beta_hat_T(
  r = 501,
  delta = 0,
  transform_responses = "none",
  show_progress = TRUE,
  permutations = NULL,
  debug = FALSE,
  zero_one_logit_clamp = .Machine$double.eps
)

Arguments

r

Number of randomization vectors. Default 501.

r

Number of randomization vectors.

delta

The null difference. Default 0.

delta

Null difference.

transform_responses

Type of transformation. Default "none".

transform_responses

Transformation.

show_progress

Show progress bar. Default TRUE.

show_progress

Show progress.

permutations

Pre-computed permutations. Default NULL.

permutations

Pre-computed permutations.

debug

If TRUE, return a list with the distribution values and per-iteration diagnostics including error messages, warning messages, counts of each, and summary proportions for iterations with errors, warnings, and illegal (non-finite) values. Runs serially. Default FALSE.

zero_one_logit_clamp

The clamping amount for exact 0 and 1 values when logging

zero_one_logit_clamp

The clamping amount for exact 0 and 1 values when logging

---

InferenceContinKKOLSOneLik$supports_rand_pval_for_incidence()

Usage

InferenceContinKKOLSOneLik$supports_rand_pval_for_incidence()

---

InferenceContinKKOLSOneLik$compute_rand_two_sided_pval()

Usage

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

Arguments

r

Number of randomization vectors. Default 501.

r

Number of randomization vectors.

delta

The null difference. Default 0.

delta

Null difference.

transform_responses

Type of transformation. Default "none".

transform_responses

Transformation.

na.rm

Remove NAs.

show_progress

Show progress bar. Default TRUE.

show_progress

Show progress.

permutations

Pre-computed permutations. Default NULL.

permutations

Pre-computed permutations.

zero_one_logit_clamp

The clamping amount for exact 0 and 1 values when logging

zero_one_logit_clamp

The clamping amount for exact 0 and 1 values when logging

---

InferenceContinKKOLSOneLik$clone()

The objects of this class are cloneable with this method.

Usage

InferenceContinKKOLSOneLik$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Examples

# \donttest{
seq_des = DesignSeqOneByOneKK14$new(n = 10, response_type = 'continuous')
for (i in 1:10) {
  seq_des$add_one_subject_to_experiment_and_assign(data.frame(x1 = rnorm(1), x2 = rnorm(1)))
}
seq_des$add_all_subject_responses(rnorm(10))
inf = InferenceContinKKOLSOneLik$new(seq_des)
inf$compute_estimate()
#> [1] -0.112185
# }