% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/get_sigma.R
\name{get_sigma}
\alias{get_sigma}
\title{Get residual standard deviation from models}
\usage{
get_sigma(x, ci = NULL, verbose = TRUE)
}
\arguments{
\item{x}{A model.}

\item{ci}{Scalar, the CI level. The default (\code{NULL}) returns no CI.}

\item{verbose}{Toggle messages and warnings.}
}
\value{
The residual standard deviation (sigma), or \code{NULL} if this
information could not be accessed.
}
\description{
Returns \code{sigma}, which corresponds the estimated standard
deviation of the residuals. This function extends the \code{sigma()} base R
generic for models that don't have implemented it. It also computes the
confidence interval (CI), which is stored as an attribute.

Sigma is a key-component of regression models, and part of the so-called
auxiliary parameters that are estimated. Indeed, linear models for instance
assume that the residuals comes from a normal distribution with mean 0 and
standard deviation \code{sigma}. See the details section below for more
information about its interpretation and calculation.
}
\section{Interpretation of Sigma}{

The residual standard deviation, \ifelse{html}{\out{&sigma;}}{\eqn{\sigma}},
indicates that the predicted outcome will be within +/-
\ifelse{html}{\out{&sigma;}}{\eqn{\sigma}} units of the linear predictor for
approximately \verb{68\%} of the data points (\emph{Gelman, Hill & Vehtari 2020, p.84}).
In other words, the residual standard deviation indicates the accuracy for a
model to predict scores, thus it can be thought of as "a measure of the
average distance each observation falls from its prediction from the model"
(\emph{Gelman, Hill & Vehtari 2020, p.168}).
\ifelse{html}{\out{&sigma;}}{\eqn{\sigma}} can be considered as a measure of
the unexplained variation in the data, or of the precision of inferences
about regression coefficients.
}

\section{Calculation of Sigma}{

By default, \code{get_sigma()} tries to extract sigma by calling \code{stats::sigma()}.
If the model-object has no \code{sigma()} method, the next step is calculating
sigma as square-root of the model-deviance divided by the residual degrees of
freedom. Finally, if even this approach fails, and \code{x} is a mixed model, the
residual standard deviation is accessed using the square-root from
\code{get_variance_residual()}.
}

\examples{
data(mtcars)
m <- lm(mpg ~ wt + cyl + vs, data = mtcars)
get_sigma(m)
}
\references{
Gelman, A., Hill, J., & Vehtari, A. (2020). Regression and Other
Stories. Cambridge University Press.
}
