# Interacting with a model

The API allows for:

- build/estimate models
- query models for statistics (e.g., goodness-of-fit statistics), components (parameter estimates)
- export model estimates

## Core Functionality

`Econometrics`

— Module```
Econometrics
Econometrics in Julia.
```

`Econometrics.EconometricModel`

— Type```
EconometricModel(estimator::Type{<:Union{EconometricModel,ModelEstimator}},
f::FormulaTerm,
data;
contrasts::Dict{Symbol} = Dict{Symbol,Union{<:AbstractContrasts,<:AbstractTerm}}(),
wts::Union{Nothing,Symbol} = nothing,
panel::Union{Nothing,Symbol} = nothing,
time::Union{Nothing,Symbol} = nothing,
vce::VCE = OIM)
```

Formula has syntax:

`@formula(response ~ exogenous + (endogenous ~ instruments) + absorb(highdimscontrols))`

Data must implement the Tables.jl API and use CategoricalArrays (CategoricalVector)

Weights are taken as `StatsBase.FrequencyWeights`

Panel and time indicators are used for longitudinal estimators

**Examples**

```
model = fit(EconometricModel, formula, data, kwargs...)
model = fit(BetweenEstimator, formula, data, panel = :panel, kwargs...)
model = fit(RandomEffectsEstimator, formula, data, panel = :panel, time = :time, kwargs...)
```

## Statistical/Regression Model Abstraction

`StatsBase.aic`

— Function`aic(model::StatisticalModel)`

Akaike's Information Criterion, defined as $-2 \log L + 2k$, with $L$ the likelihood of the model, and `k`

its number of consumed degrees of freedom (as returned by `dof`

).

`StatsBase.aicc`

— Function`aicc(model::StatisticalModel)`

Corrected Akaike's Information Criterion for small sample sizes (Hurvich and Tsai 1989), defined as $-2 \log L + 2k + 2k(k-1)/(n-k-1)$, with $L$ the likelihood of the model, $k$ its number of consumed degrees of freedom (as returned by `dof`

), and $n$ the number of observations (as returned by `nobs`

).

`StatsBase.bic`

— Function`StatsBase.r2`

— Function```
r2(model::StatisticalModel)
r²(model::StatisticalModel)
```

Coefficient of determination (R-squared).

For a linear model, the R² is defined as $ESS/TSS$, with $ESS$ the explained sum of squares and $TSS$ 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 $1 - \log (L)/\log (L_0)$;`:CoxSnell`

, defined as $1 - (L_0/L)^{2/n}$;`:Nagelkerke`

, defined as $(1 - (L_0/L)^{2/n})/(1 - L_0^{2/n})$.`:devianceratio`

, defined as $1 - D/D_0$.

In the above formulas, $L$ is the likelihood of the model, $L_0$ is the likelihood of the null model (the model with only an intercept), $D$ is the deviance of the model (from the saturated model), $D_0$ is the deviance of the null model, $n$ 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.

`StatsBase.adjr2`

— Function```
adjr2(model::StatisticalModel)
adjr²(model::StatisticalModel)
```

Adjusted coefficient of determination (adjusted R-squared).

For linear models, the adjusted R² is defined as $1 - (1 - (1-R^2)(n-1)/(n-p))$, with $R^2$ the coefficient of determination, $n$ the number of observations, and $p$ 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 $1 - (\log (L) - k)/\log (L0)$ and `:devianceratio`

, defined as $1 - (D/(n-k))/(D_0/(n-1))$. In these formulas, $L$ is the likelihood of the model, $L0$ that of the null model (the model including only the intercept), $D$ is the deviance of the model, $D_0$ is the deviance of the null model, $n$ is the number of observations (given by `nobs`

) and $k$ is the number of consumed degrees of freedom of the model (as returned by `dof`

).

`StatsBase.mss`

— Function`mss(model::StatisticalModel)`

Return the model sum of squares.

`StatsBase.rss`

— Function`rss(model::StatisticalModel)`

Return the residual sum of squares of the model.

