% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/score_table.R
\name{score_table}
\alias{score_table}
\title{Summed-Score to Theta Conversion Table}
\usage{
score_table(
  item_params,
  method = c("EAP", "WLE", "MLE"),
  prior_mean = 0,
  prior_sd = 1,
  theta_range = c(-4, 4),
  n_points = 81,
  model = NULL,
  D = 1
)
}
\arguments{
\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}}). All models in the package are supported.}

\item{method}{Character. Scoring method: \code{"EAP"} (default),
\code{"WLE"}, or \code{"MLE"}.}

\item{prior_mean, prior_sd}{Mean and standard deviation of the normal
population prior used for the EAP method and for the quadrature weighting
(defaults \code{0} and \code{1}).}

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

\item{n_points}{Integer. Number of ability grid points used to evaluate the
summed-score distributions (default \code{81}).}

\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 possible summed score and the columns:
\itemize{
\item \code{summed_score}: the integer summed score (0 to the maximum
possible score).
\item \code{theta}: the ability estimate for that summed score.
\item \code{se}: the standard error of the ability estimate.
}
}
\description{
Generates a raw-score (summed-score) to scale-score conversion table, mapping
every possible integer summed score to its corresponding ability estimate and
standard error. Such tables are standard in operational testing programs
because they let each examinee's number-correct (or number-of-points) score
be translated directly into a theta estimate without needing the full
response pattern. Three scoring methods are supported: expected a posteriori
(\code{"EAP"}), weighted likelihood (\code{"WLE"}), and maximum likelihood
(\code{"MLE"}).
}
\details{
The distribution of the summed score at each ability grid point is obtained
with the Lord-Wingersky (1984) recursion, which works for any mixture of
dichotomous and polytomous items. The \code{"EAP"} estimate is the mean of
the posterior of theta given the summed score, with \code{se} equal to the
posterior standard deviation. The \code{"MLE"} estimate maximizes the
summed-score likelihood; the \code{"WLE"} estimate (Warm, 1989) maximizes the
summed-score likelihood weighted by the square root of the test information,
which reduces the bias of the MLE. At the two extreme summed scores the MLE is
not finite and is reported at the boundary of \code{theta_range} with a missing
standard error; the WLE remains finite there and is estimated normally.
}
\examples{
  set.seed(123)
  sim <- sim_irt(n_people = 400,
                 item_structure = list(list(model = "2PL", n_items = 10)))
  fit <- binary_irt(sim$resp, model = "2PL", method = "EM",
                    control = list(max_iter = 15, verbose = FALSE))

  # EAP conversion table (0 to 10 correct)
  score_table(fit$item_params, method = "EAP")

  \donttest{
  # Maximum-likelihood conversion table
  score_table(fit$item_params, method = "MLE")
  }
}
\references{
Lord, F. M., & Wingersky, M. S. (1984). Comparison of IRT true-score and
equipercentile observed-score equatings. \emph{Applied Psychological
Measurement, 8}(4), 453-461.

Warm, T. A. (1989). Weighted likelihood estimation of ability in item
response theory. \emph{Psychometrika, 54}(3), 427-450.
}
