% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/score_se.R
\name{RMscoreSE}
\alias{RMscoreSE}
\title{Raw-Score to Logit Score Transformation Table}
\usage{
RMscoreSE(
  data,
  method = "WLE",
  output = "kable",
  ci_multiplier = 1.96,
  point_size = 3,
  error_width = 0.5,
  theta_range = c(-10, 10)
)
}
\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;
the underlying model fit handles them.}

\item{method}{Character string. Either \code{"WLE"} (default) for Warm's Weighted
Likelihood Estimator computed from a CML-fitted Rasch / Partial Credit
Model via \code{psychotools}, or \code{"EAP"} for Expected A Posteriori sum-score
estimates from an MML-fitted model via \code{mirt}.}

\item{output}{Character string controlling the return value: \code{"kable"}
(default) for a formatted \code{knitr::kable()} table, \code{"dataframe"} for the
underlying data.frame, or \code{"ggplot"} for a \code{ggplot2} figure showing each
raw score's logit estimate with \code{ci_multiplier}-scaled error bars.}

\item{ci_multiplier}{Numeric. Multiplier applied to the standard error to
draw error bars on the figure. Default \code{1.96} (\eqn{\approx}95\% CI under a Gaussian
approximation). Ignored when \code{output != "ggplot"}.}

\item{point_size}{Numeric. Point size for the figure. Default \code{3}.}

\item{error_width}{Numeric. Cap width for error bars on the figure.
Default \code{0.5}.}

\item{theta_range}{Numeric length 2. Theta search range used for boundary
raw scores under WLE estimation. Default \code{c(-10, 10)}. Ignored when
\code{method = "EAP"}.}
}
\value{
\itemize{
\item If \code{output = "kable"}: a \code{knitr_kable} object with columns "Ordinal sum
score", "Logit score", and "Logit std.error", and a caption noting the
estimation method.
\item If \code{output = "dataframe"}: a data.frame with columns \code{raw_score},
\code{logit_score}, and \code{logit_se} (one row per possible raw sum score from 0
to the theoretical maximum).
\item If \code{output = "ggplot"}: a \code{ggplot} object — points at each
(\code{logit_score}, \code{raw_score}) with horizontal error bars at
± \verb{ci_multiplier × logit_se}.
}
}
\description{
For a given set of items, returns the score-to-theta lookup that maps each
possible raw sum score to a person-location estimate (in logits) and its
standard error. Useful when reporting a scale's measurement properties or
converting raw totals to interval-scaled scores for downstream analysis.
}
\details{
The function automatically detects whether the data is dichotomous
(max score 1) or polytomous (max score > 1) and selects the appropriate
Rasch / Partial Credit model.

\strong{\code{method = "WLE"}} fits the model by CML with \code{psychotools::pcmodel()},
centres the item thresholds to grand-mean-zero, and solves Warm's
weighted-likelihood equation for each raw score with the same engine used
by \code{\link[=RMpersonParameters]{RMpersonParameters()}}; the two functions therefore report identical
locations and standard errors. Warm's bias correction yields finite
locations even at the minimum and maximum scores (only a root outside
\code{theta_range} is clamped to the boundary with \code{NA} SE). The reported
\code{logit_se} is the information-based standard error \code{1 / sqrt(I(theta))},
matching \code{catR}, \code{TAM} and most Rasch software.

\strong{\code{method = "EAP"}} fits the model with \code{mirt::mirt(..., itemtype = "Rasch")} (MML) and obtains sum-score-based EAP estimates and posterior
SDs via \code{mirt::fscores(method = "EAPsum", full.scores = FALSE, full.scores.SE = TRUE)}. EAP estimates are finite at all score boundaries
(the prior shrinks them inward), but they depend on the assumed normal
prior on theta. Item parameters from MML differ slightly from the CML
values used by the WLE path; for well-behaved data the difference is small.
}
\examples{
\donttest{
set.seed(42)
sim_data <- as.data.frame(
  matrix(sample(0:3, 200 * 6, replace = TRUE), nrow = 200, ncol = 6)
)
colnames(sim_data) <- paste0("Item", 1:6)

# Default kable output, WLE
RMscoreSE(sim_data)

# Underlying data.frame
RMscoreSE(sim_data, output = "dataframe")

# ggplot figure
if (requireNamespace("ggplot2", quietly = TRUE)) {
  RMscoreSE(sim_data, output = "ggplot")
}

# EAP via mirt
RMscoreSE(sim_data, method = "EAP")
}
}
\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}
}
