% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/brms_localdep.R
\name{q3_statistic}
\alias{q3_statistic}
\title{Posterior Predictive Q3 Residual Correlations for Bayesian IRT Models}
\usage{
q3_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. Default is \code{item}.}

\item{person_var}{An unquoted variable name identifying the person
grouping variable in the model data. Default is \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}} in long format with one row
per draw per item pair, containing:
\describe{
\item{draw}{Integer draw index.}
\item{item_pair}{Character label of the item pair
(\code{"item1 : item2"}).}
\item{item_1}{First item in the pair.}
\item{item_2}{Second item in the pair.}
\item{q3}{Observed Q3 residual correlation for this draw.}
\item{q3_rep}{Replicated Q3 residual correlation for this draw.}
}

This long-format output parallels the structure of
\code{\link{infit_statistic}} and can be passed directly to
\code{\link{q3_post}} for summary tables and plots.
}
\description{
Computes a Bayesian analogue of Yen's Q3 statistic (Yen, 1984) for
detecting local dependence between item pairs in Rasch-family models
fitted with \pkg{brms}. For each posterior draw, residual correlations
are computed for both observed and replicated data, yielding draw-level
Q3 values that can be summarized and visualized via
\code{\link{q3_post}}.
}
\details{
The procedure works as follows for each posterior draw \eqn{s}:

\enumerate{
\item Compute expected values \eqn{E^{(s)}_{vi}} from the category
probabilities returned by \code{\link[brms]{posterior_epred}}.
For ordinal models: \eqn{E^{(s)}_{vi} = \sum_c c \cdot
    P^{(s)}(X_{vi} = c)}. For binary models: \eqn{E^{(s)}_{vi} =
    P^{(s)}(X_{vi} = 1)}.
\item Compute observed residuals: \eqn{d^{(s)}_{vi} = X_{vi} -
    E^{(s)}_{vi}}.
\item Compute replicated residuals: \eqn{d^{rep(s)}_{vi} =
    Y^{rep(s)}_{vi} - E^{(s)}_{vi}}, where \eqn{Y^{rep}} is drawn
via \code{\link[brms]{posterior_predict}}.
\item For each item pair \eqn{(i, j)}, compute Q3 as the Pearson
correlation of residuals across all persons who responded to
both items.
}
}
\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 
)

# Q3 residual correlations
q3_draws <- q3_statistic(fit_pcm, ndraws_use = 500)

# Postprocess
result <- q3_post(q3_draws)
result$summary
result$hdi
result$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 
)

q3_draws <- q3_statistic(fit_rm, ndraws_use = 500)

# Postprocess
result <- q3_post(q3_draws)
result$summary
result$hdi
result$plot
}

}
\references{
Yen, W. M. (1984). Effects of local item dependence on the fit and
equating performance of the three-parameter logistic model.
\emph{Applied Psychological Measurement}, \emph{8}(2), 125--145.
\doi{10.1177/014662168400800201}

Christensen, K. B., Makransky, G. & Horton, M. (2017). Critical
values for Yen's Q3: Identification of local dependence in the
Rasch model using residual correlations.
\emph{Applied Psychological Measurement}, \emph{41}(3), 178--194.
\doi{10.1177/0146621616677520}

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{q3_post}} for postprocessing summaries and plots,
\code{\link{infit_statistic}} for Bayesian infit/outfit,
\code{\link[brms]{posterior_epred}},
\code{\link[brms]{posterior_predict}}.
}
