% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/item_restscore.R
\name{RMitemRestscore}
\alias{RMitemRestscore}
\title{Item Restscore Analysis}
\usage{
RMitemRestscore(data, output = "kable", sort, p_adj = "BH")
}
\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,
but at least one complete case (row with no \code{NA}) must be present.}

\item{output}{Character string controlling the return value. Either
\code{"kable"} (default) for a formatted \code{knitr::kable()} table, or
\code{"dataframe"} for the underlying data.frame.}

\item{sort}{Optional character string. When \code{sort = "diff"}, rows are sorted
by the absolute magnitude of \code{Difference} in descending order, so that
both over- and underfitting items appear near the top.}

\item{p_adj}{Character string specifying the p-value adjustment method
passed to \code{iarm::item_restscore()}. Default \code{"BH"} (Benjamini-Hochberg);
use \code{"none"} for unadjusted p-values. Run \code{?stats::p.adjust} for the list
of available methods.}
}
\value{
\itemize{
\item If \code{output = "kable"}: a \code{knitr_kable} object (plain text table via
\code{format = "pipe"}) with columns for item name, observed and expected
restscore correlations, the signed difference (observed minus
expected), adjusted p-value, the \code{Flagged} misfit label, and item
location relative to the sample mean person location.
\item If \code{output = "dataframe"}: a data.frame with columns \code{Item}, \code{Observed},
\code{Expected}, \code{Difference}, \code{p_adjusted}, \code{Flagged}, and
\code{Relative_location}. \code{Flagged} is \code{"overfit"} (observed above expected,
adj. p < .05), \code{"underfit"} (below, adj. p < .05), or \code{""} (not flagged).
}

The \code{Difference} column is signed (observed minus expected):
\emph{positive} values indicate that the item correlates more strongly with
the rest-score than the Rasch model predicts (over-discrimination /
\emph{overfit}, often associated with local dependence), and \emph{negative}
values indicate weaker-than-expected association (under-discrimination
/ \emph{underfit}, often associated with multidimensionality or noise).
}
\description{
Computes observed and model-expected item-restscore correlations using
\code{iarm::item_restscore()}, and enriches the output with the absolute
difference between observed and expected values, item average locations, and
item locations relative to the sample mean person location.
}
\details{
Item-restscore correlations using Goodman-Kruskal's gamma (Kreiner, 2011) measure
the association between a person's score on a single item and their total
score on the remaining items (the "restscore"). Under a correctly fitting
Rasch model, observed and model-expected correlations should agree closely.

Item parameters are estimated by conditional maximum likelihood via
\code{psychotools::pcmodel()} (a dichotomous item is a 2-category PCM); the
item-restscore statistic itself comes from \code{iarm::item_restscore()} and is
conditional on the total score, so it is invariant to the estimation engine.
Per-item average locations are the means of the CML thresholds, and the
person-location reference is the mean of the Warm WLE estimates.

Relative item location is defined as the item's average location minus the
sample mean person location, providing a measure of item targeting.

The \code{iarm} package must be installed (it is in Suggests, not Imports).
}
\examples{
\donttest{
if (requireNamespace("iarm", quietly = TRUE)) {
  # Simulate binary item response data (8 items, 200 persons)
  set.seed(42)
  sim_data <- as.data.frame(
    matrix(sample(0:1, 200 * 8, replace = TRUE), nrow = 200, ncol = 8)
  )
  colnames(sim_data) <- paste0("Item", 1:8)

  # Default kable output
  RMitemRestscore(sim_data)

  # Sorted by absolute difference
  RMitemRestscore(sim_data, sort = "diff")

  # Return as data.frame for further processing
  df <- RMitemRestscore(sim_data, output = "dataframe")
}
}
}
\references{
Kreiner, S. (2011). A Note on Item–Restscore Association in Rasch Models.
\emph{Applied Psychological Measurement, 35}(7), 557–561.
\doi{10.1177/0146621611410227}
}
