% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/reliability.R
\name{RMreliability}
\alias{RMreliability}
\title{Reliability metrics for a Rasch model}
\usage{
RMreliability(
  data,
  conf_int = 0.95,
  draws = 1000,
  rmu_iter = 50,
  estim = "WLE",
  boot = FALSE,
  boot_iter = 200,
  parallel = TRUE,
  n_cores = NULL,
  seed = NULL,
  verbose = FALSE,
  theta_range = c(-10, 10),
  output = "kable"
)
}
\arguments{
\item{data}{A data.frame or matrix of item responses. Items must be scored
starting at 0 (non-negative integers).}

\item{conf_int}{Numeric in (0, 1). HDCI width for both bootstrap CIs and
RMU. Default \code{0.95}.}

\item{draws}{Integer. Number of plausible-value draws drawn from the mirt
model for the RMU calculation. Default \code{1000}. More gives a more stable
RMU; computational cost is mostly linear.}

\item{rmu_iter}{Integer. Number of times \code{\link[=RMUreliability]{RMUreliability()}} is repeated on
the same set of plausible-value draws (each repetition uses a fresh
random column split). Estimates are averaged across repetitions to
stabilise against split-induced variability. Default \code{50}.}

\item{estim}{Character. Theta estimator used by \code{mirt::fscores()} for the
RMU plausible-value seed. One of \code{"WLE"} (default), \code{"EAP"}, \code{"MAP"},
\code{"ML"}. Plausible draws themselves are produced by Metropolis-Hastings.
(PSI and marginal reliability are computed natively and do not use this.)}

\item{boot}{Logical. If \code{TRUE}, run a non-parametric bootstrap to obtain
CIs for PSI and Marginal reliability. Default \code{FALSE}.}

\item{boot_iter}{Integer. Number of bootstrap iterations when
\code{boot = TRUE}. Default \code{200}.}

\item{parallel}{Logical. Use parallel processing via \code{mirai} for the
bootstrap if available. Default \code{TRUE}.}

\item{n_cores}{Integer or \code{NULL}. Number of parallel workers. When \code{NULL},
\code{getOption("mc.cores")} is checked first; if neither is set,
bootstrapping falls back to sequential.}

\item{seed}{Integer or \code{NULL}. Master random seed for reproducibility.}

\item{verbose}{Logical. Print progress messages and a progress bar for
the bootstrap. Default \code{FALSE}.}

\item{theta_range}{Numeric length-2 vector. Theta limits passed to
\code{mirt::fscores()}. Default \code{c(-10, 10)}.}

\item{output}{Character. \code{"kable"} (default) for a formatted
\code{knitr::kable()} table, or \code{"dataframe"} for the underlying data.frame.}
}
\value{
\itemize{
\item If \code{output = "kable"}: a \code{knitr_kable} object with one row per metric.
\item If \code{output = "dataframe"}: a data.frame with columns \code{metric},
\code{estimate}, \code{lower}, \code{upper}, \code{notes}.
}
}
\description{
Computes three reliability indices for a Rasch / partial credit model:
the Person Separation Index (PSI) -- WLE-based separation reliability -- the
marginal reliability (native, CML test information integrated over the
estimated normal latent density), and Relative Measurement Uncertainty (RMU)
via \code{\link[=RMUreliability]{RMUreliability()}} applied to plausible values from \code{mirt::fscores()}.
}
\details{
Confidence intervals for \strong{PSI} and \strong{Marginal} reliability are obtained
by non-parametric bootstrap (resampling respondents; all three indices are
recomputed natively per resample, no model is refitted by \code{mirt}). The RMU
interval is the HDCI of correlations across plausible-value draws, averaged
over \code{rmu_iter} random splits of the draws.

Marginal reliability is the native Green (1984) coefficient,
\eqn{1 - \overline{1/I(\theta)}/\sigma^2}, where the test information
\eqn{I(\theta)} is summed from the CML item parameters and the average error
variance is taken over the estimated normal latent density \eqn{N(0,
\sigma^2)} (\eqn{\sigma} from marginal ML). Unlike \code{mirt::marginal_rxx()},
which assumes \eqn{N(0,1)}, this integrates over the estimated latent
variance, so it is correct on the Rasch logit scale (where \eqn{\sigma}
is typically well above 1, and the \eqn{N(0,1)} assumption
underestimates reliability). It is the model-based complement to the
sample-based PSI; a large gap between the two flags an off-target or
non-normal sample.

PSI is the WLE-based separation reliability,
\eqn{1 - \overline{SEM^2} / \mathrm{Var}(\hat\theta)}, computed from CML item
thresholds (\code{psychotools}) and Warm's WLE person locations / analytic SEMs.
Respondents with extreme (min/max) raw scores are excluded -- their boundary
estimates would inflate the person variance and overstate reliability.
(Earlier versions used \code{eRm::SepRel()} with MLE; the values can differ, most
noticeably for scales with many extreme scorers, e.g. dichotomous items.)

RMU is from Bignardi, Kievit, & Bürkner (2025), modified here to use mirt
plausible values rather than fully Bayesian posterior draws (see Mislevy,
1991, for the plausible-values framework).

Bootstrap iterations that fail to converge are silently dropped.
}
\examples{
\donttest{
if (requireNamespace("ggdist", quietly = TRUE) &&
    requireNamespace("eRm", quietly = TRUE)) {
  set.seed(1)
  RMreliability(eRm::raschdat1[, 1:20], draws = 1000)

  # Bootstrap CI for PSI and Marginal
  # (use more bootstrap iterations, e.g. 200+, in real analyses)
  RMreliability(eRm::raschdat1[, 1:20], draws = 1000,
                boot = TRUE, boot_iter = 25, parallel = FALSE, seed = 42)
}
}
}
\references{
Bignardi, G., Kievit, R., & Bürkner, P. C. (2025). A general method for
estimating reliability using Bayesian Measurement Uncertainty. \emph{PsyArXiv}.
\doi{10.31234/osf.io/h54k8_v1}

Green, B. F., Bock, R. D., Humphreys, L. G., Linn, R. L., & Reckase, M. D.
(1984). Technical Guidelines for Assessing Computerized Adaptive Tests.
\emph{Journal of Educational Measurement, 21}(4), 347–360.
\doi{10.1111/j.1745-3984.1984.tb01039.x}

Mislevy, R. J. (1991). Randomization-Based Inference about Latent Variables
from Complex Samples. \emph{Psychometrika, 56}(2), 177-196.
\doi{10.1007/BF02294457}

Adams, R. J. (2005). Reliability as a measurement design effect.
\emph{Studies in Educational Evaluation, 31}(2), 162-172.
\doi{10.1016/j.stueduc.2005.05.008}
}
\seealso{
\code{\link[=RMUreliability]{RMUreliability()}}
}
