% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/devianlm_stats.R
\name{devianlm_stats}
\alias{devianlm_stats}
\title{Identify outliers using devianLM method}
\usage{
devianlm_stats(
  y,
  x,
  threshold = NULL,
  n_sims = 50000,
  verbose = TRUE,
  nthreads = detectCores() - 1,
  quant = 0.95,
  ...
)
}
\arguments{
\item{y}{Numeric. Response vector.}

\item{x}{either a numeric variable or several numeric variables
(explanatory variables) concatenated in a data frame. \code{devianLM} does not
add an intercept automatically; include a column of ones in \code{x}
if an intercept is desired.}

\item{threshold}{Numeric or NULL. If NULL, the threshold value is computed using \code{\link[=get_devianlm_threshold]{get_devianlm_threshold()}}.}

\item{n_sims}{Integer. Optional value which is the number of Monte-Carlo simulations. Default is 50,000.}

\item{verbose}{Logical. If TRUE (default), informative messages are printed during execution (e.g., when ties are detected and handled).}

\item{nthreads}{Integer. Optional value which is the number of threads to use. Default is
\code{parallel::detectCores() - 1}.}

\item{quant}{Numeric. Order of the quantile of interest. Default is 0.95 (this corresponds to a  risk level of 0.05).}

\item{...}{Additional arguments passed to \code{\link[=get_devianlm_threshold]{get_devianlm_threshold()}}.}
}
\value{
devianlm returns an object of class \emph{list} with the following components:
\describe{
\item{reg_residuals}{Numeric vector. The studentized residuals from the linear model.}
\item{outliers}{Integer vector. The indices (positions in the original data) of observations identified as outliers based on the threshold.}
\item{threshold}{Numeric value. The cutoff applied to the absolute value of the studentized residuals to flag outliers. If not provided, it is estimated using \code{get_devianlm_threshold()}.}
\item{is_outliers}{Integer vector. A binary vector (0 or 1) of the same length as \code{reg_residuals}, indicating whether each observation is considered an outlier (1) or not (0).}
}
}
\description{
This function determines whether the maximum of the absolute values
of the studentized residuals of a Gaussian regression is abnormally high.
Outliers are detected by comparing the absolute values of the studentized residuals to a
threshold (depending on the design matrix), which can be supplied or estimated
via \code{n_sims} Monte-Carlo simulations.
}
\details{
When ties are present in \code{y}, a small random perturbation is added to avoid
numerical issues. The "Ties were detected in the data,
they have been randomly broken" message is displayed when this occurs.
}
\examples{
set.seed(123)
y <- salary$hourly_earnings_log
x <- cbind(1, salary$age, salary$educational_attainment, salary$children_number)

test_salary <- devianlm_stats(y, x, n_sims = 100, quant = 0.95)

plot(test_salary$reg_residuals,
  pch = 16, cex = .8,
  ylim = c(-1 * max(abs(test_salary$reg_residuals)), max(abs(test_salary$reg_residuals))),
  xlab = "", ylab = "Studentized residuals",
  col = ifelse(test_salary$is_outliers, "red", "black"))

# Add the thresholds lines:
abline(h = c(-test_salary$threshold, test_salary$threshold), col = "chartreuse2", lwd = 2)
 
}
