% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/brms_fitstats.R
\name{infit_statistic}
\alias{infit_statistic}
\title{Posterior Predictive Infit Statistic for Bayesian IRT Models}
\usage{
infit_statistic(
  model,
  item_var = item,
  person_var = id,
  ndraws_use = NULL,
  outfit = FALSE
)
}
\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
\code{family = bernoulli()} for a dichotomous Rasch model).}

\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.}

\item{outfit}{Logical. If \code{TRUE}, outfit statistics are computed
alongside infit. Default is \code{FALSE} (infit only), since outfit
is highly sensitive to outliers and rarely recommended for Rasch
diagnostics.}
}
\value{
A \code{\link[tibble]{tibble}} with the following columns:
\describe{
\item{item}{The item identifier.}
\item{draw}{Integer index of the posterior draw.}
\item{infit}{The observed infit statistic for that item and draw.}
\item{infit_rep}{The replicated infit statistic (based on posterior
predicted data) for that item and draw.}
\item{outfit}{(Only if \code{outfit = TRUE}) The observed outfit
statistic for that item and draw.}
\item{outfit_rep}{(Only if \code{outfit = TRUE}) The replicated
outfit statistic for that item and draw.}
}
The output is grouped by the item variable. Posterior predictive
p-values can be obtained by computing, e.g.,
\code{mean(infit_rep > infit)} within each item.
}
\description{
Computes a Bayesian analogue of the conditional item infit statistic
(as described in Christensen, Kreiner & Mesbah, 2013) for Rasch-family
models fitted with \pkg{brms}. For each posterior draw, expected values
and variances are derived from the category probabilities returned by
\code{\link[brms]{posterior_epred}}, and variance-weighted standardised
residuals are computed for both observed and replicated data. The result
can be summarised into posterior predictive p-values to assess item fit.
}
\details{
The procedure adapts the conditional infit/outfit statistics
(Christensen et al., 2013; Kreiner & Christensen, 2011; Müller, 2020)
to the Bayesian framework:

\enumerate{
\item For each posterior draw \eqn{s}, category probabilities
\eqn{P^{(s)}(X_{vi} = c)} are obtained from
\code{\link[brms]{posterior_epred}}.
\item The conditional expected value and variance for each
observation are computed as:
\deqn{E^{(s)}_{vi} = \sum_c c \cdot P^{(s)}(X_{vi} = c)}
\deqn{Var^{(s)}_{vi} = \sum_c (c - E^{(s)}_{vi})^2 \cdot
      P^{(s)}(X_{vi} = c)}
\item Standardised squared residuals are:
\deqn{Z^{2(s)}_{vi} = (X_{vi} - E^{(s)}_{vi})^2 / Var^{(s)}_{vi}}
\item The infit statistic for item \eqn{i} is the variance-weighted
mean of \eqn{Z^2} across persons:
\deqn{Infit_i^{(s)} = \frac{\sum_v Var_{vi}^{(s)} Z^{2(s)}_{vi}}
      {\sum_v Var_{vi}^{(s)}}}
\item If requested, the outfit is the unweighted mean of \eqn{Z^2}.
}
}
\examples{
\donttest{
library(brms)
library(dplyr)
library(tidyr)
library(tibble)

# --- Partial Credit Model (polytomous) ---

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 
)

# Compute infit per item
item_infit <- infit_statistic(
  model      = fit_pcm,
  ndraws_use = 100 # use at least 500
)

# Post-process draws
infit_results <- infit_post(item_infit)
infit_results$summary
infit_results$hdi
infit_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 
)

item_infit_rm <- infit_statistic(
  model      = fit_rm,
  ndraws_use = 100 # use at least 500
)

# Post-process draws
infit_results <- infit_post(item_infit_rm)
infit_results$summary
infit_results$hdi
infit_results$plot

}

}
\references{
Christensen, K. B., Kreiner, S. & Mesbah, M. (Eds.) (2013).
\emph{Rasch Models in Health}. Iste and Wiley, pp. 86--90.

Kreiner, S. & Christensen, K. B. (2011). Exact evaluation of Bias in
Rasch model residuals. \emph{Advances in Mathematics Research}, 12,
19--40.

Müller, M. (2020). Item fit statistics for Rasch analysis: can we
trust them? \emph{Journal of Statistical Distributions and
Applications}, \emph{7}(1).
\doi{10.1186/s40488-020-00108-7}
}
\seealso{
\code{\link{fit_statistic_pcm}} for a general-purpose posterior predictive
fit statistic with user-supplied criterion functions,
\code{\link{fit_statistic_rm}} for a general-purpose posterior predictive
fit statistic with user-supplied criterion functions,
\code{\link[brms]{posterior_epred}},
\code{\link[brms]{posterior_predict}}.
}
