% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/rasch.R
\name{rasch}
\alias{rasch}
\title{Fit and diagnose a Rasch model by pairwise conditional estimation}
\usage{
rasch(
  data,
  model = c("PCM", "RSM"),
  id = NULL,
  factors = NULL,
  items = NULL,
  n_groups = NULL,
  adjust_N = NA,
  anchors = NULL,
  na_codes = -1,
  key = NULL,
  pc_components = NULL,
  maxit = 60,
  tol = 1e-08
)
}
\arguments{
\item{data}{Persons-by-items integer score matrix (categories from 0), or a
data frame also containing ID and person-factor columns. Missing values
are allowed.}

\item{model}{Either \code{"PCM"} (partial credit) or \code{"RSM"} (rating
scale).}

\item{id}{Optional name of an ID column in \code{data}, or a vector of IDs;
carried through to the person estimates.}

\item{factors}{Optional character vector of person-factor column names in
\code{data} (for DIF analysis), or a data frame of factors.}

\item{items}{Optional character vector naming the item columns; by default
every column not named in \code{id} or \code{factors}.}

\item{n_groups}{Number of class intervals for the item-trait chi-square
and ANOVA item fit. The default \code{NULL} applies the rule of Andrich
and Marais (2019, ch. 15): as
many intervals of at least 50 non-extreme persons as the sample allows,
at most 10, at least 2. The resolved value is stored in
\code{fit$n_groups}.}

\item{adjust_N}{Optional reference sample size; if supplied, item-trait
chi-squares are rescaled to this size (a sample-size adjustment for the
sensitivity of the chi-square to large samples). The scaling is
proportional and global -- every item's chi-square is multiplied by
\code{adjust_N} over the number of classified persons -- so an item
answered by a subset of persons keeps its proportionally smaller share
of the notional sample rather than being inflated to the full
\code{adjust_N}.}

\item{anchors}{Optional anchor table for equating: a data frame with
columns \code{item}, \code{k}, and \code{tau} fixing nominated
thresholds at known values; see \code{\link{pcml}}. With anchors in
place the scale origin comes from the anchors, so person measures are
directly comparable across separately analysed datasets.}

\item{na_codes}{Values to read as missing. Defaults to \code{-1}, the
conventional missing-response code; any negative score is also treated as
missing, since valid category scores start at zero.}

\item{key}{Optional multiple-choice scoring key, in any of three forms. (1) A named vector or data frame with columns \code{item}
and \code{key} naming each item's correct option: scored 0/1
(case-insensitive after trimming; blanks become missing). (2) Double
keying: several correct options separated by \code{"/"} (for example
\code{"A/C"}), all scoring 1. (3) Polytomous option scoring (Andrich
and Styles 2011): a data frame with columns \code{item},
\code{option}, and \code{score} assigning an integer score to every
credited option (unlisted options score 0), so informative
distractors receive partial credit and the item is fitted as
polytomous; see \code{\link{distractor_rescore}} for an
evidence-based proposal. Raw responses are retained in \code{fit$mc}
for \code{\link{distractor_analysis}} and
\code{\link{plot_distractors}}.}

\item{pc_components}{\code{NULL} (default) estimates every PCM threshold
freely. An integer 1 to 4 instead estimates each item's thresholds
through the Andrich principal-components reparameterisation (see
\code{\link{pcml_pc}}): 1 = location only, 2 = + spread (the dispersion
model of Andrich 1982), 3 = + skewness, 4 = + kurtosis (the full
principal-components model; Pedler 1987). Useful when some categories are sparsely
populated; the component estimates are returned in
\code{fit$est$components}. PCM only, and not combinable with anchors.}

\item{maxit, tol}{Newton-Raphson iteration cap and convergence
tolerance of the pairwise conditional estimation.}
}
\value{
An object of class \code{"rasch"}: a list with the item summary
  (\code{items}), \code{thresholds} (with standard errors), the person
  table (\code{person}, including ID and factors), the score table,
  residuals, reliability (\code{psi}, \code{psi_noext}, the item
  separation index \code{isi}, \code{alpha}), targeting, item-trait
  statistics (\code{item_trait}, \code{item_anova}), the
  summary distribution block (\code{summary_stats}: location and fit
  residual mean/SD/skewness/kurtosis, fit-location correlations, and the
  cell degrees-of-freedom factor), threshold diagnostics, and estimation
  details (\code{est}).
}
\description{
Runs a complete Rasch analysis: Andrich and Luo pairwise conditional
maximum likelihood item estimation (see \code{\link{pcml}}), Warm weighted
likelihood person estimates per missing-data pattern, item and person fit
residuals (the log-of-mean-square statistic of Andrich and Marais 2019,
ch. 23, with its
untransformed natural form and degrees of freedom), infit and outfit,
the item-trait interaction chi-square and the class-interval ANOVA
item-fit F, the person separation index with and without extremes,
Cronbach's alpha, targeting, threshold diagnostics, and the
score-to-measure table.
}
\details{
The fit residual follows Andrich and Marais (2019, ch. 23) exactly:
standardised residuals are
squared and summed over each item's (person's) observed cells among
non-extreme persons, compared with the summed cell degrees of freedom
(the model-testing degrees of freedom, cells minus estimated parameters,
apportioned equally over cells), and symmetrised by the
log-of-mean-square transform \eqn{f (\ln Y^2 - \ln f)/\sqrt{V[Y^2]}} with
model-based variance \eqn{V[Y^2] = \sum (C_4/V^2 - 1)}. Values are
approximately N(0,1) under fit; the conventional flagging value is 2.5
(Andrich and Marais 2019, ch. 15).
Negative values indicate over-discrimination (Guttman-like responses),
positive values under-discrimination.

A calibration note that applies to the whole test-of-fit suite: the
item-trait chi-square evaluates unconditional residuals at estimated
person measures and refers the sum of correlated item statistics to a
chi-square with summed degrees of freedom, following the convention of
Andrich and Marais (2019); the class-interval ANOVA F and the
Wilson-Hilferty-style transformations are approximations of the same
kind. Null simulation with this package shows rejection rates near but
not exactly at the nominal level (conservative in the settings
examined), and the direction can vary with design. These statistics are
therefore approximate, convention-faithful diagnostics for ordering and
flagging misfit -- not exactly calibrated hypothesis tests; where exact
calibration matters, use the simulation tools
(\code{\link{sim_replicate}}) to build parametric-bootstrap reference
distributions for the observed design.
}
\examples{
set.seed(1)
d <- seq(-2, 2, length.out = 8)
X <- matrix(rbinom(500 * 8, 1, plogis(outer(rnorm(500), d, "-"))), 500, 8)
colnames(X) <- paste0("I", 1:8)
fit <- rasch(X, model = "PCM")
fit$items
fit$psi$PSI
}
