% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/post_helpers.R
\name{q3_post}
\alias{q3_post}
\title{Summarize and Plot Posterior Predictive Q3 Residual Correlations}
\usage{
q3_post(
  q3_draws,
  ci = 0.84,
  n_pairs = NULL,
  sort_by = c("q3_diff", "q3_obs", "ppp")
)
}
\arguments{
\item{q3_draws}{A data frame (or tibble) as returned by
\code{\link{q3_statistic}} containing at minimum the columns
\code{item_pair}, \code{q3} (observed Q3 per draw), and
\code{q3_rep} (replicated Q3 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.}

\item{n_pairs}{Integer. Maximum number of item pairs to display
in the plot, selected by largest absolute \code{q3_diff}. If
\code{NULL} (the default), all pairs are shown. Useful when
the number of item pairs is large.}

\item{sort_by}{Character. How to order item pairs on the y-axis.
\code{"q3_diff"} (the default) sorts by the posterior mean
difference between observed and replicated Q3 (largest at top).
\code{"q3_obs"} sorts by the posterior mean observed Q3.
\code{"ppp"} sorts by the posterior predictive p-value.}
}
\value{
A list with three elements:
\describe{
\item{summary}{A \code{\link[tibble]{tibble}} with one row per
item pair containing: \code{item_pair}, \code{item_1},
\code{item_2}, \code{q3_obs} (posterior mean observed Q3),
\code{q3_rep} (posterior mean replicated Q3),
\code{q3_diff} (posterior mean difference), and \code{q3_ppp}
(posterior predictive p-value: proportion of draws where the
observed Q3 exceeds the replicated Q3).}
\item{hdi}{A \code{\link[tibble]{tibble}} with one row per
item pair containing: \code{item_pair}, \code{item_1},
\code{item_2}, \code{ld} (local dependence probability:
proportion of draws where observed Q3 exceeds upper HDI
bound of replicated distribution), and \code{lr} (local
repulsion probability: proportion of draws where observed
Q3 falls below lower HDI bound).}
\item{plot}{A \code{\link[ggplot2]{ggplot}} object showing
the posterior predictive distribution of replicated Q3
(grey filled slab) overlaid with the observed Q3
distribution (coloured slab + interval), with a dashed
reference line at 0.}
}
}
\description{
Postprocesses the output of \code{\link{q3_statistic}} to produce
summary tables of posterior predictive Q3 statistics and a combined
slab + interval plot comparing observed Q3 residual correlations
to the posterior predictive distribution for each item pair.
}
\details{
Two complementary summary tables are provided:

\describe{
\item{\code{summary}}{Reports posterior mean observed and
replicated Q3 values alongside the posterior predictive
p-value (ppp). The ppp is the proportion of draws where
the observed Q3 exceeds the replicated Q3. Under good fit
(no local dependence), the ppp should be near 0.5. A ppp
close to 1 indicates the observed correlation is
systematically higher than expected (local dependence);
a ppp close to 0 indicates it is systematically lower
(local repulsion, e.g., speed-accuracy tradeoffs).}
\item{\code{hdi}}{Reports the probability that the observed
Q3 falls above (local dependence) or below (local repulsion)
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) Q3 distribution as a filled density slab per
item pair, shaded by credible interval level.}
\item{\code{stat_slabinterval}}{Displays the observed Q3
distribution per item pair as a semi-transparent slab with
point and interval summaries.}
}
}
\examples{
\dontrun{
library(brms)
library(ggplot2)

# Assuming fit_pcm is a fitted brmsfit object
q3_draws <- q3_statistic(fit_pcm, ndraws_use = 500)

result <- q3_post(q3_draws)
result$summary
result$hdi
result$plot

# Show only top 10 pairs by Q3 difference
result_top <- q3_post(q3_draws, n_pairs = 10)
result_top$plot
}

}
\seealso{
\code{\link{q3_statistic}},
\code{\link{infit_post}},
\code{\link{item_restscore_post}}.
}
