% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/simplexreg_influence.R
\name{diag.im}
\alias{diag.im}
\title{Sample Influence Measures for Simplex Regression Models}
\usage{
diag.im(
  model,
  data,
  type = c("s3", "s5"),
  interval = c("I1", "I2"),
  parameter = c("theta", "beta", "gamma"),
  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 vector specifying measure(s): \code{"s3"}, \code{"s5"},
or both (default).}

\item{interval}{Character string specifying the outlier detection threshold:
\code{"I1"} (default, moderate) or \code{"I2"} (strict).}

\item{parameter}{Character string indicating the parameter block:
\code{"theta"} (default, all parameters), \code{"beta"} (mean submodel),
or \code{"gamma"} (dispersion submodel).}

\item{plot}{Logical; if \code{TRUE}, produces index plots of \eqn{s_{3,i}}
and \eqn{s_{5,i}} with threshold lines and flagged-observation labels.
Default is \code{FALSE}.}

\item{verbose}{Logical; if \code{TRUE} (default), prints progress during
leave-one-out refitting. Ignored (set to \code{FALSE}) 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 silently clamped to that
value to avoid overloading the system. A safe explicit choice is
\code{parallel::detectCores() - 1}.}

\item{label.pos}{Position(s) for outlier labels in 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} (default), a list containing only the
requested measures:
\describe{
  \item{\code{s3_i}}{(if requested) Numeric vector of \eqn{s_{3,i}} values.}
  \item{\code{s5_i}}{(if requested) Numeric vector of \eqn{s_{5,i}} values.}
  \item{\code{outliers_s3}}{(if requested) Data frame of flagged observations
    for \eqn{s_{3,i}}.}
  \item{\code{outliers_s5}}{(if requested) Data frame of flagged observations
    for \eqn{s_{5,i}}.}
  \item{\code{limits_s3}}{(if requested) Named vector with lower and upper
    thresholds for \eqn{s_{3,i}}.}
  \item{\code{limits_s5}}{(if requested) Named vector with lower and upper
    thresholds for \eqn{s_{5,i}}.}
  \item{\code{interval}}{Interval type used.}
  \item{\code{parameter}}{Parameter block used.}
  \item{\code{n}}{Number of observations.}
}
If \code{plot = TRUE}, the same list is returned invisibly.
}
\description{
Computes leave-one-out sample influence measures \eqn{s_{3,i}}
and \eqn{s_{5,i}} for simplex regression models, based on the
information-matrix-based criteria measures proposed by Cribari-Neto,
Vasconcellos and Santana e Silva (2025).
}
\details{
For each observation \eqn{i}, the model is refit on the dataset with
observation \eqn{i} removed. Let \eqn{\hat\theta} and
\eqn{\hat\theta_{(i)}} denote the full and leave-one-out MLEs. Following
Cribari-Neto, Vasconcellos and Santana e Silva (2025), let \eqn{A_n}
denote the sample average of the second-order log-likelihood derivatives
(\eqn{n^{-1}\sum_i \partial^2\ell_i/\partial\theta\partial\theta'}) and
\eqn{B_n} denote the sample average of the outer products of the
individual score vectors
(\eqn{n^{-1}\sum_i (\partial\ell_i/\partial\theta)(\partial\ell_i/\partial\theta)'}),
the two matrices that comprise the information matrix equality. Let
\eqn{A^{(i)}_{n-1}} and \eqn{B^{(i)}_{n-1}} denote these same quantities
recomputed with observation \eqn{i} excluded (i.e. based on \eqn{n-1}
observations).

\strong{Measures computed:}
\deqn{s_{3,i} = m_{3,(i)} / m_3}
\deqn{s_{5,i} = D_i^{\mathrm{mod}} - D_i^{\mathrm{gen}}}

Here \eqn{m_3 = \|\mathrm{vech}(P_n^{-1} B_n P_n^{-\top} - I)\|_2}, where
\eqn{P_n} is obtained from the Cholesky decomposition of \eqn{-A_n}
(i.e. \eqn{-A_n = P_n P_n^\top}); \eqn{m_{3,(i)}} is the same quantity
recomputed with observation \eqn{i} excluded from the sample.

\deqn{D_i^{\mathrm{gen}} = (n-1) \,
  (\hat\theta - \hat\theta_{(i)})^\top (-A^{(i)}_{n-1})
  (\hat\theta - \hat\theta_{(i)})}
\deqn{D_i^{\mathrm{mod}} = (n-1) \,
  (\hat\theta - \hat\theta_{(i)})^\top
  0.5(-A^{(i)}_{n-1} + B^{(i)}_{n-1})
  (\hat\theta - \hat\theta_{(i)})}

If \eqn{-A^{(i)}_{n-1}} is not positive definite, \code{nearPD} is used to
find the nearest positive-definite matrix and a message is printed.

\strong{Threshold intervals} use two asymmetric IQR spreads, as proposed
by Cribari-Neto, Vasconcellos and Santana e Silva (2025). Let
\eqn{Q(p)} denote the empirical \eqn{p}-th quantile of the relevant
measure (\eqn{s_{3,i}} or \eqn{s_{5,i}}, computed separately for each):
\eqn{IQR_1 = Q(0.50) - Q(0.125)} (left) and
\eqn{IQR_2 = Q(0.875) - Q(0.50)} (right).
Limits are \eqn{v - z \cdot IQR_1} (lower) and \eqn{v + z \cdot IQR_2}
(upper), with reference value \eqn{v = 1} for \eqn{s_3} and \eqn{v = 0}
for \eqn{s_5}:
\itemize{
  \item \code{I1} (moderate): \eqn{z = 2.5} for \eqn{s_3};
    \eqn{z = 4.0} for \eqn{s_5}.
  \item \code{I2} (strict): \eqn{z = 5.0} for \eqn{s_3};
    \eqn{z = 8.0} for \eqn{s_5}.
}

\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)
im <- diag.im(fit, data = ReadingSkills, type = "s3", interval = "I1",
              parameter = "theta")

# Produce index plots directly
diag.im(fit, data = ReadingSkills, type = "s3", interval = "I1",
        parameter = "theta", plot = TRUE)
}

}
\references{
Cribari-Neto, F.; Vasconcellos, K. L. P.; Santana e Silva, J. J. (2025).
New strategies for detecting atypical observations based on the information
matrix equality. \emph{Journal of Applied Statistics}, \bold{52},
2873--2893. \doi{10.1080/02664763.2025.2487914}
}
\seealso{
\code{\link{diag.distances}}, \code{\link{local.influence}},
\code{\link{gleverage}}.
}
