GLMM Inference for KK Designs with Count Response
Source:R/inference_count_KK_combined.R
InferenceCountKKGLMM.RdFits a Poisson GLMM for count responses under a KK matching-on-the-fly design. The random intercept per matched pair is integrated out via Gauss-Hermite quadrature.
When use_rcpp = TRUE (default) the likelihood is maximised by an internal
Rcpp routine. Set use_rcpp = FALSE to fall back to glmmTMB.
Model. \(Y_{ij} \mid b_i \sim \mathrm{Poisson}(\mu_{ij})\) with \(\log \mu_{ij} = X_{ij}'\beta + \beta_T \cdot W_{ij} + b_i\), where \(i\) indexes matched pairs, \(j \in \{1, 2\}\) the two subjects within a pair, \(W_{ij}\) is the treatment indicator, and \(b_i \sim \mathcal{N}(0, \sigma_b^2)\) is a pair-level random intercept absorbing within-pair correlation induced by matching. \(\beta_T\) is a log-rate (log relative risk) treatment effect: \(\exp(\hat\beta_T)\) is the estimated rate ratio. The random effect is integrated out of the marginal likelihood by adaptive Gauss-Hermite quadrature rather than a Laplace approximation.
Likelihood tier. likelihood_tier = "full": both Wald
(model-based standard error) and likelihood-ratio testing types are
available. Because the GLMM likelihood alone does not encode the KK design's
matched-pair randomization structure, the likelihood-ratio CI/p-value are
conservatively widened/calibrated against the design-aware Wald result (see
compute_lik_ratio_confidence_interval()/
compute_lik_ratio_two_sided_pval()) so the model-based test is never
anti-conservative relative to the design.
Assumptions. Count response modeled as conditionally Poisson given the random intercept (equidispersion conditional on \(b_i\)); pair-level random effects independent across pairs; a KK matching-on-the-fly design.
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
Analogous Python API for Poisson/count GLMs: statsmodels discrete models. Generalized linear model and Gauss-Hermite quadrature (orientation).
Super class
Inference -> InferenceCountKKGLMM
Methods
Public 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()
InferenceCountKKGLMM$new()
Initialize a KK Poisson-GLMM inference object for a matched-pair KK design with a count response and prepare the matched-pair random-intercept likelihood machinery; see the class topic for the model.
Usage
InferenceCountKKGLMM$new(
des_obj,
model_formula = NULL,
use_rcpp = TRUE,
optimization_alg = NULL,
verbose = FALSE,
smart_cold_start_default = NULL
)Arguments
des_objA completed KK matching-on-the-fly
Designobject (DesignSeqOneByOneKK14or subclass) with a count response.model_formulaOptional formula for covariate adjustment. If
NULL(default), the formula from the design object is used.use_rcppLogical. If
TRUE(default), maximize the Gauss-Hermite-quadrature marginal likelihood with the internal Rcpp Poisson-GLMM routine; ifFALSE, fall back to glmmTMB.optimization_algOptimization algorithm passed to the likelihood maximizer. If
NULL(default), an algorithm is dispatched via the package's optimizer policy.verboseWhether to print progress messages.
smart_cold_start_defaultWhether to use smart starting values for the optimizer.
InferenceCountKKGLMM$compute_estimate()
Point estimate of the treatment log-rate coefficient \(\beta_T\) from a
Poisson GLMM with a matched-pair random intercept, fit by maximizing the
Gauss-Hermite-quadrature-integrated marginal likelihood (internal Rcpp routine when
use_rcpp = TRUE, else glmmTMB). See the class topic for the model form.
InferenceCountKKGLMM$compute_estimate_with_bootstrap_weights()
Recomputes the KK Poisson-GLMM treatment estimate under nonparametric/
Bayesian-bootstrap subject-or-block weights, refitting the weighted GLMM
(compute_weighted_glmm_bootstrap_estimate()). Standard error, degrees of
freedom, and the cached summary table are cleared/set to NA/Inf/
NULL since only the point estimate is meaningful under resampling weights.
Falls back to the unweighted point estimate when the weights are effectively
constant.
Usage
InferenceCountKKGLMM$compute_estimate_with_bootstrap_weights(
subject_or_block_weights,
estimate_only = FALSE
)Arguments
subject_or_block_weightsNumeric vector of nonnegative bootstrap replicate weights, one per subject or per matched block (KK match structure).
estimate_onlyIf
TRUE, compute only the weighted point estimate (this method never computes a weighted standard error regardless of this argument).
InferenceCountKKGLMM$compute_wald_confidence_interval()
Wald confidence interval for the treatment log-rate coefficient:
\(\hat\beta_T \pm t_{1-\alpha/2,\,df}\cdot \hat{se}(\hat\beta_T)\), using the
model-based GLMM standard error. See
InferenceAsymp for the shared contract.
InferenceCountKKGLMM$compute_wald_two_sided_pval()
Two-sided Wald p-value for \(H_0: \beta_T = \code{delta}\) vs. \(H_1: \beta_T \neq \code{delta}\), using the model-based GLMM standard error.
InferenceCountKKGLMM$compute_lik_ratio_confidence_interval()
Likelihood-ratio confidence interval for the treatment log-rate
coefficient, inverting the GLMM's profile likelihood-ratio test against
\(\chi^2_1\). Because the GLMM likelihood does not itself account for the KK
matched-pair design's randomization structure, this interval is conservatively
widened to be at least as wide as the design-aware Wald interval
(compute_wald_confidence_interval()) via .conservative_kk_onelik_ci() –
guarding against the model-based interval being anti-conservative relative to the
design.
InferenceCountKKGLMM$compute_lik_ratio_two_sided_pval()
Two-sided likelihood-ratio p-value for \(H_0: \beta_T = \code{delta}\),
from the GLMM's profile likelihood-ratio test referred to \(\chi^2_1\). As with
compute_lik_ratio_confidence_interval(), this is conservatively calibrated
(via .conservative_kk_onelik_pval()) against the design-aware Wald p-value so
the model-based test cannot be anti-conservative relative to the KK matched-pair
design.
InferenceCountKKGLMM$compute_asymp_confidence_interval()
Asymptotic confidence interval, dispatching to
compute_wald_confidence_interval() or compute_lik_ratio_confidence_interval()
depending on self$get_testing_type() (defaults to Wald if the testing type is
neither). See InferenceAsymp for the shared
testing-type dispatch contract.
InferenceCountKKGLMM$compute_asymp_two_sided_pval()
Asymptotic two-sided p-value, dispatching to
compute_wald_two_sided_pval() or compute_lik_ratio_two_sided_pval()
depending on self$get_testing_type() (defaults to Wald if the testing type is
neither). See InferenceAsymp for the shared
testing-type dispatch contract.
Examples
# \donttest{
seq_des = DesignSeqOneByOneKK14$new(n = 10, response_type = 'count')
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(rpois(10, 2))
inf = InferenceCountKKGLMM$new(seq_des)
inf$compute_estimate()
#> [1] -0.01205704
# }