Fast Zero/One-Inflated Beta Regression (C++) — fast_zero_one_inflated_beta_cpp • EDI: Experimental Design and Inference

Fits, by direct maximum likelihood, a three-component mixture model for a response $Y_i \in [0, 1]$ (e.g. a bounded proportion with excess exact 0s and 1s): with probability $\pi_{0,i}$ the response is exactly 0, with probability $\pi_{1,i}$ it is exactly 1, and with probability $\pi_{b,i} = 1 - \pi_{0,i} - \pi_{1,i}$ it falls strictly inside $(0, 1)$ and follows a mean-precision Beta distribution. The three category probabilities come from a multinomial-logit-style softmax over two linear predictors on X_zero_one, with the "interior" (Beta) category as the implicit zero baseline: $$\pi_{0,i} = \frac{e^{\eta_{0,i}}}{e^{\eta_{0,i}} + e^{\eta_{1,i}} + 1}, \quad \pi_{1,i} = \frac{e^{\eta_{1,i}}}{e^{\eta_{0,i}} + e^{\eta_{1,i}} + 1}, \quad \eta_{0,i} = x_{\mathrm{zo},i}^\top\gamma_0,\ \ \eta_{1,i} = x_{\mathrm{zo},i}^\top\gamma_1,$$ and, conditional on $0 < Y_i < 1$, $Y_i \sim \mathrm{Beta}(\mu_i\phi, (1-\mu_i)\phi)$ with $\mu_i = \mathrm{logit}^{-1}(x_i^\top\beta)$ (clamped to $[10^{-8}, 1-10^{-8}]$) and precision $\phi = e^{\log\phi}$ — matching the mean-precision Beta regression parameterization documented at fast_beta_regression_cpp. Optimizes the joint parameter vector $[\beta, \log\phi, \gamma_0, \gamma_1]$ via optimization_alg (default "lbfgs"), for up to 1500 iterations at gradient-norm tolerance $10^{-6}$ — both hardcoded, with no maxit/tol arguments exposed by this function.

Usage

fast_zero_one_inflated_beta_cpp(
  X,
  X_zero_one,
  y,
  warm_start_params = NULL,
  smart_cold_start = TRUE,
  fixed_idx = NULL,
  fixed_values = NULL,
  optimization_alg = "lbfgs",
  warm_start_fisher_info = NULL,
  estimate_only = FALSE
)

Arguments

X: Matrix of predictors for the interior Beta (mean) component.
X_zero_one: Matrix of predictors for the zero- and one-inflation (mixture-probability) components; shared between $\gamma_0$ and $\gamma_1$.
y: Vector of responses in [0, 1].
warm_start_params: Optional starting values for the joint $[\beta, \log\phi, \gamma_0, \gamma_1]$ vector. If provided, smart_cold_start is ignored.
smart_cold_start: Logical. If TRUE (the default) and no warm_start_params is supplied, use an OLS-based initial guess; see Details.
fixed_idx: Optional 1-indexed positions of parameters to hold fixed.
fixed_values: Optional values, parallel to fixed_idx, of the fixed parameters.
optimization_alg: Optimization algorithm (default "lbfgs").
warm_start_fisher_info: Optional initial curvature (Fisher/observed information) matrix.
estimate_only: If TRUE, skip the post-fit Hessian/variance computation and return only b, log_phi, zero_one_b0, zero_one_b1, params, neg_loglik, and converged.

Value

A list with components b ($\hat\beta$), log_phi, zero_one_b0/zero_one_b1 ($\hat\gamma_0$/$\hat\gamma_1$), params (the full fitted joint vector), neg_loglik, converged; unless estimate_only = TRUE, additionally vcov (the joint variance-covariance matrix — an all-NA matrix if the observed information is non-finite or its free-parameter submatrix is not invertible, rather than an error), observed_information/fisher_information/information (three aliases for the same observed-information matrix; information_type is always "observed"), and hessian (the negative of that same matrix).

Fixed parameters, warm starts

fixed_idx (1-indexed into $[\beta, \log\phi, \gamma_0, \gamma_1]$) and fixed_values optionally hold a subset of parameters fixed at caller-supplied constant values rather than estimated. warm_start_params supplies the full starting vector directly; otherwise, if smart_cold_start = TRUE (the default): $\beta$ starts from an OLS fit of $\mathrm{logit}(y_i)$ on X restricted to interior observations ($0 < y_i < 1$), falling back to zero if fewer such observations than ncol(X) are available; $\log\phi$ starts at 2; and $\gamma_0$/ $\gamma_1$ each start from a separate OLS fit of X_zero_one on the corresponding 0/1 indicator ($\mathbb{1}[y_i = 0]$, $\mathbb{1}[y_i = 1]$). If smart_cold_start = FALSE, all parameters start at zero except $\log\phi$, which still starts at 2. warm_start_fisher_info, if supplied, seeds the curvature estimate used for the optimizer's first iteration.