Fits the beta regression model of Ferrari and Cribari-Neto (2004) for a
continuous response strictly in \((0, 1)\), with mean linked to the covariates
via the logit link and a single (constant) precision parameter \(\phi\). See
fast_beta_regression_cpp for the full model equation, parameter
layout, and optimizer contract implemented by the C++ backend this function
wraps; this page documents only the R-level fallback chain and response-scale
conventions.
Usage
fast_beta_regression(
X,
y,
start_phi = 10,
optimization_alg = "lbfgs",
warm_start_beta = NULL,
warm_start_fisher_info = NULL
)Arguments
- X
A numeric matrix of predictor variables. It is assumed that an intercept column (e.g., a column of ones) is already included in
Xif desired.- y
A numeric vector of the response variable, with values strictly between 0 and 1. See
sanitize_beta_response()(internal) for how boundary values (exact 0s/1s) are handled before fitting.- start_phi
A numeric value, the starting value for the precision parameter phi. Defaults to 10.
- optimization_alg
Optimization algorithm:
"lbfgs"(default) or"newton_raphson"; see.normalize_optimizer_algorithm.- warm_start_beta
Optional starting values for coefficients \(\beta\).
- warm_start_fisher_info
Optional initial Fisher Information matrix, used to warm-start curvature information for the optimizer.
Value
A list containing the following components:
- b
A numeric vector of the estimated beta regression coefficients \(\hat\beta\) (on the logit-of-mean scale:
plogis(X %*% b)gives the fitted mean \(\hat\mu\)), from whichever stage of the fallback chain (see Details) ultimately succeeded.- phi
The estimated precision parameter \(\hat\phi\) (only present when the C++ backend or the betareg fallback succeeds; absent from the final OLS-on-
logit(y)fallback, which has no precision parameter).- fisher_information
The working-weights Fisher information matrix from the C++ backend (see
fast_beta_regression_cpp); only present when that backend succeeds.
Details
Fallback chain. The primary implementation uses the C++ backend
(fast_beta_regression_cpp). If that fails to converge or errors, the
function falls back to betareg, which is listed in Suggests and is not
installed automatically with EDI. If betareg is also unavailable (or
itself fails), a final fallback of OLS on logit(y) is used — this last
resort is always available (no external dependency) but does not respect the beta
distribution's mean-variance relationship or estimate \(\phi\) at all, so its
coefficients should be treated as an approximate, non-model-based summary rather
than a true beta-regression fit. Install betareg manually to
enable the intermediate fallback. A warning() is issued whenever a fallback
stage is used, naming which stage and the triggering error, so callers can detect
when the primary fit failed even though a result was still returned.
Examples
X = matrix(rnorm(500), 100, 5)
y = runif(100)
fast_beta_regression(X, y)
#> $b
#> [1] -0.16450946 0.12800498 -0.01839382 -0.05882154 -0.09641642
#>
#> $phi
#> [1] 2.468764
#>
#> $fisher_information
#> [,1] [,2] [,3] [,4] [,5] [,6]
#> [1,] 118.467956 -6.218329 19.521771 -28.0549567 -1.481276 7.2752733
#> [2,] -6.218329 83.167649 -6.697227 -5.7996939 9.575162 -4.6059577
#> [3,] 19.521771 -6.697227 104.286992 3.6984746 4.188177 2.6402500
#> [4,] -28.054957 -5.799694 3.698475 88.4208110 -4.621791 0.6809702
#> [5,] -1.481276 9.575162 4.188177 -4.6217907 117.802646 3.8172886
#> [6,] 7.275273 -4.605958 2.640250 0.6809702 3.817289 68.1195239
#>