% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/binned_residuals.R
\name{binned_residuals}
\alias{binned_residuals}
\title{Binned residuals for binomial logistic regression}
\usage{
binned_residuals(
  model,
  term = NULL,
  n_bins = NULL,
  show_dots = NULL,
  ci = 0.95,
  ci_type = "exact",
  residuals = "deviance",
  iterations = 1000,
  verbose = TRUE,
  ...
)
}
\arguments{
\item{model}{A \code{glm}-object with \emph{binomial}-family.}

\item{term}{Name of independent variable from \code{x}. If not \code{NULL},
average residuals for the categories of \code{term} are plotted; else,
average residuals for the estimated probabilities of the response are
plotted.}

\item{n_bins}{Numeric, the number of bins to divide the data. If
\code{n_bins = NULL}, the square root of the number of observations is
taken.}

\item{show_dots}{Logical, if \code{TRUE}, will show data points in the plot. Set
to \code{FALSE} for models with many observations, if generating the plot is too
time-consuming. By default, \code{show_dots = NULL}. In this case \code{binned_residuals()}
tries to guess whether performance will be poor due to a very large model
and thus automatically shows or hides dots.}

\item{ci}{Numeric, the confidence level for the error bounds.}

\item{ci_type}{Character, the type of error bounds to calculate. Can be
\code{"exact"} (default), \code{"gaussian"} or \code{"boot"}. \code{"exact"} calculates the
error bounds based on the exact binomial distribution, using \code{\link[=binom.test]{binom.test()}}.
\code{"gaussian"} uses the Gaussian approximation, while \code{"boot"} uses a simple
bootstrap method, where confidence intervals are calculated based on the
quantiles of the bootstrap distribution.}

\item{residuals}{Character, the type of residuals to calculate. Can be
\code{"deviance"} (default), \code{"pearson"} or \code{"response"}. It is recommended to
use \code{"response"} only for those models where other residuals are not
available.}

\item{iterations}{Integer, the number of iterations to use for the
bootstrap method. Only used if \code{ci_type = "boot"}.}

\item{verbose}{Toggle warnings and messages.}

\item{...}{Currently not used.}
}
\value{
A data frame representing the data that is mapped in the accompanying
plot. In case all residuals are inside the error bounds, points are black.
If some of the residuals are outside the error bounds (indicated by the
grey-shaded area), blue points indicate residuals that are OK, while red
points indicate model under- or over-fitting for the relevant range of
estimated probabilities.
}
\description{
Check model quality of binomial logistic regression models.
}
\details{
Binned residual plots are achieved by "dividing the data into
categories (bins) based on their fitted values, and then plotting
the average residual versus the average fitted value for each bin."
\emph{(Gelman, Hill 2007: 97)}. If the model were true, one would
expect about 95\% of the residuals to fall inside the error bounds.

If \code{term} is not \code{NULL}, one can compare the residuals in
relation to a specific model predictor. This may be helpful to check if a
term would fit better when transformed, e.g. a rising and falling pattern
of residuals along the x-axis is a signal to consider taking the logarithm
of the predictor (cf. Gelman and Hill 2007, pp. 97-98).
}
\note{
\code{binned_residuals()} returns a data frame, however, the \code{print()}
method only returns a short summary of the result. The data frame itself
is used for plotting. The \code{plot()} method, in turn, creates a ggplot-object.
}
\examples{
model <- glm(vs ~ wt + mpg, data = mtcars, family = "binomial")
result <- binned_residuals(model)
result

# look at the data frame
as.data.frame(result)

\dontshow{if (insight::check_if_installed("see", minimum_version = "0.9.1", quietly = TRUE)) withAutoprint(\{ # examplesIf}
\donttest{
# plot
plot(result, show_dots = TRUE)
}
\dontshow{\}) # examplesIf}
}
\references{
Gelman, A., and Hill, J. (2007). Data analysis using regression and
multilevel/hierarchical models. Cambridge; New York: Cambridge University
Press.
}
