% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/brms_fitstats.R
\name{item_restscore_statistic}
\alias{item_restscore_statistic}
\title{Posterior Predictive Item-Restscore Association for Bayesian IRT Models}
\usage{
item_restscore_statistic(
  model,
  item_var = item,
  person_var = id,
  ndraws_use = NULL
)
}
\arguments{
\item{model}{A fitted \code{\link[brms]{brmsfit}} object from an
ordinal IRT model (e.g., \code{family = acat} for a partial credit
model) or a dichotomous model (\code{family = bernoulli()}).}

\item{item_var}{An unquoted variable name identifying the item
grouping variable in the model data (e.g., \code{item}).}

\item{person_var}{An unquoted variable name identifying the person
grouping variable in the model data (e.g., \code{id}).}

\item{ndraws_use}{Optional positive integer. If specified, a random
subset of posterior draws of this size is used. If \code{NULL} (the
default), all draws are used.}
}
\value{
A \code{\link[tibble]{tibble}} with the following columns:
\describe{
\item{item}{The item identifier.}
\item{gamma_obs}{Posterior mean of the observed Goodman-Kruskal
gamma between this item and the rest-score.}
\item{gamma_rep}{Posterior mean of the replicated gamma.}
\item{gamma_diff}{Posterior mean of \code{gamma_obs - gamma_rep}.
Positive values indicate the observed item-restscore association
is stronger than the model expects.}
\item{ppp}{Posterior predictive p-value:
\code{mean(gamma_obs > gamma_rep)} across draws.
Values close to 1 indicate the item discriminates more than the
model predicts (too high discrimination). Values close to 0
indicate the item discriminates less than expected (too low
discrimination, e.g., noise or miskeyed item).}
\item{gamma_obs_q025, gamma_obs_q975}{95\\% credible interval for
the observed gamma.}
\item{gamma_obs_q005, gamma_obs_q995}{99\\% credible interval for
the observed gamma.}
\item{gamma_diff_q025, gamma_diff_q975}{95\\% credible interval for
the gamma difference.}
\item{gamma_diff_q005, gamma_diff_q995}{99\\% credible interval for
the gamma difference.}
}
}
\description{
Computes a Bayesian analogue of the item-restscore association test
(Kreiner, 2011) for Rasch-family models fitted with \pkg{brms}. For
each posterior draw, the Goodman-Kruskal gamma coefficient between
each item's score and the rest-score (total score minus that item)
is computed for both observed and replicated data. Posterior
predictive p-values indicate whether the observed association is
stronger than the model predicts, which signals violations of
local independence or unidimensionality.
}
\details{
The item-restscore association is a key diagnostic in Rasch
measurement. Under the Rasch model, each item should relate to the
latent trait (and hence the rest-score) only through the modelled
relationship. Goodman-Kruskal's gamma is a rank-based measure of
association for ordinal cross-tabulations that is well-suited for
this purpose (Kreiner, 2011).

The procedure for each posterior draw \eqn{s} is:

\enumerate{
\item Obtain replicated responses \eqn{Y^{rep(s)}} from
\code{\link[brms]{posterior_predict}}.
\item For each item \eqn{i} and each person \eqn{v}, compute the
rest-score: \eqn{R^{obs}_{vi} = \sum_{j \neq i} X_{vj}} for
observed data and \eqn{R^{rep(s)}_{vi} = \sum_{j \neq i}
    Y^{rep(s)}_{vj}} for replicated data.
\item Cross-tabulate item score \eqn{\times} rest-score and compute
the Goodman-Kruskal gamma for both observed and replicated data.
\item Compare the two gammas across draws.
}

Items with \code{ppp} close to 1 have observed item-restscore
association that is consistently stronger than the model predicts.
This typically indicates that the item discriminates more than
assumed under the equal-discrimination Rasch model (i.e., a
violation of the Rasch assumption). Items with \code{ppp} close to
0 discriminate less than expected.
}
\examples{
\donttest{
library(brms)
library(dplyr)
library(tidyr)
library(tibble)

# --- Partial Credit Model ---

df_pcm <- eRm::pcmdat2 \%>\%
  mutate(across(everything(), ~ .x + 1)) \%>\%
  rownames_to_column("id") \%>\%
  pivot_longer(!id, names_to = "item", values_to = "response")

fit_pcm <- brm(
  response | thres(gr = item) ~ 1 + (1 | id),
  data   = df_pcm,
  family = acat,
  chains = 4,
  cores  = 1, # use more cores if you have
  iter   = 500 # use at least 2000 
)

# Item-restscore association
irs <- item_restscore_statistic(
  model      = fit_pcm,
  ndraws_use = 100 # use at least 500
)

# Post-process draws
irs_results <- item_restscore_post(irs)
irs_results$summary
irs_results$plot

# --- Dichotomous Rasch Model ---

df_rm <- eRm::raschdat3 \%>\%
  as.data.frame() \%>\%
  rownames_to_column("id") \%>\%
  pivot_longer(!id, names_to = "item", values_to = "response")

fit_rm <- brm(
  response ~ 1 + (1 | item) + (1 | id),
  data   = df_rm,
  family = bernoulli(),
  chains = 4,
  cores  = 1, # use more cores if you have
  iter   = 500 # use at least 2000 
)

irs_rm <- item_restscore_statistic(
  model      = fit_rm,
  ndraws_use = 100 # use at least 500
)

# Post-process draws
irs_results <- item_restscore_post(irs_rm)
irs_results$summary
irs_results$plot
}

}
\references{
Kreiner, S. (2011). A note on item-restscore association in Rasch
models. \emph{Applied Psychological Measurement}, \emph{35}(7),
557--561.

Goodman, L. A. & Kruskal, W. H. (1954). Measures of association for
cross classifications. \emph{Journal of the American Statistical
Association}, \emph{49}(268), 732--764.

Bürkner, P.-C. (2021). Bayesian Item Response Modeling in R with
brms and Stan. \emph{Journal of Statistical Software}, \emph{100},
1--54. \doi{10.18637/jss.v100.i05}
}
\seealso{
\code{\link{fit_statistic_pcm}} for posterior predictive fit statistics,
\code{\link{fit_statistic_rm}} for posterior predictive fit statistics,
\code{\link{infit_statistic}} for Bayesian infit/outfit,
\code{\link{q3_statistic}} for Bayesian Q3 residual correlations,
\code{\link[brms]{posterior_predict}}.
}
