Linear Mixed Model Inference for KK Designs with Continuous Response
Source:R/inference_continuous_KK_glmm.R
InferenceContinKKGLMM.RdFits a linear mixed model for continuous responses under a KK
matching-on-the-fly design. The matched-pair strata enter as a subject-level
random intercept (1 | group_id), accounting for within-pair correlation.
When use_rcpp = TRUE (default) the likelihood is maximised by an
internal Rcpp/L-BFGS routine that requires no external packages. Set
use_rcpp = FALSE to fall back to glmmTMB.
The treatment coefficient \(\beta_T\) is on the response's natural
(untransformed) scale — a mean difference, not a ratio or log-scale
effect. likelihood_tier = "full": likelihood-ratio, score, and
Wald tests are all available when the model converges (see
$get_likelihood_test_spec() inherited from the shared count/GLMM
likelihood plumbing). Validity requires the random-intercept-per-pair
structure to correctly capture the design's matching dependence and the
usual linear mixed model assumptions (conditional normality of responses
and pair effects, correctly specified fixed-effects formula).
See also
Comparable Python API: statsmodels MixedLM. See also: Mixed model (Wikipedia).
Super class
Inference -> InferenceContinKKGLMM
Methods
+ 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()
InferenceContinKKGLMM$new()
Initialize inference for the linear mixed model \(Y_i = \beta_0 + \beta_T W_i + X_i^\top \gamma + b_{g(i)} + \epsilon_i\), \(b_g \sim N(0, \sigma_b^2)\), \(\epsilon_i \sim N(0, \sigma_e^2)\), where \(g(i)\) is subject \(i\)'s matched-pair group id, \(W_i\) is the treatment indicator, \(X_i\) are covariates, and \(\beta_T\) is the treatment effect (mean difference on the response's natural scale). The random intercept \(b_g\) absorbs the within-pair correlation induced by matching, so \(\beta_T\)'s standard error correctly reflects the design.
Usage
InferenceContinKKGLMM$new(
des_obj,
model_formula = NULL,
use_rcpp = TRUE,
use_gls_fast_path = TRUE,
use_gls_fast_path_bootstrap = FALSE,
verbose = FALSE,
smart_cold_start_default = NULL,
optimization_alg = NULL
)Arguments
des_objA completed
Designobject with a continuous response.model_formulaOptional 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.use_rcppLogical. If
TRUE(default), use the optimised Rcpp Gaussian LMM implementation (no external package required). IfFALSE, use glmmTMB.use_gls_fast_pathLogical. If
TRUE(default), use a fast GLS estimator (no optimisation) forestimate_onlycalls during randomisation inference once variance components are cached from a prior full fit. Statistically exact: fixing VC at the null-fit MLE and permuting only the treatment assignment gives a valid permutation test by exchangeability. SetFALSEto always run full L-BFGS.use_gls_fast_path_bootstrapLogical. If
TRUE, also use the fast GLS estimator for non-studentised bootstrap draws (estimate_only = TRUEweighted calls). Asymptotically valid by the plug-in principle (VC orthogonal to beta_T in the Fisher information), but not exact in finite samples. DefaultFALSE.verboseWhether to print progress messages.
smart_cold_start_defaultWhether to use smart cold start values.
optimization_algThe optimization algorithm to use. Default is dispatched via policy.
InferenceContinKKGLMM$compute_estimate()
Fits the linear mixed model by maximum likelihood and
returns \(\hat\beta_T\). When use_rcpp = TRUE (the
default), the log-likelihood
\(\ell(\beta, \sigma_b^2, \sigma_e^2)\) is maximized directly by an
internal Rcpp/L-BFGS routine over \(\beta\) and the log-variance
components; otherwise glmmTMB performs the fit. If
use_gls_fast_path = TRUE and variance components are already
cached from a prior full fit (used during randomization inference,
where only the treatment column changes across permutations),
estimate_only = TRUE calls instead solve the generalized
least-squares problem at the cached variance components — exact
under exchangeability of the permuted treatment assignment, since
fixing the variance components at their null-fit MLE and permuting
only \(W\) preserves the permutation test's validity.
InferenceContinKKGLMM$compute_estimate_with_bootstrap_weights()
Refits the linear mixed model with subject/block-level
weights applied to each row's contribution to the likelihood
(Bayesian-bootstrap or nonparametric-bootstrap draw weights,
expanded from subject/block level to individual rows via
private$expand_subject_or_block_weights_to_row_weights()),
and returns the reweighted estimate \(\hat\beta_T^{(w)}\). When
weights are effectively constant, this collapses to the unweighted
compute_estimate() call (returns df = Inf to signal a
degenerate/skipped bootstrap replicate rather than refitting). When
use_rcpp = TRUE, a weighted Rcpp fast path is tried first via
private$weighted_rcpp_estimate(); otherwise
private$compute_weighted_glmm_bootstrap_estimate() refits via
glmmTMB-based machinery.
Usage
InferenceContinKKGLMM$compute_estimate_with_bootstrap_weights(
subject_or_block_weights,
estimate_only = FALSE
)InferenceContinKKGLMM$compute_asymp_confidence_interval()
Computes a \(1-\alpha\) Wald confidence interval for
\(\beta_T\) from the fitted-model standard error, using a normal
or \(t\) critical value depending on the resolved degrees of
freedom (see private$compute_z_or_t_ci_from_s_and_df).
InferenceContinKKGLMM$compute_asymp_two_sided_pval()
Computes a two-sided Wald p-value for
\(H_0: \beta_T = \code{delta}\) using the fitted-model estimate
and standard error (same statistic that
$compute_asymp_confidence_interval() inverts).
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 = InferenceContinKKGLMM$new(seq_des)
inf$compute_estimate()
#> [1] -1.028912
# }