One-Likelihood Conditional-Poisson Inference for KK Count Designs

Estimates a treatment log-rate-ratio \(\beta_T\) for count outcomes collected under a KK matching-on-the-fly design (DesignSeqOneByOneKK14 or subclass) by maximizing a single combined likelihood that couples a conditional (within-matched-pair, intercept-free) Poisson likelihood for matched subjects with an ordinary Poisson likelihood for reservoir subjects, sharing one treatment coefficient across both pieces. This is the "one-likelihood" alternative to the inverse-variance-weighted combination (...IVWC pattern used elsewhere in the KK family): rather than fitting matched and reservoir models separately and pooling by inverse-variance weights, the treatment coefficient here is estimated jointly from the full combined log-likelihood, and its standard error, score, likelihood-ratio, and gradient statistics are all "design-conservative" – each is the pointwise-wider of the model-based asymptotic quantity and a design-based quantity computed by treating the estimate as a plug-in statistic under InferenceAsymp's \(z\)/\(t\) machinery, so inference never overstates precision relative to the design alone.

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

Estimand. \(\beta_T\), the treatment coefficient in a log-linear (Poisson) mean model \(E[Y \mid w, x] = \exp(\beta_0 + \beta_T w + x\beta)\), interpreted as a log rate ratio (equivalently, \(\exp(\hat\beta_T)\) is the treatment-vs-control incidence rate ratio).

Model. Matched subjects contribute a conditional-Poisson term that eliminates the pair-specific nuisance intercept by conditioning on the pair total count (removing the need to estimate one intercept per pair); reservoir subjects contribute an ordinary Poisson log-likelihood with a single shared intercept. Both pieces are summed into one combined negative log-likelihood and maximized jointly in \((\beta_0, \beta_T, \beta)\) (see get_cpoisson_combined_hessian_cpp and fast_cpoisson_combined_with_var_cpp for the backend fitting contract). likelihood_tier = "full", so likelihood-ratio, score, and gradient tests and a parametric likelihood bootstrap are all available in addition to the design-conservative Wald path.

Assumptions. Independence of counts across matched pairs and reservoir subjects given covariates; correct log-linear mean specification; a KK matching-on-the-fly design supplying the matched/reservoir partition. No response censoring is supported (checked at construction via assertNoCensoring()).

References

Kapelner, A. and Krieger, A. (2014). "Matching on-the-fly: A group sequential covariate balanced randomization procedure." arXiv preprint arXiv:1305.6259. (KK14 in REFERENCES.md.)

See also

Analogous Python API for count models: statsmodels discrete models (ConditionalPoisson, Poisson). Poisson regression (orientation).

Super class

Inference -> InferenceCountKKCondPoissonOneLik

Methods

Public methods

• InferenceCountKKCondPoissonOneLik$approximate_randomization_distribution_beta_hat_T()

• InferenceCountKKCondPoissonOneLik$supports_rand_pval_for_incidence()

• InferenceCountKKCondPoissonOneLik$compute_rand_two_sided_pval()

• InferenceCountKKCondPoissonOneLik$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()

---

InferenceCountKKCondPoissonOneLik$approximate_randomization_distribution_beta_hat_T()

Usage

InferenceCountKKCondPoissonOneLik$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

---

InferenceCountKKCondPoissonOneLik$supports_rand_pval_for_incidence()

Usage

InferenceCountKKCondPoissonOneLik$supports_rand_pval_for_incidence()

---

InferenceCountKKCondPoissonOneLik$compute_rand_two_sided_pval()

Usage

InferenceCountKKCondPoissonOneLik$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

---

InferenceCountKKCondPoissonOneLik$clone()

The objects of this class are cloneable with this method.

Usage

InferenceCountKKCondPoissonOneLik$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.