% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/brms_fitstats.R
\name{fit_statistic_pcm}
\alias{fit_statistic_pcm}
\title{Posterior Predictive Item Fit Statistic for Bayesian IRT Models}
\usage{
fit_statistic_pcm(model, criterion, group, ndraws_use = NULL)
}
\arguments{
\item{model}{A fitted \code{\link[brms]{brmsfit}} object.}

\item{criterion}{A function with signature \code{function(y, p)} that
computes a pointwise fit criterion. For ordinal and categorical models,
\code{y} is the observed (or replicated) response category and \code{p}
is the model-predicted probability of that category. For binary models,
\code{y} is the binary response and \code{p} is the predicted probability
of success.}

\item{group}{An unquoted variable name (e.g., \code{item} or \code{id})
indicating the grouping variable over which the fit statistic is
aggregated. Typically \code{item} for item fit or \code{id} for person
fit.}

\item{ndraws_use}{Optional positive integer. If specified, a random subset
of posterior draws of this size is used, which can speed up computation
for large models. If \code{NULL} (the default), all draws are used.}
}
\value{
A \code{\link[tibble]{tibble}} with the following columns:
\describe{
\item{\code{group}}{The grouping variable (e.g., item name or person id).}
\item{draw}{Integer index of the posterior draw.}
\item{crit}{The observed fit statistic (criterion applied to observed
data) summed within each group and draw.}
\item{crit_rep}{The replicated fit statistic (criterion applied to
posterior predicted data) summed within each group and draw.}
\item{crit_diff}{The difference \code{crit_rep - crit}.}
}
The output is grouped by the grouping variable. Posterior predictive
p-values can be obtained by computing
\code{mean(crit_rep > crit)} within each group.
}
\description{
Computes posterior predictive item (or person) fit statistics for
Bayesian IRT models fitted with \pkg{brms}. For each posterior draw,
observed and replicated data are compared via a user-supplied criterion
function, grouped by item, person, or any other variable. Posterior
predictive p-values can then be derived from the output to assess fit.
}
\details{
The function implements the posterior predictive checking approach for
item fit described in Bürkner (2020). The procedure works as follows:

\enumerate{
\item Draw posterior expected category probabilities via
\code{\link[brms]{posterior_epred}} and posterior predicted responses
via \code{\link[brms]{posterior_predict}}.
\item For ordinal or categorical models (3D array output from
\code{posterior_epred}), extract the probability assigned to the
observed response category and to the replicated response category
for each draw and observation.
\item Apply the user-supplied \code{criterion} function to compute
pointwise fit values for both observed and replicated data.
\item Aggregate (sum) the criterion values within each level of
\code{group} and each posterior draw.
}

A common choice for ordinal IRT models is the categorical
log-likelihood criterion \code{function(y, p) log(p)}. For binary
(e.g., dichotomous Rasch) models, the Bernoulli log-likelihood
\code{function(y, p) y * log(p) + (1 - y) * log(1 - p)} may be used
instead.
}
\examples{
\donttest{
library(brms)
library(dplyr)
library(tidyr)
library(tibble)

# --- Polytomous Rasch (Partial Credit Model) ---

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

# Fit a Partial Credit Model using the adjacent category family
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 
)

# Categorical log-likelihood criterion (for polytomous models)
ll_categorical <- function(y, p) log(p)

# Compute item fit statistics
item_fit <- fit_statistic_pcm(
  model      = fit_pcm,
  criterion  = ll_categorical,
  group      = item,
  ndraws_use = 100 # use at least 500
)

# Summarise: posterior predictive p-values per item
item_fit \%>\%
  group_by(item) \%>\%
  summarise(
    observed   = mean(crit),
    replicated = mean(crit_rep),
    ppp        = mean(crit_rep > crit)
  )

# Use ggplot2 to make a histogram
library(ggplot2)
item_fit \%>\%
  ggplot(aes(crit_diff)) +
  geom_histogram(aes(fill = ifelse(crit_diff > 0, "above","below"))) +
  facet_wrap("item") +
  theme_bw() +
  theme(legend.position = "none")

# Compute person fit statistics
person_fit <- fit_statistic_pcm(
  model      = fit_pcm,
  criterion  = ll_categorical,
  group      = id,
  ndraws_use = 100 # use at least 500
)
}

}
\references{
Bürkner, P.-C. (2020). Analysing Standard Progressive Matrices (SPM-LS)
with Bayesian Item Response Models. \emph{Journal of Intelligence},
\emph{8}(1). \doi{10.3390/jintelligence8010005}

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_rm}} for dichotomous Rasch models,
\code{\link[brms]{posterior_epred}} for expected predictions,
\code{\link[brms]{posterior_predict}} for posterior predictive samples,
\code{\link[brms]{pp_check}} for graphical posterior predictive checks.
}
