% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/post_helpers.R
\name{infit_post}
\alias{infit_post}
\title{Summarize and Plot Posterior Predictive Infit Statistics}
\usage{
infit_post(infit_draws, ci = 0.84)
}
\arguments{
\item{infit_draws}{A data frame (or tibble) as returned by
\code{\link{infit_statistic}} containing at minimum the columns
\code{item}, \code{infit} (observed infit per draw), and
\code{infit_rep} (replicated infit per draw).}

\item{ci}{Numeric in \eqn{(0, 1)}. Width of the credible
interval used for the posterior predictive HDI and the slab
display. Default is 0.84.}
}
\value{
A list with three elements:
\describe{
\item{summary}{A \code{\link[tibble]{tibble}} with one row per
item containing: \code{item}, \code{infit_obs} (posterior
mean of observed infit), \code{infit_rep} (posterior mean of
replicated infit), and \code{infit_ppp} (posterior predictive
p-value: proportion of draws where the replicated infit
exceeds the observed infit). Values near 0.5 indicate good
fit; values near 0 suggest underfit; values near 1 suggest
overfit.}
\item{hdi}{A \code{\link[tibble]{tibble}} with one row per
item containing: \code{item}, \code{underfit} (posterior
probability that the observed infit exceeds the upper HDI
bound of the replicated distribution), and \code{overfit}
(posterior probability that the observed infit falls below
the lower HDI bound).}
\item{plot}{A \code{\link[ggplot2]{ggplot}} object showing
the posterior predictive distribution of replicated infit
(grey filled slab) overlaid with the observed infit
distribution (coloured slab + interval), with a dashed
reference line at 1 (perfect fit).}
}
}
\description{
Postprocesses the output of \code{\link{infit_statistic}} to produce summary tables
of posterior predictive infit statistics and a combined slab +
interval plot comparing observed infit values to the posterior
predictive distribution.
}
\details{
Two complementary summary tables are provided:

\describe{
\item{\code{summary}}{Reports the posterior mean observed and
replicated infit values alongside the posterior predictive
p-value (ppp). The ppp is the proportion of draws where the
replicated infit exceeds the observed infit. Under good fit,
the ppp should be near 0.5. A ppp near 0 indicates the
observed infit is consistently larger than expected
(underfit); a ppp near 1 indicates it is consistently
smaller (overfit).}
\item{\code{hdi}}{Reports the probability that the observed
infit falls above (underfit) or below (overfit) the HDI of
the replicated distribution. This provides a more
distributional assessment than the ppp alone.}
}

The plot uses two layers from the \pkg{ggdist} package:
\describe{
\item{\code{stat_slab}}{Displays the posterior predictive
(replicated) infit distribution as a filled density slab
per item, shaded by credible interval level.}
\item{\code{stat_slabinterval}}{Displays the observed infit
distribution per item as a semi-transparent slab with
point and interval summaries.}
}

Under good model fit, the observed infit distribution should
overlap substantially with the replicated distribution. Items
where the observed distribution sits systematically above the
replicated HDI indicate underfit (more variation than expected);
items below indicate overfit (less variation than expected).
}
\examples{
\dontrun{
library(brms)
library(ggplot2)

# Assuming fit_pcm is a fitted brmsfit object
infit_draws <- infit_statistic(fit_pcm)

result <- infit_post(infit_draws)
result$summary
result$hdi
result$plot
}

}
\seealso{
\code{\link{infit_statistic}},
\code{\link{item_restscore_post}}.
}
