Abstraction for Statistical Models
StatsAPI.jl defines an abstract type StatisticalModel
, and an abstract subtype RegressionModel
. They are both extended by StatsBase, and documented here.
Particularly, instances of StatisticalModel
implement the following methods.
#
StatsAPI.adjr2
— Function
adjr2(model::StatisticalModel)
adjr²(model::StatisticalModel)
Adjusted coefficient of determination (adjusted R-squared).
For linear models, the adjusted R² is defined as , with the coefficient of determination, the number of observations, and the number of coefficients (including the intercept). This definition is generally known as the Wherry Formula I.
adjr2(model::StatisticalModel, variant::Symbol) adjr²(model::StatisticalModel, variant::Symbol)
Adjusted pseudo-coefficient of determination (adjusted pseudo R-squared). For nonlinear models, one of the several pseudo R² definitions must be chosen via variant
. The only currently supported variants are :MacFadden
, defined as and :devianceratio
, defined as . In these formulas, is the likelihood of the model, that of the null model (the model including only the intercept), is the deviance of the model, is the deviance of the null model, is the number of observations (given by nobs
) and is the number of consumed degrees of freedom of the model (as returned by dof
).
#
StatsAPI.aic
— Function
aic(model::StatisticalModel)
Akaike’s Information Criterion, defined as , with the likelihood of the model, and k
its number of consumed degrees of freedom (as returned by dof
).
#
StatsAPI.aicc
— Function
aicc(model::StatisticalModel)
Corrected Akaike’s Information Criterion for small sample sizes (Hurvich and Tsai 1989), defined as , with the likelihood of the model, its number of consumed degrees of freedom (as returned by dof
), and the number of observations (as returned by nobs
).
#
StatsAPI.bic
— Function
bic(model::StatisticalModel)
Bayesian Information Criterion, defined as , with the likelihood of the model, its number of consumed degrees of freedom (as returned by dof
), and the number of observations (as returned by nobs
).
#
StatsAPI.coef
— Function
coef(model::StatisticalModel)
Return the coefficients of the model.
#
StatsAPI.coefnames
— Function
coefnames(model::StatisticalModel)
Return the names of the coefficients.
#
StatsAPI.coeftable
— Function
coeftable(model::StatisticalModel; level::Real=0.95)
Return a table with coefficients and related statistics of the model. level
determines the level for confidence intervals (by default, 95%).
The returned CoefTable
object implements the Tables.jl interface, and can be converted e.g. to a DataFrame
via using DataFrames; DataFrame(coeftable(model))
.
#
StatsAPI.confint
— Function
confint(model::StatisticalModel; level::Real=0.95)
Compute confidence intervals for coefficients, with confidence level level
(by default 95%).
#
StatsAPI.deviance
— Function
deviance(model::StatisticalModel)
Return the deviance of the model relative to a reference, which is usually when applicable the saturated model. It is equal, up to a constant, to , with the likelihood of the model.
#
StatsAPI.dof
— Function
dof(model::StatisticalModel)
Return the number of degrees of freedom consumed in the model, including when applicable the intercept and the distribution’s dispersion parameter.
#
StatsAPI.fit
— Function
Fit a statistical model.
#
StatsAPI.fit!
— Function
Fit a statistical model in-place.
#
StatsAPI.informationmatrix
— Function
informationmatrix(model::StatisticalModel; expected::Bool = true)
Return the information matrix of the model. By default the Fisher information matrix is returned, while the observed information matrix can be requested with expected = false
.
#
StatsAPI.isfitted
— Function
isfitted(model::StatisticalModel)
Indicate whether the model has been fitted.
#
StatsAPI.islinear
— Function
islinear(model::StatisticalModel)
Indicate whether the model is linear.
#
StatsAPI.loglikelihood
— Function
loglikelihood(model::StatisticalModel)
loglikelihood(model::StatisticalModel, observation)
Return the log-likelihood of the model.
With an observation
argument, return the contribution of observation
to the log-likelihood of model
.
If observation
is a Colon
, return a vector of each observation’s contribution to the log-likelihood of the model. In other words, this is the vector of the pointwise log-likelihood contributions.
In general, sum(loglikehood(model, :)) == loglikelihood(model)
.
#
StatsAPI.mss
— Function
mss(model::StatisticalModel)
Return the model sum of squares.
#
StatsAPI.nobs
— Function
nobs(model::StatisticalModel)
Return the number of independent observations on which the model was fitted. Be careful when using this information, as the definition of an independent observation may vary depending on the model, on the format used to pass the data, on the sampling plan (if specified), etc.
#
StatsAPI.nulldeviance
— Function
nulldeviance(model::StatisticalModel)
Return the deviance of the null model, obtained by dropping all independent variables present in model
.
If model
includes an intercept, the null model is the one with only the intercept; otherwise, it is the one without any predictor (not even the intercept).
#
StatsAPI.nullloglikelihood
— Function
nullloglikelihood(model::StatisticalModel)
Return the log-likelihood of the null model, obtained by dropping all independent variables present in model
.
If model
includes an intercept, the null model is the one with only the intercept; otherwise, it is the one without any predictor (not even the intercept).
#
StatsAPI.r2
— Function
r2(model::StatisticalModel)
r²(model::StatisticalModel)
Coefficient of determination (R-squared).
For a linear model, the R² is defined as , with the explained sum of squares and the total sum of squares.
r2(model::StatisticalModel, variant::Symbol) r²(model::StatisticalModel, variant::Symbol)
Pseudo-coefficient of determination (pseudo R-squared).
For nonlinear models, one of several pseudo R² definitions must be chosen via variant
. Supported variants are:
-
:MacFadden
(a.k.a. likelihood ratio index), defined as ; -
:CoxSnell
, defined as ; -
:Nagelkerke
, defined as . -
:devianceratio
, defined as .
In the above formulas, is the likelihood of the model, is the likelihood of the null model (the model with only an intercept), is the deviance of the model (from the saturated model), is the deviance of the null model, is the number of observations (given by nobs
).
The Cox-Snell and the deviance ratio variants both match the classical definition of R² for linear models.
#
StatsAPI.rss
— Function
rss(model::StatisticalModel)
Return the residual sum of squares of the model.
#
StatsAPI.score
— Function
score(model::StatisticalModel)
Return the score of the model, that is the gradient of the log-likelihood with respect to the coefficients.
#
StatsAPI.stderror
— Function
stderror(model::StatisticalModel)
Return the standard errors for the coefficients of the model.
#
StatsAPI.vcov
— Function
vcov(model::StatisticalModel)
Return the variance-covariance matrix for the coefficients of the model.
#
StatsAPI.weights
— Function
weights(model::StatisticalModel)
Return the weights used in the model.
RegressionModel
extends StatisticalModel
by implementing the following additional methods.
#
StatsAPI.crossmodelmatrix
— Function
crossmodelmatrix(model::RegressionModel)
Return X’X
where X
is the model matrix of model
. This function will return a pre-computed matrix stored in model
if possible.
#
StatsAPI.dof_residual
— Function
dof_residual(model::RegressionModel)
Return the residual degrees of freedom of the model.
#
StatsAPI.fitted
— Function
fitted(model::RegressionModel)
Return the fitted values of the model.
#
StatsAPI.leverage
— Function
leverage(model::RegressionModel)
Return the diagonal of the projection matrix of the model.
#
StatsAPI.cooksdistance
— Function
cooksdistance(model::RegressionModel)
Compute Cook’s distance for each observation in linear model model
, giving an estimate of the influence of each data point.
#
StatsAPI.meanresponse
— Function
meanresponse(model::RegressionModel)
Return the mean of the response.
#
StatsAPI.modelmatrix
— Function
modelmatrix(model::RegressionModel)
Return the model matrix (a.k.a. the design matrix).
#
StatsAPI.response
— Function
response(model::RegressionModel)
Return the model response (a.k.a. the dependent variable).
#
StatsAPI.responsename
— Function
responsename(model::RegressionModel)
Return the name of the model response (a.k.a. the dependent variable).
#
StatsAPI.predict
— Function
predict(model::RegressionModel, [newX])
Form the predicted response of model
. An object with new covariate values newX
can be supplied, which should have the same type and structure as that used to fit model
; e.g. for a GLM it would generally be a DataFrame
with the same variable names as the original predictors.
#
StatsAPI.predict!
— Function
predict!
In-place version of predict
.
#
StatsAPI.residuals
— Function
residuals(model::RegressionModel)
Return the residuals of the model.
An exception type is provided to signal convergence failures during model estimation:
#
StatsBase.ConvergenceException
— Type
ConvergenceException(iters::Int, lastchange::Real=NaN, tol::Real=NaN)
The fitting procedure failed to converge in iters
number of iterations, i.e. the lastchange
between the cost of the final and penultimate iteration was greater than specified tolerance tol
.