Fast Beta Regression (C++ Backend)

Fits the beta regression model of Ferrari and Cribari-Neto (2004) for a continuous response strictly between 0 and 1 (proportions, rates, and similar bounded outcomes), via direct maximum likelihood on the reparameterized beta density $$f(y_i; \mu_i, \phi) = \frac{\Gamma(\phi)}{\Gamma(\mu_i \phi)\Gamma((1-\mu_i)\phi)} y_i^{\mu_i \phi - 1} (1 - y_i)^{(1-\mu_i)\phi - 1}, \quad 0 < y_i < 1,$$ with mean $E[Y_i] = \mu_i$ and variance $\mathrm{Var}(Y_i) = \mu_i(1-\mu_i) / (1 + \phi)$, where $\phi > 0$ is a single (constant-across-observations) precision parameter and the mean is linked to the covariates via the logit link $\mathrm{logit}(\mu_i) = x_i^\top \beta$ (fixed; no alternative link functions are supported by this backend).

Usage

fast_beta_regression_cpp(
  X,
  y,
  warm_start_beta = NULL,
  smart_cold_start = TRUE,
  start_phi = 10,
  compute_std_errs = FALSE,
  fixed_idx = NULL,
  fixed_values = NULL,
  optimization_alg = "lbfgs",
  warm_start_fisher_info = NULL,
  estimate_only = FALSE
)

Arguments