`StatsBase.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 $-2 \log L$, with $L$ the likelihood of the model.

`StatsBase.nulldeviance`

— Function`nulldeviance(model::StatisticalModel)`

Return the deviance of the null model, that is the one including only the intercept.

`StatsBase.loglikelihood`

— Function`loglikelihood(model::StatisticalModel)`

Return the log-likelihood of the model.

`StatsBase.nullloglikelihood`

— Function`loglikelihood(model::StatisticalModel)`

Return the log-likelihood of the null model corresponding to `model`

. This is usually the model containing only the intercept.

`StatsBase.coef`

— Function`coef(model::StatisticalModel)`

Return the coefficients of the model.

`StatsBase.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.

`StatsBase.dof_residual`

— Function`dof_residual(model::RegressionModel)`

Return the residual degrees of freedom of the model.

`StatsBase.coefnames`

— Method`coefnames(model::StatisticalModel)`

Return the names of the coefficients.

`StatsBase.coeftable`

— Method```
coeftable(obj::EconometricModel;
level::Real = 0.95)
coeftable(obj::EconometricModel{<:LinearModelEstimators};
level::Real = 0.95,
vce::VCE = obj.vce)
```

Return a table of class `CoefTable`

with coefficients and related statistics. `level`

determines the level for confidence intervals (by default, 95%). `vce`

determines the variance-covariance estimator (by default, `OIM`

).

`StatsBase.islinear`

— Function`islinear(model::StatisticalModel)`

Indicate whether the model is linear.

`StatsBase.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`

.

`StatsBase.vcov`

— Method```
vcov(obj::EconometricModel)
vcov(obj::EconometricModel{<:LinearModelEstimators}, vce::VCE = obj.vce)
```

Return the variance-covariance matrix for the coefficients of the model. The `vce`

argument allows to request variance estimators.

`StatsBase.stderror`

— Method```
stderror(obj::EconometricModel)
stderror(obj::EconometricModel{<:LinearModelEstimators}, vce::VCE = obj.vce)
```

Return the standard errors for the coefficients of the model. The `vce`

argument allows to request variance estimators.

`StatsBase.confint`

— Method`confint(obj::EconometricModel; se::AbstractVector{<:Real} = stderror(obj), level::Real = 0.95)`

Compute the confidence intervals for coefficients, with confidence level `level`

(by default, 95%). `se`

can be provided as a precomputed value.

`StatsModels.hasintercept`

— Function`hasintercept(obj::EconometricModel)::Bool`

Return whether the model has an intercept.

`StatsBase.isfitted`

— Function`isfitted(model::StatisticalModel)`

Indicate whether the model has been fitted.

`StatsBase.fit`

— MethodFit a statistical model.

`StatsBase.fit!`

— MethodFit a statistical model in-place.

`StatsBase.response`

— Function`response(model::RegressionModel)`

Return the model response (a.k.a. the dependent variable).

`StatsBase.meanresponse`

— Function`meanresponse(model::RegressionModel)`

Return the mean of the response.

`StatsBase.fitted`

— Function`fitted(model::RegressionModel)`

Return the fitted values of the model.

`StatsBase.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.

`StatsBase.modelmatrix`

— Function`modelmatrix(model::RegressionModel)`

Return the model matrix (a.k.a. the design matrix).

`StatsBase.residuals`

— Function`residuals(model::RegressionModel)`

Return the residuals of the model.

`StatsBase.leverage`

— Function`leverage(model::RegressionModel)`

Return the diagonal of the projection matrix of the model.

`StatsBase.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.

`StatsBase.weights`

— Method`weights(model::StatisticalModel)`

Return the weights used in the model.

## Estimators

`Econometrics.BetweenEstimator`

— Type```
BetweenEstimator(effect::Symbol,
groups::Vector{Vector{Int}}) <: LinearModelEstimators
```

Continuous response estimator collapsing a dimension in a longitudinal setting.

`Econometrics.RandomEffectsEstimator`

— Type```
RandomEffectsEstimator(pid::Tuple{Symbol,Vector{Vector{Int}}},
tid::Tuple{Symbol,Vector{Vector{Int}}},
idiosyncratic::Float64,
individual::Float64,
θ::Vector{Float64}) <: LinearModelEstimators
```

Swamy-Arora estimator.

`Econometrics.VCE`

— Type`VCE`

Variance-covariance estimators.

- Observed Information Matrix (OIM)
- Heteroscedasticity Consistent: HC0, HC1, HC2, HC3, HC4

## Formula Components

`Econometrics.absorb`

— Function`absorb`

Function for constructing the `FunctionTerm{typeof(absorb)}`

used in decompose.