% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/check_outliers.R
\name{check_outliers}
\alias{check_outliers}
\alias{check_outliers.default}
\alias{check_outliers.numeric}
\alias{check_outliers.data.frame}
\alias{check_outliers.performance_simres}
\title{Outliers detection (check for influential observations)}
\usage{
check_outliers(x, ...)

\method{check_outliers}{default}(
  x,
  method = c("cook", "pareto"),
  threshold = NULL,
  ID = NULL,
  verbose = TRUE,
  ...
)

\method{check_outliers}{numeric}(x, method = "zscore_robust", threshold = NULL, ...)

\method{check_outliers}{data.frame}(x, method = "mahalanobis", threshold = NULL, ID = NULL, ...)

\method{check_outliers}{performance_simres}(
  x,
  type = "default",
  iterations = 100,
  alternative = "two.sided",
  ...
)
}
\arguments{
\item{x}{A model, a data.frame, a \code{performance_simres} \code{\link[=simulate_residuals]{simulate_residuals()}}
or a \code{DHARMa} object, or an EFA/PCA/Omega object returned by the \strong{psych}
package, or an object returned by \code{parameters::factor_analysis()} or
\code{item_omega()}.}

\item{...}{When \code{method = "ics"}, further arguments in \code{...} are passed
down to \code{\link[ICSOutlier:ics.outlier]{ICSOutlier::ics.outlier()}}. When \code{method = "mahalanobis"},
they are  passed down to \code{\link[stats:mahalanobis]{stats::mahalanobis()}}. \code{percentage_central} can
be specified when \code{method = "mcd"}. For objects of class \code{performance_simres}
or \code{DHARMa}, further arguments are passed down to \code{DHARMa::testOutliers()}.}

\item{method}{The outlier detection method(s). Can be \code{"all"} or some of
\code{"cook"}, \code{"pareto"}, \code{"zscore"}, \code{"zscore_robust"}, \code{"iqr"}, \code{"ci"}, \code{"eti"},
\code{"hdi"}, \code{"bci"}, \code{"mahalanobis"}, \code{"mahalanobis_robust"}, \code{"mcd"}, \code{"ics"},
\code{"optics"} or \code{"lof"}.}

\item{threshold}{A list containing the threshold values for each method (e.g.
\code{list('mahalanobis' = 7, 'cook' = 1)}), above which an observation is
considered as outlier. If \code{NULL}, default values will be used (see
'Details'). If a numeric value is given, it will be used as the threshold for
any of the method run. For EFA/PCA/Omega, indicates the threshold for
correlation of residuals (by default, 0.05).}

\item{ID}{Optional, to report an ID column along with the row number.}

\item{verbose}{Toggle warnings.}

\item{type}{Type of method to test for outliers. Can be one of \code{"default"},
\code{"binomial"} or \code{"bootstrap"}. Only applies when \code{x} is an object returned
by \code{simulate_residuals()} or of class \code{DHARMa}. See 'Details' in
\code{?DHARMa::testOutliers} for a detailed description of the types.}

\item{iterations}{Number of simulations to run.}

\item{alternative}{A character string specifying the alternative hypothesis.
Can be one of \code{"two.sided"}, \code{"less"}, or \code{"greater"}.}
}
\value{
A logical vector of the detected outliers with a nice printing
method: a check (message) on whether outliers were detected or not. The
information on the distance measure and whether or not an observation is
considered as outlier can be recovered with the \link{as.data.frame} function.
Note that the function will (silently) return a vector of \code{FALSE} for
non-supported data types such as character strings.
}
\description{
Checks for and locates influential observations (i.e.,
"outliers") via several distance and/or clustering methods. If several
methods are selected, the returned "Outlier" vector will be a composite
outlier score, made of the average of the binary (0 or 1) results of each
method. It represents the probability of each observation of being
classified as an outlier by at least one method. The decision rule used by
default is to classify as outliers observations which composite outlier
score is superior or equal to 0.5 (i.e., that were classified as outliers
by at least half of the methods). See the \strong{Details} section below
for a description of the methods.
}
\details{
Outliers can be defined as particularly influential observations.
Most methods rely on the computation of some distance metric, and the
observations greater than a certain threshold are considered outliers.
Importantly, outliers detection methods are meant to provide information to
consider for the researcher, rather than to be an automatized procedure which
mindless application is a substitute for thinking.

An \strong{example sentence} for reporting the usage of the composite method
could be:

\emph{"Based on a composite outlier score (see the 'check_outliers' function
in the 'performance' R package; Lüdecke et al., 2021) obtained via the joint
application of multiple outliers detection algorithms (Z-scores, Iglewicz,
1993; Interquartile range (IQR); Mahalanobis distance, Cabana, 2019; Robust
Mahalanobis distance, Gnanadesikan and Kettenring, 1972; Minimum Covariance
Determinant, Leys et al., 2018; Invariant Coordinate Selection, Archimbaud et
al., 2018; OPTICS, Ankerst et al., 1999; Isolation Forest, Liu et al. 2008;
and Local Outlier Factor, Breunig et al., 2000), we excluded n participants
that were classified as outliers by at least half of the methods used."}
}
\note{
There is also a
\href{https://easystats.github.io/see/articles/performance.html}{\code{plot()}-method}
implemented in the \href{https://easystats.github.io/see/}{\strong{see} package}.
\strong{Please note} that the range of the distance-values along the y-axis is
re-scaled to range from 0 to 1.
}
\section{Model-specific methods}{

\itemize{
\item \strong{Cook's Distance}:
Among outlier detection methods, Cook's distance and leverage are less
common than the basic Mahalanobis distance, but still used. Cook's distance
estimates the variations in regression coefficients after removing each
observation, one by one (Cook, 1977). Since Cook's distance is in the metric
of an F distribution with p and n-p degrees of freedom, the median point of
the quantile distribution can be used as a cut-off (Bollen, 1985). A common
approximation or heuristic is to use 4 divided by the numbers of
observations, which usually corresponds to a lower threshold (i.e., more
outliers are detected). This only works for frequentist models. For Bayesian
models, see \code{pareto}.
\item \strong{Pareto}:
The reliability and approximate convergence of Bayesian models can be
assessed using the estimates for the shape parameter k of the generalized
Pareto distribution. If the estimated tail shape parameter k exceeds 0.5, the
user should be warned, although in practice the authors of the \strong{loo}
package observed good performance for values of k up to 0.7 (the default
threshold used by \code{performance}).
}
}

\section{Univariate methods}{

\itemize{
\item \strong{Z-scores} \verb{("zscore", "zscore_robust")}:
The Z-score, or standard score, is a way of describing a data point as
deviance from a central value, in terms of standard deviations from the mean
(\code{"zscore"}) or, as it is here the case (\code{"zscore_robust"}) by
default (Iglewicz, 1993), in terms of Median Absolute Deviation (MAD) from
the median (which are robust measures of dispersion and centrality). The
default threshold to classify outliers is 1.959 (\code{threshold = list("zscore" = 1.959)}),
corresponding to the 2.5\% (\code{qnorm(0.975)}) most extreme observations
(assuming the data is normally distributed). Importantly, the Z-score
method is univariate: it is computed column by column. If a data frame is
passed, the Z-score is calculated for each variable separately, and the
maximum (absolute) Z-score is kept for each observations. Thus, all
observations that are extreme on at least one variable might be detected
as outliers. Thus, this method is not suited for high dimensional data
(with many columns), returning too liberal results (detecting many outliers).
\item \strong{IQR} \code{("iqr")}:
Using the IQR (interquartile range) is a robust method developed by John
Tukey, which often appears in box-and-whisker plots (e.g., in
\link[ggplot2:geom_boxplot]{ggplot2::geom_boxplot}). The interquartile range is the range between the first
and the third quartiles. Tukey considered as outliers any data point that
fell outside of either 1.5 times (the default threshold is 1.7) the IQR below
the first or above the third quartile. Similar to the Z-score method, this is
a univariate method for outliers detection, returning outliers detected for
at least one column, and might thus not be suited to high dimensional data.
The distance score for the IQR is the absolute deviation from the median of
the upper and lower IQR thresholds. Then, this value is divided by the IQR
threshold, to “standardize” it and facilitate interpretation.
\item \strong{CI} \verb{("ci", "eti", "hdi", "bci")}:
Another univariate method is to compute, for each variable, some sort of
"confidence" interval and consider as outliers values lying beyond the edges
of that interval. By default, \code{"ci"} computes the Equal-Tailed Interval
(\code{"eti"}), but other types of intervals are available, such as Highest
Density Interval (\code{"hdi"}) or the Bias Corrected and Accelerated
Interval (\code{"bci"}). The default threshold is \code{0.95}, considering
as outliers all observations that are outside the 95\% CI on any of the
variable. See \code{\link[bayestestR:ci]{bayestestR::ci()}} for more details
about the intervals. The distance score for the CI methods is the absolute
deviation from the median of the upper and lower CI thresholds. Then, this
value is divided by the difference between the upper and lower CI bounds
divided by two, to “standardize” it and facilitate interpretation.
}
}

\section{Multivariate methods}{

\itemize{
\item \strong{Mahalanobis Distance}:
Mahalanobis distance (Mahalanobis, 1930) is often used for multivariate
outliers detection as this distance takes into account the shape of the
observations. The default \code{threshold} is often arbitrarily set to some
deviation (in terms of SD or MAD) from the mean (or median) of the
Mahalanobis distance. However, as the Mahalanobis distance can be
approximated by a Chi squared distribution (Rousseeuw and Van Zomeren, 1990),
we can use the alpha quantile of the chi-square distribution with k degrees
of freedom (k being the number of columns). By default, the alpha threshold
is set to 0.025 (corresponding to the 2.5\\% most extreme observations;
Cabana, 2019). This criterion is a natural extension of the median plus or
minus a coefficient times the MAD method (Leys et al., 2013).
\item \strong{Robust Mahalanobis Distance}:
A robust version of Mahalanobis distance using an Orthogonalized
Gnanadesikan-Kettenring pairwise estimator (Gnanadesikan and Kettenring,
1972). Requires the \strong{bigutilsr} package. See the \code{\link[bigutilsr:covrob_ogk]{bigutilsr::dist_ogk()}}
function.
\item \strong{Minimum Covariance Determinant (MCD)}:
Another robust version of Mahalanobis. Leys et al. (2018) argue that
Mahalanobis Distance is not a robust way to determine outliers, as it uses
the means and covariances of all the data - including the outliers - to
determine individual difference scores. Minimum Covariance Determinant
calculates the mean and covariance matrix based on the most central subset of
the data (by default, 66\\%), before computing the Mahalanobis Distance. This
is deemed to be a more robust method of identifying and removing outliers
than regular Mahalanobis distance.
This method has a \code{percentage_central} argument that allows specifying
the breakdown point (0.75, the default, is recommended by Leys et al. 2018,
but a commonly used alternative is 0.50).
\item \strong{Invariant Coordinate Selection (ICS)}:
The outlier are detected using ICS, which by default uses an alpha threshold
of 0.025 (corresponding to the 2.5\\% most extreme observations) as a cut-off
value for outliers classification. Refer to the help-file of
\code{\link[ICSOutlier:ics.outlier]{ICSOutlier::ics.outlier()}} to get more details about this procedure.
Note that \code{method = "ics"} requires both \strong{ICS} and \strong{ICSOutlier}
to be installed, and that it takes some time to compute the results. You
can speed up computation time using parallel computing. Set the number of
cores to use with \code{options(mc.cores = 4)} (for example).
\item \strong{OPTICS}:
The Ordering Points To Identify the Clustering Structure (OPTICS) algorithm
(Ankerst et al., 1999) is using similar concepts to DBSCAN (an unsupervised
clustering technique that can be used for outliers detection). The threshold
argument is passed as \code{minPts}, which corresponds to the minimum size
of a cluster. By default, this size is set at 2 times the number of columns
(Sander et al., 1998). Compared to the other techniques, that will always
detect several outliers (as these are usually defined as a percentage of
extreme values), this algorithm functions in a different manner and won't
always detect outliers. Note that \code{method = "optics"} requires the
\strong{dbscan} package to be installed, and that it takes some time to compute
the results. Additionally, the \code{optics_xi} (default to 0.05) is passed to
the \code{\link[dbscan:optics]{dbscan::extractXi()}} function to further refine the cluster selection.
\item \strong{Local Outlier Factor}:
Based on a K nearest neighbors algorithm, LOF compares the local density of
a point to the local densities of its neighbors instead of computing a
distance from the center (Breunig et al., 2000). Points that have a
substantially lower density than their neighbors are considered outliers. A
LOF score of approximately 1 indicates that density around the point is
comparable to its neighbors. Scores significantly larger than 1 indicate
outliers. The default threshold of 0.025 will classify as outliers the
observations located at \verb{qnorm(1-0.025) * SD)} of the log-transformed
LOF distance. Requires the \strong{dbscan} package.
}
}

\section{Methods for simulated residuals}{


The approach for detecting outliers based on simulated residuals differs
from the traditional methods and may not be detecting outliers as expected.
Literally, this approach compares observed to simulated values. However, we
do not know the deviation of the observed data to the model expectation, and
thus, the term "outlier" should be taken with a grain of salt. It refers to
"simulation outliers". Basically, the comparison tests whether on observed
data point is outside the simulated range. It is strongly recommended to read
the related documentations in the \strong{DHARMa} package, e.g. \code{?DHARMa::testOutliers}.
}

\section{Threshold specification}{


Default thresholds are currently specified as follows:

\if{html}{\out{<div class="sourceCode">}}\preformatted{list(
  zscore = stats::qnorm(p = 1 - 0.001 / 2),
  zscore_robust = stats::qnorm(p = 1 - 0.001 / 2),
  iqr = 1.7,
  ci = 1 - 0.001,
  eti = 1 - 0.001,
  hdi = 1 - 0.001,
  bci = 1 - 0.001,
  cook = stats::qf(0.5, ncol(x), nrow(x) - ncol(x)),
  pareto = 0.7,
  mahalanobis = stats::qchisq(p = 1 - 0.001, df = ncol(x)),
  mahalanobis_robust = stats::qchisq(p = 1 - 0.001, df = ncol(x)),
  mcd = stats::qchisq(p = 1 - 0.001, df = ncol(x)),
  ics = 0.001,
  optics = 2 * ncol(x),
  optics_xi = 0.05,
  lof = 0.001
)
}\if{html}{\out{</div>}}
}

\section{Meta-analysis models}{

For meta-analysis models (e.g. objects of class \code{rma} from the \emph{metafor}
package or \code{metagen} from package \emph{meta}), studies are defined as outliers
when their confidence interval lies outside the confidence interval of the
pooled effect.
}

\examples{
data <- mtcars # Size nrow(data) = 32

# For single variables ------------------------------------------------------
# Find all observations beyond +/- 2 SD
outliers_list <- check_outliers(data$mpg, method = "zscore", threshold = 2)
outliers_list # Show the row index of the outliers
as.numeric(outliers_list) # The object is a binary vector...
filtered_data <- data[!outliers_list, ] # And can be used to filter a data frame
nrow(filtered_data) # New size, 30 (2 outliers removed)


# For dataframes ------------------------------------------------------
check_outliers(data, threshold = 2) # It works the same way on data frames

# You can also use multiple methods at once
outliers_list <- check_outliers(data, method = c(
  "mahalanobis",
  "iqr",
  "zscore"
))
outliers_list

# Using `as.data.frame()`, we can access more details!
outliers_info <- as.data.frame(outliers_list)
head(outliers_info)
outliers_info$Outlier # Including the probability of being an outlier

# And we can be more stringent in our outliers removal process
filtered_data <- data[outliers_info$Outlier < 0.1, ]

# We can run the function stratified by groups using `{datawizard}` package:
group_iris <- datawizard::data_group(iris, "Species")
check_outliers(group_iris)
# nolint start
\dontshow{if (all(insight::check_if_installed(c("bigutilsr", "MASS", "ICSOutlier", "ICS", "dbscan", "loo", "see"), quietly = TRUE))) withAutoprint(\{ # examplesIf}
# nolint end
\donttest{
# You can also run all the methods
check_outliers(data, method = "all", verbose = FALSE)

# For statistical models ---------------------------------------------
# select only mpg and disp (continuous)
mt1 <- mtcars[, c(1, 3, 4)]
# create some fake outliers and attach outliers to main df
mt2 <- rbind(mt1, data.frame(
  mpg = c(37, 40), disp = c(300, 400),
  hp = c(110, 120)
))
# fit model with outliers
model <- lm(disp ~ mpg + hp, data = mt2)

outliers_list <- check_outliers(model)
plot(outliers_list)

insight::get_data(model)[outliers_list, ] # Show outliers data
}
\dontshow{\}) # examplesIf}
}
\references{
\itemize{
\item Archimbaud, A., Nordhausen, K., and Ruiz-Gazen, A. (2018). ICS for
multivariate outlier detection with application to quality control.
\emph{Computational Statistics and Data Analysis}, \emph{128}, 184-199.
\doi{10.1016/j.csda.2018.06.011}
\item Gnanadesikan, R., and Kettenring, J. R. (1972). Robust estimates, residuals,
and outlier detection with multiresponse data. \emph{Biometrics}, 81-124.
\item Bollen, K. A., and Jackman, R. W. (1985). Regression diagnostics: An
expository treatment of outliers and influential cases. \emph{Sociological Methods
and Research}, \emph{13}(4), 510-542.
\item Cabana, E., Lillo, R. E., and Laniado, H. (2019). Multivariate outlier
detection based on a robust Mahalanobis distance with shrinkage estimators.
arXiv preprint arXiv:1904.02596.
\item Cook, R. D. (1977). Detection of influential observation in linear
regression. \emph{Technometrics}, \emph{19}(1), 15-18.
\item Iglewicz, B., and Hoaglin, D. C. (1993). How to detect and handle outliers
(Vol. 16). Asq Press.
\item Leys, C., Klein, O., Dominicy, Y., and Ley, C. (2018). Detecting
multivariate outliers: Use a robust variant of Mahalanobis distance. \emph{Journal
of Experimental Social Psychology}, 74, 150-156.
\item Liu, F. T., Ting, K. M., and Zhou, Z. H. (2008, December). Isolation forest.
In 2008 Eighth IEEE International Conference on Data Mining (pp. 413-422).
IEEE.
\item Lüdecke, D., Ben-Shachar, M. S., Patil, I., Waggoner, P., and Makowski, D.
(2021). performance: An R package for assessment, comparison and testing of
statistical models. \emph{Journal of Open Source Software}, \emph{6}(60), 3139.
\doi{10.21105/joss.03139}
\item Thériault, R., Ben-Shachar, M. S., Patil, I., Lüdecke, D., Wiernik, B. M.,
and Makowski, D. (2023). Check your outliers! An introduction to identifying
statistical outliers in R with easystats. \emph{Behavior Research Methods}, 1-11.
\doi{10.3758/s13428-024-02356-w}
\item Rousseeuw, P. J., and Van Zomeren, B. C. (1990). Unmasking multivariate
outliers and leverage points. \emph{Journal of the American Statistical
association}, \emph{85}(411), 633-639.
}
}
\seealso{
\code{\link[see:plot.see_check_outliers]{see::plot.see_check_outliers()}} for options to customize the plot.

Other functions to check model assumptions and and assess model quality: 
\code{\link{check_autocorrelation}()},
\code{\link{check_collinearity}()},
\code{\link{check_convergence}()},
\code{\link{check_heteroscedasticity}()},
\code{\link{check_homogeneity}()},
\code{\link{check_model}()},
\code{\link{check_overdispersion}()},
\code{\link{check_predictions}()},
\code{\link{check_singularity}()},
\code{\link{check_zeroinflation}()}
}
\concept{functions to check model assumptions and and assess model quality}
