% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/reliability.R
\name{reliability}
\alias{reliability}
\title{Test Reliability Indices}
\usage{
reliability(
  person_params = NULL,
  data = NULL,
  item_params = NULL,
  prior_sd = 1,
  theta_range = c(-4, 4),
  n_points = 61,
  model = NULL,
  D = 1
)
}
\arguments{
\item{person_params}{Optional. A person-parameter data frame containing an
\code{ability}/\code{theta} column and a standard-error column (such as
\code{ability_se} or \code{se}); typically the \code{person_params} element
returned by the estimation functions. Used for the empirical reliability.}

\item{data}{Optional. A data frame of item responses used to compute
Cronbach's alpha (rows = persons, columns = items).}

\item{item_params}{Optional. A data frame of item parameters used to compute
the model-based marginal reliability from the test information function.}

\item{prior_sd}{Numeric. Standard deviation of the population ability
distribution used for the model-based marginal reliability (default
\code{1}).}

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

\item{n_points}{Integer. Number of grid points for the marginal-reliability
integration (default \code{61}).}

\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 the columns \code{Index} and \code{Value},
reporting whichever reliability coefficients could be computed from the
supplied arguments:
\itemize{
\item \code{empirical_reliability}: from person estimates and their SEs.
\item \code{marginal_reliability}: from the test information function.
\item \code{cronbach_alpha}: classical internal-consistency reliability.
\item \code{n_items}, \code{n_persons}: sample descriptors when available.
}
}
\description{
Computes commonly reported reliability coefficients for a test. Depending on
the information supplied it returns the empirical (marginal) reliability from
latent-trait estimates and their standard errors, the model-based marginal
reliability from the test information function, and the classical Cronbach's
alpha from the raw responses. Reliability summarizes how consistently the test
orders examinees and is a standard entry in every technical report.
}
\details{
The empirical reliability is
\eqn{\mathrm{Var}(\hat\theta) / (\mathrm{Var}(\hat\theta) + \overline{SE^2})}.
The model-based marginal reliability is
\eqn{\sigma^2 / (\sigma^2 + \overline{1/I(\theta)})}, where the average error
variance is taken over the population ability distribution. Cronbach's alpha
is \eqn{\frac{J}{J-1}\left(1 - \frac{\sum_j s_j^2}{s_T^2}\right)}.
}
\examples{
  set.seed(123)
  sim <- sim_irt(n_people = 500,
                 item_structure = list(list(model = "2PL", n_items = 12)))
  fit <- binary_irt(sim$resp, model = "2PL", method = "EM",
                    control = list(max_iter = 15, verbose = FALSE))

  reliability(person_params = fit$person_params,
              data = sim$resp,
              item_params = fit$item_params)
}