X: A numeric matrix of predictors, $n \times p$; include an explicit intercept column if desired (the model has no implicit intercept).
y: A numeric vector of responses, strictly in $(0, 1)$ (values at or beyond the boundary are not valid beta-distributed outcomes; see fast_beta_regression for boundary-handling guidance at the R wrapper level).
warm_start_beta: Optional starting values for coefficients $\beta$. If provided, smart_cold_start is ignored.
smart_cold_start: Logical. If TRUE, use an initial OLS-based guess when starting from scratch (a "cold start") with no prior knowledge. This is ignored if a warm start is provided.
start_phi: Starting value for the precision parameter $\phi$ (on its natural, not log, scale).
compute_std_errs: Deprecated; has no effect on this estimate-only entry point. Use fast_beta_regression_with_var_cpp for standard errors.
fixed_idx: Optional integer indices (into the c(beta, log(phi)) parameter layout) of parameters to hold fixed rather than estimate.
fixed_values: Optional values to fix the parameters named by fixed_idx at; must be the same length as fixed_idx.
optimization_alg: Optimization algorithm; see Details.
warm_start_fisher_info: Optional initial Fisher Information matrix (over c(beta, log(phi))) to warm-start curvature information for the first optimizer iteration.
estimate_only: Logical; if TRUE, may skip work not needed to produce point estimates (kept in sync with the package's other fast_* estimate- vs-inference split).

Value

A list containing the following components:

coefficients: A numeric vector of the estimated beta regression coefficients.
phi: The estimated precision parameter phi.
neg_ll: The negative log-likelihood at the final iteration.
converged: A logical value indicating whether the algorithm converged.

A list with components coefficients ($\hat\beta$, length p), phi ($\hat\phi$, on its natural scale), neg_loglik (the exact beta negative log-likelihood at the fitted parameters), converged (logical), and fisher_information (an approximate working curvature matrix; see Details).

Details

Parameterization and optimization. The optimizer's parameter vector is c(beta, log(phi)) — $\phi$ is optimized on the log scale to keep it unconstrained ($\phi > 0$ enforced automatically by exponentiating back), initialized from start_phi (or a value derived from it via smart_cold_start). $\mu_i$ is clipped to $[10^{-8}, 1 - 10^{-8}]$ internally during likelihood/gradient/Hessian evaluation to avoid boundary blowup when $x_i^\top \beta$ is extreme; this affects only numerical evaluation, not the returned $\hat\beta$ itself. Optimized via optimization_alg ("lbfgs" default; see .normalize_optimizer_algorithm); when no warm_start_beta is supplied, smart_cold_start = TRUE (default) seeds $\beta$ from an OLS-based initial guess. fixed_idx/fixed_values allow holding specific parameters (by index into the c(beta, log(phi)) layout) fixed rather than estimated. compute_std_errs is a legacy/deprecated argument with no effect in this estimate-only entry point; use fast_beta_regression_with_var_cpp to obtain standard errors.

Reported likelihood and information. neg_loglik is the exact beta negative log-likelihood re-evaluated at the fitted parameters (not merely the optimizer's internal objective trace); fisher_information is the $X^\top W X$-style working-weights curvature matrix from the fit (fit.XtWX) — the same expected-information approximation classical IRLS uses for GLM standard errors, and exactly what fast_beta_regression_with_var_cpp inverts to produce vcov — rather than a fresh evaluation of the exact observed-information Hessian from get_beta_regression_hessian_cpp. It is also suitable for warm-starting a subsequent fit via warm_start_fisher_info.

References

Ferrari, S., and Cribari-Neto, F. (2004). "Beta regression for modelling rates and proportions." Journal of Applied Statistics, 31(7), 799-815, doi:10.1080/0266476042000214501 . Analogous Python API: statsmodels GLM (via the Beta family, statsmodels.othermod.betareg).

Examples

X = matrix(rnorm(100), 10, 10)
y = runif(10)
fast_beta_regression_cpp(X, y)
#> $coefficients
#>  [1]   1.2783412   6.2518634  21.2793767  -0.1847222 -37.6781303  -9.1345408
#>  [7] -23.4459298  14.8316356  18.6904151  -5.1901350
#> 
#> $phi
#> [1] 2091896561
#> 
#> $neg_loglik
#> [1] -109.9642
#> 
#> $converged
#> [1] TRUE
#> 
#> $num_iter
#> [1] 173
#> 
#> $hit_iteration_cap
#> [1] FALSE
#> 
#> $gradient_norm
#> [1] 538.8727
#> 
#> $min_eigenvalue_information
#> [1] NaN
#> 
#> $fisher_information
#>                [,1]          [,2]          [,3]          [,4]          [,5]
#>  [1,]  3.103009e+09  1.164630e+07 -2.145492e+09  1.862450e+09 -1.187782e+09
#>  [2,]  1.164630e+07  4.168661e+09 -6.160117e+08  3.095561e+08  7.427715e+08
#>  [3,] -2.145492e+09 -6.160117e+08  2.989874e+09 -8.558711e+08  1.311018e+09
#>  [4,]  1.862450e+09  3.095561e+08 -8.558711e+08  2.104860e+09 -2.518092e+08
#>  [5,] -1.187782e+09  7.427715e+08  1.311018e+09 -2.518092e+08  1.942058e+09
#>  [6,]  1.853802e+08 -1.988326e+09  9.569042e+08  6.607703e+08 -4.614428e+08
#>  [7,]  5.056173e+08 -1.792250e+09 -8.719686e+08 -2.342798e+08 -1.976470e+09
#>  [8,] -5.015436e+08 -1.740341e+09  3.629877e+08 -2.945508e+08 -2.080926e+07
#>  [9,]  3.696530e+08 -7.873765e+08 -7.046567e+08  2.059684e+08 -1.727078e+08
#> [10,] -2.462810e+09  9.760832e+08  2.438608e+09 -1.190326e+09  1.045207e+09
#> [11,]  2.936504e+02  1.116786e+02 -1.011826e+02  5.458118e+01  1.778834e+02
#>                [,6]          [,7]          [,8]          [,9]         [,10]
#>  [1,]  1.853802e+08  5.056173e+08 -5.015436e+08  3.696530e+08 -2.462810e+09
#>  [2,] -1.988326e+09 -1.792250e+09 -1.740341e+09 -7.873765e+08  9.760832e+08
#>  [3,]  9.569042e+08 -8.719686e+08  3.629877e+08 -7.046567e+08  2.438608e+09
#>  [4,]  6.607703e+08 -2.342798e+08 -2.945508e+08  2.059684e+08 -1.190326e+09
#>  [5,] -4.614428e+08 -1.976470e+09 -2.080926e+07 -1.727078e+08  1.045207e+09
#>  [6,]  3.606506e+09 -1.661079e+08 -7.297220e+07 -2.216794e+07 -7.929867e+08
#>  [7,] -1.661079e+08  3.489512e+09  1.694790e+09  5.128556e+08 -2.350813e+08
#>  [8,] -7.297220e+07  1.694790e+09  2.339291e+09  4.363672e+08  7.858770e+07
#>  [9,] -2.216794e+07  5.128556e+08  4.363672e+08  8.612736e+08 -5.400482e+08
#> [10,] -7.929867e+08 -2.350813e+08  7.858770e+07 -5.400482e+08  4.001450e+09
#> [11,] -5.584165e+01  3.318164e+02 -1.614086e+02 -7.904083e+01  2.509289e+01
#>              [,11]
#>  [1,]  293.6504128
#>  [2,]  111.6785774
#>  [3,] -101.1826149
#>  [4,]   54.5811813
#>  [5,]  177.8834341
#>  [6,]  -55.8416487
#>  [7,]  331.8163654
#>  [8,] -161.4086454
#>  [9,]  -79.0408327
#> [10,]   25.0928898
#> [11,]    0.2672385
#>