% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/person_fit.R
\name{person_fit}
\alias{person_fit}
\title{Person Fit Statistics (Standardized Log-Likelihood, lz)}
\usage{
person_fit(data, item_params, theta, critical = -1.96, 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. Missing values (\code{NA}) are allowed and are skipped
person-by-person.}

\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}{A numeric vector of estimated person abilities (length equal to
the number of rows in \code{data}), or a person-parameter data frame
containing an \code{ability} or \code{theta} column (such as the
\code{person_params} element returned by the estimation functions).}

\item{critical}{Numeric. Persons with \eqn{l_z} below this value are flagged
as potentially misfitting (default = \code{-1.96}, the lower 2.5\\% point of
the standard normal distribution; \code{-2} is another common choice).}

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

\item{D}{Scaling constant for the dichotomous logistic metric (default
\code{1}).}
}
\value{
A data frame with one row per person and the columns:
\itemize{
\item \code{person}: person index (row number).
\item \code{n_items}: number of items answered.
\item \code{theta}: the ability estimate used.
\item \code{loglik}: the observed log-likelihood of the response pattern.
\item \code{lz}: the standardized log-likelihood person-fit index.
\item \code{flag}: logical; \code{TRUE} if \code{lz < critical}.
}
}
\description{
Computes person-level fit statistics to detect examinees whose response
patterns are unlikely under the fitted item response model (for example,
careless responding, cheating, or unusual guessing). The function returns the
\eqn{l_z} standardized log-likelihood index of Drasgow, Levine, and Williams
(1985), which under model fit is approximately standard normal, and flags
persons whose \eqn{l_z} falls below a critical value.
}
\details{
For a person with ability \eqn{\theta}, let \eqn{l_0} be the log-likelihood of
the observed responses. The index is
\eqn{l_z = (l_0 - E[l_0]) / \sqrt{\mathrm{Var}(l_0)}}, where the expectation
and variance are taken over the model-implied category probabilities at
\eqn{\theta}. Large negative values indicate response patterns that are less
likely than the model predicts.
}
\examples{
  set.seed(123)
  sim <- sim_irt(n_people = 300,
                 item_structure = list(list(model = "2PL", n_items = 15)))
  fit <- binary_irt(sim$resp, model = "2PL", method = "EM",
                    control = list(max_iter = 15, verbose = FALSE))

  pf <- person_fit(sim$resp, fit$item_params, fit$person_params)
  head(pf)

  # How many examinees are flagged as misfitting?
  sum(pf$flag, na.rm = TRUE)
}
\references{
Drasgow, F., Levine, M. V., & Williams, E. A. (1985). Appropriateness
measurement with polychotomous item response models and standardized indices.
\emph{British Journal of Mathematical and Statistical Psychology, 38}(1),
67-86.
}
