% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/person_parameters.R
\name{RMpersonParameters}
\alias{RMpersonParameters}
\title{Person Locations for a Rasch / Partial Credit Model}
\usage{
RMpersonParameters(
  data,
  method = c("WLE", "EAP"),
  item_params = NULL,
  estimator = c("CML", "MML"),
  theta_range = c(-10, 10),
  prior_mean = 0,
  prior_sd = NULL,
  output = c("kable", "dataframe", "ggplot", "file"),
  filename = NULL
)
}
\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{method}{Character. \code{"WLE"} (default) for Warm's Weighted
Likelihood Estimate (lower bias than MLE; Warm, 1989), or \code{"EAP"}
for the Expected A Posteriori estimate under a normal prior.}

\item{item_params}{Optional pre-specified item parameters, e.g. for
anchoring or equating. Either a named list of Andrich-threshold
vectors (one per item) or the long-format data.frame returned by
\code{\link[=RMitemParameters]{RMitemParameters()}}. When \code{NULL} (default) item parameters are
estimated from \code{data}.}

\item{estimator}{Character. How item parameters are estimated when
\code{item_params} is \code{NULL}: \code{"CML"} (default, via \pkg{psychotools}) or
\code{"MML"} (via \pkg{mirt}). Ignored when \code{item_params} is supplied.}

\item{theta_range}{Numeric length 2. Search range for the WLE root
and bounds for the EAP quadrature grid. Default \code{c(-10, 10)}. Only
if the WLE root falls outside this range is the boundary returned.}

\item{prior_mean}{Numeric. Mean of the normal prior used by
\code{method = "EAP"}. Default \code{0}, the natural choice when item
parameters are centred at mean difficulty zero. Ignored for WLE.}

\item{prior_sd}{Numeric or \code{NULL}. Standard deviation of the normal
prior used by \code{method = "EAP"}. When \code{NULL} (default) it is
estimated from the data by marginal maximum likelihood, holding the
item parameters fixed. Supply a number (e.g. \code{1} for a standard
\code{N(0, 1)} prior, or a value carried over from a reference sample
for equating) to fix it. Ignored for WLE.}

\item{output}{Character. \code{"kable"} (default) for a formatted
\code{\link[knitr:kable]{knitr::kable()}} table, \code{"dataframe"} for the underlying
data.frame, \code{"ggplot"} for a histogram of the estimated person
locations, or \code{"file"} to write the data.frame to a CSV at
\code{filename} (the data.frame is also returned invisibly).}

\item{filename}{Character. Path to the CSV file to write when
\code{output = "file"}. Required in that case; ignored otherwise.}
}
\value{
For \code{output = "dataframe"}, a data.frame with one row per respondent
(in input order; respondents with no responses are dropped with a
message) and columns \code{theta} (the person location), \code{sem}
(standard error of measurement), \code{sum_score}, \code{n_answered} (number of
non-missing responses), and \code{extreme} (logical: a minimum or maximum
possible score given the items answered). For \code{output = "kable"}, the
same content as a \code{knitr_kable} object. For \code{output = "ggplot"}, a
histogram of \code{theta}.
}
\description{
Estimates a person location (theta) and its standard error of
measurement (SEM) for every respondent. Estimation is performed
directly on each person's observed response pattern, so partial
missingness is handled correctly: two respondents with the same sum
score on different subsets of items receive different estimates. This
avoids the sum-score lookup used by \code{\link[=RMscoreSE]{RMscoreSE()}}, which assumes
complete data.
}
\details{
Item parameters are obtained once (by CML or MML, or taken from
\code{item_params}) and treated as fixed. Each person's theta is then
estimated from the items they answered.

\strong{WLE} solves Warm's weighted-likelihood score equation
\verb{l'(theta) + J(theta) / (2 I(theta)) = 0} by bracketed root finding,
where the bias-correction term \verb{J / (2 I)} keeps the equation solvable
at the boundaries. The SEM is \code{1 / sqrt(I(theta))}. Unlike the MLE,
Warm's estimator therefore yields \emph{finite} locations for the minimum
and maximum possible scores (a sensible step beyond the next-most
extreme score rather than +/-Inf; cf. Warm, 1989), matching
established implementations such as \pkg{catR} and \pkg{TAM}. Such
scores are still marked in the \code{extreme} column because they are
extrapolated and carry large standard errors. Only if the root lies
outside \code{theta_range} is the boundary returned with \code{NA} SEM.

\strong{EAP} integrates the pattern likelihood against a normal prior
over a quadrature grid; the estimate is the posterior mean and the
SEM is the posterior standard deviation. Unlike WLE, EAP is finite at
extreme scores because the prior shrinks them inward, at the cost of
depending on the assumed prior. The prior actually used -- including
the marginal-ML estimate of \code{prior_sd} when it is left \code{NULL} -- is
reported in the kable caption and attached to the result as
\code{attr(result, "prior")}.
}
\examples{
\donttest{
set.seed(1)
dat <- as.data.frame(
  matrix(sample(0:2, 200 * 6, replace = TRUE), nrow = 200, ncol = 6)
)
colnames(dat) <- paste0("Item", 1:6)
# Introduce some missingness
dat[cbind(sample(200, 30), sample(6, 30, replace = TRUE))] <- NA

# Default: WLE person locations
RMpersonParameters(dat, output = "dataframe") |> head()

# EAP with a data-estimated prior SD
eap <- RMpersonParameters(dat, method = "EAP", output = "dataframe")
attr(eap, "prior")

# EAP with a fixed N(0, 1) prior
RMpersonParameters(dat, method = "EAP", prior_sd = 1, output = "dataframe") |>
  head()

# Write the person-location table to a CSV (also returned invisibly)
RMpersonParameters(dat, output = "file",
                   filename = tempfile(fileext = ".csv"))
}
}
\references{
Warm, T. A. (1989). Weighted likelihood estimation of ability in item
response theory. \emph{Psychometrika, 54}(3), 427-450.
\doi{10.1007/BF02294627}

Bock, R. D., & Mislevy, R. J. (1982). Adaptive EAP estimation of
ability in a microcomputer environment. \emph{Applied Psychological
Measurement, 6}(4), 431-444. \doi{10.1177/014662168200600405}

Magis, D. (2015). A note on weighted likelihood and Jeffreys modal
estimation of proficiency levels in polytomous item response models.
\emph{Psychometrika, 80}(1), 200-204. \doi{10.1007/s11336-013-9378-5}
}
\seealso{
\code{\link[=RMitemParameters]{RMitemParameters()}}, \code{\link[=RMscoreSE]{RMscoreSE()}}, \code{\link[=RMreliability]{RMreliability()}}
}
