% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/person_fit.R
\name{RMpersonFit}
\alias{RMpersonFit}
\title{Person-Fit Statistics for a Rasch / Partial Credit Model}
\usage{
RMpersonFit(
  data,
  statistics = c("infit", "outfit", "lz"),
  estimator = c("CML", "MML"),
  theta_method = c("WLE", "EAP"),
  iterations = 500L,
  flag_alpha = 0.05,
  flag = c("both", "underfit"),
  zstd = FALSE,
  parallel = FALSE,
  n_cores = NULL,
  seed = NULL,
  output = c("kable", "dataframe", "ggplot", "list")
)
}
\arguments{
\item{data}{A data.frame or matrix of item responses. Items must be
scored starting at 0 (non-negative integers). Missing values (\code{NA})
are allowed.}

\item{statistics}{Character vector. Which statistics to report; any of
\code{"infit"}, \code{"outfit"}, \code{"lz"}. Defaults to all three.}

\item{estimator}{Character. How item parameters are estimated:
\code{"CML"} (default) or \code{"MML"} (via \pkg{mirt}).}

\item{theta_method}{Character. Person-location estimator used for the
lz statistic: \code{"WLE"} (default) or \code{"EAP"}. Ignored if \code{"lz"} is not
requested.}

\item{iterations}{Integer. Number of Monte-Carlo replications per
person. \code{0} skips resampling and returns statistics only. Default
\code{500}.}

\item{flag_alpha}{Numeric in (0, 1). Significance level for the \code{flagged}
column and the plot highlighting. Default \code{0.05}.}

\item{flag}{Character. Which misfit direction drives flagging for the MSQ
statistics: \code{"both"} (default) flags either direction with a two-sided
p-value; \code{"underfit"} flags only underfit (MSQ > 1, noisy responding)
with a one-sided upper p-value, which is more powerful for detecting it
and ignores (benign) overfit. The reported \code{p_infit} / \code{p_outfit} follow
this choice. lz is one-sided regardless. Overfit can occasionally be
suspicious (e.g. fabricated or copied response patterns), so \code{"both"} is
the default.}

\item{zstd}{Logical. If \code{TRUE}, also report the Wilson-Hilferty
standardized (ZSTD) versions of the MSQ statistics. These are
provided only as a familiar cross-person comparability metric and
are \strong{not} used for inference (see Müller, 2020). Default \code{FALSE}.}

\item{parallel, n_cores}{Logical / integer. Parallelise the resampling
across persons via \pkg{mirai} when available. Default sequential.}

\item{seed}{Optional integer for reproducible resampling.}

\item{output}{Character. \code{"kable"} (default), \code{"dataframe"},
\code{"ggplot"}, or \code{"list"}. For \code{"ggplot"}, a \strong{named list} of
person-fit maps is returned -- one per requested statistic (e.g.
\verb{$infit}, \verb{$outfit}, \verb{$lz}) -- each plotting the statistic against
person location, with
respondents flagged by \emph{that} statistic highlighted and a caption
reporting the assessed sample size and the proportion flagged. For the
MSQ maps the flagged count is split into underfit (MSQ > 1, noisy/erratic
responding) and overfit (MSQ < 1, overly deterministic responding).}
}
\value{
For \code{output = "dataframe"}, a data.frame with one row per respondent
(input order): \code{id}, \code{n_answered}, \code{sum_score}, the requested
statistics (\code{infit_msq}, \code{outfit_msq}, \code{lz}), their resampled
p-values (\code{p_infit}, \code{p_outfit}, \code{p_lz}) when \code{iterations > 0},
\code{flagged}, and -- if \code{zstd = TRUE} -- \code{infit_zstd}, \code{outfit_zstd}.
The \code{flagged} column is \code{TRUE} when the marginal (uncorrected) p-value of
\strong{any} requested statistic is below \code{flag_alpha} for that respondent; it
is therefore a per-person screening flag, not corrected for the number of
respondents tested (so under fit expect about \code{flag_alpha} of respondents
to be flagged by chance). Each \code{output = "ggplot"} map instead colours and
counts respondents flagged by its \strong{own} statistic alone. Extreme scorers
(minimum or maximum possible given the items they answered) receive \code{NA}
statistics and are not assessed. For \code{output = "kable"} the same content as
a \code{knitr_kable}; for \code{output = "ggplot"} the named list of maps described
under that argument; for \code{output = "list"}, a list with both views from a
single computation: \code{fit} (the data.frame) and \code{plots} (the named list of
maps).
}
\description{
Computes per-respondent person-fit statistics and resampling-based
p-values. Three statistics are reported: conditional \strong{infit} and
\strong{outfit} mean-squares (MSQ) -- the magnitude (effect-size) measures
familiar from Rasch analysis -- and the standardized log-likelihood
statistic \strong{lz}. The conditional MSQ statistics use response
probabilities conditional on the total score, which require no person
estimate and are therefore unbiased (Kreiner & Christensen, 2011); they are
computed on each person's observed response pattern, so partial
missingness is handled directly.
}
\details{
Statistical significance is assessed by Monte-Carlo resampling under
the fitted model rather than by an assumed asymptotic distribution.
The asymptotic null distributions of MSQ and lz are known to be
unreliable -- the Wilson-Hilferty (ZSTD) transformation of MSQ in
particular adds nothing once conditional estimation is used (Müller,
2020) -- so resampling provides the valid reference (Sinharay, 2016).

\strong{Conditional MSQ.} For person \eqn{v} with answered items
\eqn{A_v} and total score \eqn{r_v}, the conditional residual is
\eqn{z_{vi} = (x_{vi} - E(X_{vi} \mid R_v = r_v)) /
\sqrt{\mathrm{Var}(X_{vi} \mid R_v = r_v)}}, with conditional moments
obtained from elementary symmetric functions of the answered items'
parameters. Outfit is the unweighted mean of \eqn{z_{vi}^2}; infit is
the information-weighted mean. Because the conditional moments use only
item parameters, no (biased) person estimate enters the residual.

\strong{Interpreting MSQ direction.} Values near 1 indicate fit. MSQ > 1
(\emph{underfit}) means the responses are noisier / more erratic than the
model expects -- the validity-relevant direction, indicating careless or
aberrant responding. MSQ < 1 (\emph{overfit}) means responses are overly
deterministic (Guttman-like); usually benign for score validity, though a
suspiciously perfect pattern can occasionally signal copied or fabricated
data. Use \code{flag = "underfit"} to flag only the former. lz is one-sided:
low (negative) values flag the aberrant (underfit-like) direction.

\strong{lz.} The standardized log-likelihood of the response pattern
evaluated at the estimated person location (Drasgow, Levine &
Williams, 1985); small (negative) values indicate misfit. Because the
location is estimated rather than known, the variance of lz is below 1
and its asymptotic standard-normal null is invalid, which makes a
naive test conservative (Snijders, 2001; Sinharay, 2016). Instead of
applying the analytic lz\* standardization -- derived by Snijders (2001)
for dichotomous items and extended to polytomous / mixed-format items by
Sinharay (2016, 2026) -- easyRasch2 obtains the reference distribution by
resampling with the person location \strong{re-estimated for every
simulated pattern} (see \strong{Resampling}). This reproduces the
ability-estimation effect and is the resampling analogue of lz\*, so the
resampled p-value is well calibrated.

\strong{Resampling.} Each statistic is referenced against the null that
matches it, removing the need to choose a scheme. The conditional MSQ
statistics use patterns sampled \strong{conditional on the person's total
score} -- the exact Rasch-native null, requiring no person estimate and
fully consistent with the (conditional) statistic. lz, which is defined at
the estimated location, uses patterns \strong{simulated at that location and then
scored with the location re-estimated from each simulated pattern}, so the
null carries the same ability-estimation effect as the observed lz (for a
Rasch / PCM model the location is a function of the total score, so this
re-estimation is a cheap score-based lookup). Both schemes are computed per
person over the items actually answered, so partial missingness is handled
by either. The p-value is the proportion of the \code{iterations} replicates at
least as extreme as the observed value. This follows the resampling-based
person-fit approach (Sinharay, 2016) and the bootstrap recommendation of
Müller (2020).
}
\examples{
\donttest{
set.seed(1)
dat <- as.data.frame(
  matrix(sample(0:2, 200 * 8, replace = TRUE), nrow = 200, ncol = 8)
)
colnames(dat) <- paste0("Item", 1:8)

# Conditional infit/outfit MSQ + lz with resampled p-values
RMpersonFit(dat, iterations = 200, output = "dataframe") |> head()

# Person-fit maps: a named list with one plot per statistic
if (requireNamespace("ggplot2", quietly = TRUE)) {
  plots <- RMpersonFit(dat, iterations = 200, output = "ggplot")
  plots$infit    # infit map (each plot's caption reports the \% flagged)
}

# Flag only underfit (noisy responding), the validity-relevant direction
RMpersonFit(dat, iterations = 200, flag = "underfit",
            output = "dataframe") |> head()
}
}
\references{
de la Torre, J., & Deng, W. (2008). Improving person-fit assessment by
correcting the ability estimate and its reference distribution.
\emph{Journal of Educational Measurement, 45}(2), 159-177.
\doi{10.1111/j.1745-3984.2008.00058.x}

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. \doi{10.1111/j.2044-8317.1985.tb00817.x}

Kreiner, S., & Christensen, K. B. (2011). Exact evaluation of bias in
Rasch model residuals. \emph{Advances in Mathematics Research, 12},
19-40.

Müller, M. (2020). Item fit statistics for Rasch analysis: can we
trust them? \emph{Journal of Statistical Distributions and Applications,
7}(5). \doi{10.1186/s40488-020-00108-7}

Sinharay, S. (2016). Assessment of person fit using resampling-based
approaches. \emph{Journal of Educational Measurement, 53}(1), 63-85.
\doi{10.1111/jedm.12101}

Sinharay, S. (2016). Asymptotically correct standardization of
person-fit statistics beyond dichotomous items. \emph{Psychometrika,
81}(4), 992-1013. \doi{10.1007/s11336-015-9465-x}

Sinharay, S. (2026). Refining the asymptotically correct
standardization of person-fit statistics for mixed-format tests.
\emph{British Journal of Mathematical and Statistical Psychology}.
\doi{10.1111/bmsp.70049}

Snijders, T. A. B. (2001). Asymptotic null distribution of person fit
statistics with estimated person parameter. \emph{Psychometrika, 66}(3),
331-342. \doi{10.1007/BF02294440}
}
\seealso{
\code{\link[=RMpersonParameters]{RMpersonParameters()}}, \code{\link[=RMitemInfit]{RMitemInfit()}}, \code{\link[=RMitemParameters]{RMitemParameters()}}
}
