Fast Combined Conditional-Poisson + Poisson Regression for KK Matched-Pair/ Reservoir Designs, with Variance (C++ Backend)

Jointly fits a single treatment-effect coefficient \(\beta_T\) (and shared covariate effects \(\beta_{xs}\)) across two structurally different count likelihoods at once — the matched-pair (conditional Poisson) component from subjects paired on-the-fly by a KK matching design (e.g. DesignSeqOneByOneKK14) and the marginal Poisson component from unmatched "reservoir" subjects — rather than fitting the two subsets separately and combining estimates afterward (as an inverse-variance-weighted combination does elsewhere in the package). This one-likelihood joint fit is what backs InferenceCountKKCondPoissonOneLik-style estimators.

Usage

fast_cpoisson_combined_with_var_cpp(
  yT_v_r,
  n_k_v_r,
  X_diff_v_r,
  y_r_r,
  w_r_r,
  X_r_r,
  maxit = 100L,
  tol = 1e-08,
  fixed_idx = NULL,
  fixed_values = NULL,
  warm_start_fisher_info = NULL,
  warm_start_params = NULL,
  warm_start_beta = NULL,
  estimate_only = FALSE
)

Arguments

yT_v_r: Numeric vector of length \(n_{\mathrm{pairs}}\): the treated member's count for each matched pair.
n_k_v_r: Numeric vector of length \(n_{\mathrm{pairs}}\): the total (treated + control) count for each matched pair.
X_diff_v_r: Numeric matrix, \(n_{\mathrm{pairs}} \times p\): each pair's covariate difference (treated minus control); \(p = 0\) (zero columns) is valid (no covariate adjustment).
y_r_r: Numeric vector of length \(n_R\): reservoir subjects' counts.
w_r_r: Numeric vector of length \(n_R\) with values in {0, 1}: reservoir subjects' treatment indicators.
X_r_r: Numeric matrix, \(n_R \times p\): reservoir subjects' covariates (same \(p\) as X_diff_v_r).
maxit: Maximum number of Newton iterations.
tol: Convergence tolerance (on the norm of the parameter update step).
fixed_idx: Optional integer indices (into the c(beta_0, beta_T, beta_xs) parameter layout) of parameters to hold fixed rather than estimate.
fixed_values: Optional values to fix the parameters named by fixed_idx at.
warm_start_fisher_info: Optional initial Fisher Information matrix (over the full p + 2 parameters) to warm-start the first Newton iteration.
warm_start_params: Optional starting values for the full parameter vector c(beta_0, beta_T, beta_xs).
warm_start_beta: Optional starting values for just c(beta_T, beta_xs) (length p + 1); beta_0 is still initialized separately. Ignored if warm_start_params is supplied.
estimate_only: Logical; if TRUE, skip score/information/variance computation after optimization (see Details).

Value

A list with components b/params (the fitted c(beta_0, beta_T, beta_xs) vector), converged (logical), and, unless estimate_only = TRUE: ssq_b_j (the variance of \(\hat\beta_T\)), score (the score vector at the fitted parameters), observed_information/fisher_information/ information (three aliases for the same Fisher information matrix, also tagged by information_type = "fisher"), hessian (the Hessian of the negative log-likelihood, i.e. -information), neg_loglik/neg_ll (aliases for the combined negative log-likelihood at the fitted parameters), and loglik (its negation).

Details

Matched-pair component (conditional Poisson). For pair \(k\) with total count \(n_k\) (sum of both members' counts) and treated-member count \(y_{T,k}\), conditioning on \(n_k\) (the sufficient statistic that eliminates the pair's nuisance baseline rate) reduces the joint Poisson likelihood of the pair to a Binomial: \(y_{T,k} \mid n_k \sim \mathrm{Binomial}(n_k, p_k)\), \(p_k = \mathrm{logit}^{-1}(\beta_T + x_{\Delta,k}^\top \beta_{xs})\), where \(x_{\Delta,k}\) is the pair's covariate difference (treated minus control). This is exactly the count-response analog of conditional logistic regression for matched pairs — no per-pair intercept is estimated (it is conditioned out entirely), so only \(\beta_T\) and \(\beta_{xs}\) appear in this component.

Reservoir component (marginal Poisson). Unmatched reservoir subjects contribute an ordinary Poisson log-linear likelihood, \(y_i \sim \mathrm{Poisson}(\mu_i)\), \(\log \mu_i = \beta_0 + w_i \beta_T + x_i^\top \beta_{xs}\), sharing the same \(\beta_T\) and \(\beta_{xs}\) as the pair component but additionally estimating an intercept \(\beta_0\) (which the conditional pair likelihood has no use for).

Combined likelihood and optimization. The total log-likelihood is the simple sum of the pair (conditional Poisson/Binomial) and reservoir (Poisson) log-likelihoods, jointly maximized over c(beta_0, beta_T, beta_xs) (length p + 2) via Newton's method using the analytic Fisher information as the Hessian (quadratic convergence near the optimum, typically very few iterations). fixed_idx/fixed_values hold specific parameters fixed rather than estimated; warm_start_params (full vector) or warm_start_beta (either the full vector, or just c(beta_T, beta_xs) when of length p + 1, in which case beta_0 is initialized separately) seed the optimizer, with a log-mean-based default cold start for beta_0 when neither is supplied.

Variance. ssq_b_j is the variance of \(\hat\beta_T\) specifically (index 1, 0-based, in the parameter layout — the package's usual single-treatment-coefficient convention), obtained via a targeted diagonal inverse of the observed/Fisher information restricted to free parameters; NA if \(\beta_T\) was itself fixed via fixed_idx.

Estimate-only mode. If estimate_only = TRUE, optimization still runs to convergence but the score/information/variance computation is skipped entirely, returning only b, params, and converged.

Usage

Arguments

Value

Details

See also