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]  0.17601979 -0.07964609  0.49290955  0.51108059 -0.79737034 -1.90701977
#>  [7]  0.30584803 -0.19394410 -3.03866851  0.81510842
#> 
#> $phi
#> [1] 3.257956e+13
#> 
#> $neg_loglik
#> [1] -155.2754
#> 
#> $converged
#> [1] FALSE
#> 
#> $num_iter
#> [1] 1000
#> 
#> $hit_iteration_cap
#> [1] FALSE
#> 
#> $gradient_norm
#> [1] NaN
#> 
#> $min_eigenvalue_information
#> [1] NaN
#> 
#> $fisher_information
#>                [,1]          [,2]          [,3]          [,4]          [,5]
#>  [1,]  7.717176e+13 -3.582857e+13 -1.194839e+13  3.484882e+12  3.684367e+13
#>  [2,] -3.582857e+13  1.238192e+14  8.030161e+12 -3.168640e+13 -1.014599e+13
#>  [3,] -1.194839e+13  8.030161e+12  5.904369e+13  3.006430e+13 -3.617831e+13
#>  [4,]  3.484882e+12 -3.168640e+13  3.006430e+13  5.774153e+13 -1.338137e+13
#>  [5,]  3.684367e+13 -1.014599e+13 -3.617831e+13 -1.338137e+13  6.670373e+13
#>  [6,] -1.693057e+13  2.997027e+13  1.736822e+13 -1.761699e+13 -4.736366e+12
#>  [7,] -3.470080e+13 -2.241994e+13  4.077275e+12  1.760463e+13 -2.452727e+13
#>  [8,]  1.313913e+13  3.264485e+12 -1.950250e+13 -6.568608e+11  1.037690e+13
#>  [9,]  1.893167e+12 -2.262237e+13  2.160807e+13  3.190786e+13 -2.051878e+13
#> [10,] -1.042382e+13  2.719818e+13  1.245965e+13  4.046127e+12  5.729663e+12
#> [11,]  2.545240e+06 -2.887214e+06 -3.671641e+06  1.602400e+06 -1.159086e+05
#>                [,6]          [,7]          [,8]          [,9]         [,10]
#>  [1,] -1.693057e+13 -3.470080e+13  1.313913e+13  1.893167e+12 -1.042382e+13
#>  [2,]  2.997027e+13 -2.241994e+13  3.264485e+12 -2.262237e+13  2.719818e+13
#>  [3,]  1.736822e+13  4.077275e+12 -1.950250e+13  2.160807e+13  1.245965e+13
#>  [4,] -1.761699e+13  1.760463e+13 -6.568608e+11  3.190786e+13  4.046127e+12
#>  [5,] -4.736366e+12 -2.452727e+13  1.037690e+13 -2.051878e+13  5.729663e+12
#>  [6,]  5.284986e+13 -1.001906e+13 -3.652610e+13 -2.790756e+13  4.332022e+12
#>  [7,] -1.001906e+13  7.989846e+13 -3.633419e+11  1.702214e+13  5.323759e+12
#>  [8,] -3.652610e+13 -3.633419e+11  6.460621e+13  1.181133e+13  4.403110e+12
#>  [9,] -2.790756e+13  1.702214e+13  1.181133e+13  4.196284e+13  6.757947e+12
#> [10,]  4.332022e+12  5.323759e+12  4.403110e+12  6.757947e+12  2.616443e+13
#> [11,] -2.312519e+06 -1.289721e+05  3.303803e+06  8.390095e+05 -7.605212e+05
#>               [,11]
#>  [1,]  2.545240e+06
#>  [2,] -2.887214e+06
#>  [3,] -3.671641e+06
#>  [4,]  1.602400e+06
#>  [5,] -1.159086e+05
#>  [6,] -2.312519e+06
#>  [7,] -1.289721e+05
#>  [8,]  3.303803e+06
#>  [9,]  8.390095e+05
#> [10,] -7.605212e+05
#> [11,]  1.756234e+00
#>