% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ld_stats.R
\name{ld_stats}
\alias{ld_stats}
\title{Local Dependence Statistics (Yen's Q3)}
\usage{
ld_stats(
  data,
  item_params,
  theta = NULL,
  theta_range = c(-4, 4),
  n_points = 41,
  model = NULL,
  D = 1
)
}
\arguments{
\item{data}{A data frame of item responses (rows = persons, columns = items).
Dichotomous items are 0/1; polytomous items are consecutive integers
starting at 0.}

\item{item_params}{A data frame of item parameters (the \code{item_params}
element from \code{\link{binary_irt}}, \code{\link{polytomous_irt}}, or
\code{\link{mixed_irt}}). Item order must match the columns of \code{data}.}

\item{theta}{Optional numeric vector of estimated abilities (length equal to
the number of rows in \code{data}), or a person-parameter data frame with
an \code{ability}/\code{theta} column. If \code{NULL} (default), abilities
are estimated internally by expected a posteriori (EAP) scoring from
\code{item_params}.}

\item{theta_range}{Numeric vector of length 2 giving the ability grid bounds
used for internal EAP scoring (default \code{c(-4, 4)}).}

\item{n_points}{Integer. Number of quadrature points for internal EAP scoring
(default \code{41}).}

\item{model}{Optional model override (see \code{\link{item_info}}).}

\item{D}{Scaling constant for the dichotomous logistic metric (default
\code{1}).}
}
\value{
A symmetric numeric matrix of \eqn{Q_3} statistics with one row and
one column per item (diagonal set to \code{1}). The off-diagonal entries
are the residual correlations for each item pair. The average off-diagonal
\eqn{Q_3} is attached as the attribute \code{"mean_q3"} and the largest
absolute value as \code{"max_abs_q3"}.
}
\description{
Computes Yen's (1984) \eqn{Q_3} statistic for every item pair. \eqn{Q_3} is
the correlation between the model residuals of two items after the latent
trait has been partialled out. Under the local-independence assumption of
unidimensional item response theory these residual correlations should be
small and negative (around \eqn{-1/(J-1)}); large positive values signal that
two items share something beyond the common trait, such as a passage or a
scenario. \eqn{Q_3} is therefore used both to decide whether testlet modeling
is needed and to check whether a testlet model has adequately absorbed the
residual dependence.
}
\examples{
  set.seed(123)
  sim <- sim_irt(n_people = 400,
                 item_structure = list(list(model = "2PL", n_items = 8)))
  fit <- binary_irt(sim$resp, model = "2PL", method = "EM",
                    control = list(max_iter = 15, verbose = FALSE))

  q3 <- ld_stats(sim$resp, fit$item_params)
  round(q3, 3)
  attr(q3, "max_abs_q3")
}
\references{
Yen, W. M. (1984). Effects of local item dependence on the fit and equating
performance of the three-parameter logistic model. \emph{Applied
Psychological Measurement, 8}(2), 125-145.
}
