% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/simplexreg_influence.R
\name{diag.distances}
\alias{diag.distances}
\title{Distance-Based Influence Diagnostics for Simplex Regression}
\usage{
diag.distances(
  model,
  data,
  type = c("W1", "W2", "H"),
  plot = FALSE,
  verbose = TRUE,
  ncores = 1,
  label.pos = 3,
  plot.type = NULL,
  ...
)
}
\arguments{
\item{model}{An object of class \code{simplexregression}.}

\item{data}{The data frame used to fit \code{model}.}

\item{type}{Character string or integer specifying the distance measure:
\code{"W1"} (default, Wasserstein with \eqn{p_W = 1}),
\code{"W2"} (Wasserstein with \eqn{p_W = 2}), \code{"H"} (Hellinger).}

\item{plot}{Logical; if \code{FALSE} (default), returns the numeric vector
of distances. If \code{TRUE}, produces an index plot with the ad hoc
threshold and flagged-observation labels.}

\item{verbose}{Logical; if \code{TRUE} (default), prints progress during
leave-one-out refitting. Ignored when \code{ncores > 1}, since output
from parallel workers does not reach the main console.}

\item{ncores}{Positive integer specifying the number of CPU cores to use
for the leave-one-out loop. Default is \code{1} (sequential). Values
greater than \code{1} activate parallel computation via
\code{\link[parallel]{parLapply}}. If \code{ncores} exceeds
\code{parallel::detectCores() - 1}, it is clamped to that value with a
warning to avoid overloading the system. A safe explicit choice is
\code{parallel::detectCores() - 1}.}

\item{label.pos}{Position(s) for outlier labels in the plot. Can be a
single value (applied to all labels) or a vector. Values: 1 = below,
2 = left, 3 = above, 4 = right.}

\item{plot.type}{Character string controlling the plot style when
\code{plot = TRUE}. If \code{NULL} (default), uses \code{"h"} for
\eqn{n \le 150} and \code{"p"} for \eqn{n > 150} (automatic). Passed
to the \code{type} argument of \code{plot()}.}

\item{...}{Additional graphical parameters passed to \code{plot()}.}
}
\value{
If \code{plot = FALSE}, a list containing:
\describe{
  \item{\code{distances}}{Numeric vector of length \eqn{n} with the
    leave-one-out distances.}
  \item{\code{threshold}}{Named numeric scalar with the ad hoc upper
    threshold.}
  \item{\code{outliers}}{Data frame of flagged observations (index and
    distance value). An empty data frame if no observations are flagged.}
  \item{\code{type}}{Distance type used (full label).}
  \item{\code{n}}{Number of observations.}
}
If \code{plot = TRUE}, the same list is returned invisibly.
}
\description{
Computes leave-one-out influence measures based on
distributional distances (Wasserstein with \eqn{p_W = 1} and \eqn{p_W = 2} or
Hellinger) for simplex regression models, as proposed by Justino and
Cribari-Neto (2026).
}
\details{
For each observation \eqn{i}, the model is refit on the dataset with
observation \eqn{i} removed. The chosen distance between the full-model
and leave-one-out fitted distributions is then computed pointwise across
all \eqn{n} observations and summed to produce the scalar influence
measure \eqn{d_i}.

\strong{Ad hoc threshold} uses an asymmetric IQR spread adjusted for
skewness, as proposed by Justino and Cribari-Neto (2026). Let \eqn{Q(p)} denote the
empirical \eqn{p}-th quantile of the distances \eqn{d_i}, the threshold is
\deqn{\text{threshold} = Q(0.75) + (1 + a)(Q(0.75) - Q(0.25))}
where \eqn{a} is the sample skewness of the distances. Observations with
\eqn{d_i} above this threshold are flagged as potentially influential.

\strong{Warning:} for \eqn{n > 500}, the numerical integration used
internally by the distance functions may be slow. Consider using a subset
or a faster integration method.

\strong{Parallel computation:} when \code{ncores > 1}, the
leave-one-out loop is distributed across workers using
\code{\link[parallel]{parLapply}} from the \pkg{parallel} package
(included in base R). Each worker receives the necessary objects and
loads the \pkg{simplexregression} package. The random-number stream is
initialized with \code{\link[parallel]{clusterSetRNGStream}} to ensure
reproducibility across runs. Progress messages (\code{verbose}) are
suppressed in parallel mode because worker output does not reach the
main console.
}
\examples{
data(ReadingSkills, package = "SimplexRegression")
fit <- simplexreg(accuracy ~ dyslexia * iq | dyslexia + iq + I(iq^2),
                 data = ReadingSkills)

\donttest{
# Sequential (default) — Wasserstein W1
dd <- diag.distances(fit, data = ReadingSkills, type = "W1")

# Index plot with flagged observations
diag.distances(fit, data = ReadingSkills, type = "W1", plot = TRUE)

# Hellinger distance
diag.distances(fit, data = ReadingSkills, type = "H", plot = TRUE)
}


}
\references{
Justino, M. E. C. and Cribari-Neto, F. (2026).
Influence diagnostics in beta regression via Hellinger and Wasserstein
distances. \emph{Statistical Papers}, \bold{67}(3), 50.
\doi{10.1007/s00362-026-01823-0}
}
\seealso{
\code{\link{diag.im}}, \code{\link{local.influence}},
\code{\link{gleverage}}.
}
