% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/locdep_q3_plot.R
\name{RMlocdepQ3Plot}
\alias{RMlocdepQ3Plot}
\title{Plot Distribution of Simulated \eqn{Q_3} Residual Correlations}
\usage{
RMlocdepQ3Plot(simfit, data, items = NULL, n_pairs = NULL)
}
\arguments{
\item{simfit}{The return value of \code{\link{RMlocdepQ3Cutoff}} (a list
with components \code{pair_results}, \code{pair_cutoffs}, \code{actual_iterations},
\code{sample_n}, and \code{item_names}).}

\item{data}{Optional. A data.frame or matrix of item responses for
computing and overlaying observed \eqn{Q_3} values. Items must be scored
starting at 0 (non-negative integers). When provided, the plot
includes orange diamond markers for the observed \eqn{Q_3} alongside the
simulated distribution, plus segment summaries from the cutoff
intervals.}

\item{items}{Optional character vector of item names to include in the
plot. Only item pairs where \strong{both} items are in this vector will be
shown. When \code{NULL} (default), all item pairs are plotted.}

\item{n_pairs}{Optional positive integer. When supplied, only the
\code{n_pairs} item pairs with the largest \strong{deviation} from the simulated
null are plotted, sorted by \verb{|observed Q3 - median(simulated Q3 per pair)|} descending when \code{data} is supplied, or by
\verb{|median(simulated Q3 per pair)|} otherwise. Applied \emph{after} the
\code{items} filter when both are supplied. Values larger than the number
of available pairs are silently capped.}
}
\value{
A named list of two \code{ggplot} objects (mirroring the \verb{$matrix} /
\verb{$pairs} structure of \code{\link{RMlocdepQ3}}'s table output):
\describe{
\item{\verb{$pairs}}{the per-pair plot described below (always returned).}
\item{\verb{$matrix}}{a lower-triangle tile heatmap of the \strong{observed} \eqn{Q_3}
matrix, with pairs above the global dynamic cut-off outlined. This
needs the observed data, so it is \code{NULL} (with a message) when \code{data}
is not supplied. When \code{items} is given, the heatmap is subset to those
items; \code{n_pairs} does not apply to it.}
}
}
\description{
Visualises the distribution of simulation-based Yen's \eqn{Q_3} residual
correlations per item pair from \code{\link{RMlocdepQ3Cutoff}},
optionally overlaying observed \eqn{Q_3} values computed from real data via
\code{mirt::residuals(..., type = "Q3")}.
}
\details{
Uses \code{ggdist::stat_dotsinterval()} (when \code{data} is not supplied) or
\code{ggdist::stat_dots()} (when \code{data} is supplied) with
\code{point_interval = "median_hdci"} and \code{.width = c(0.66, 0.95, 0.99)}.

The \verb{$pairs} plot shows one row per item pair (labelled as "Item1 - Item2").
Only
the upper triangle of the \eqn{Q_3} matrix is plotted (pairs are unordered
under symmetric \eqn{Q_3}, unlike partial gamma which is direction-dependent).

When \code{data} is \strong{not} supplied, the function plots the simulated Q3
distributions as dot-interval plots using \code{ggdist::stat_dotsinterval()}
with median and Highest Density Continuous Interval (HDCI) summaries.

When \code{data} \strong{is} supplied, the function:
\enumerate{
\item Computes observed \eqn{Q_3} residual correlations under the same
estimator used to build \code{simfit} (its \verb{$estimator}: CML/WLE by
default, or MML via \code{mirt}).
\item Overlays observed \eqn{Q_3} values as orange diamond markers on the
simulated distributions.
\item Shows per-pair cutoff intervals (from \code{simfit$pair_cutoffs})
as black line segments, with thicker segments for the 66\\%
interval and black dots for the median.
}

The \code{ggplot2}, \code{ggdist}, \code{mirt}, and \code{scales} packages must be
installed (most are in Suggests, not Imports).
}
\examples{
\donttest{
if (requireNamespace("ggplot2", quietly = TRUE) &&
    requireNamespace("ggdist", quietly = TRUE)) {
  set.seed(42)
  sim_data <- as.data.frame(
    matrix(sample(0:1, 200 * 10, replace = TRUE), nrow = 200, ncol = 10)
  )
  colnames(sim_data) <- paste0("Item", 1:10)

  # Run simulation (use more iterations, e.g. 500+, in real analyses)
  cutoff_res <- RMlocdepQ3Cutoff(sim_data, iterations = 50,
                                 parallel = FALSE, seed = 42)

  # Simulated distribution only
  RMlocdepQ3Plot(cutoff_res)

  # With observed Q3 overlaid
  RMlocdepQ3Plot(cutoff_res, data = sim_data)

  # Top 10 pairs by departure from null
  RMlocdepQ3Plot(cutoff_res, data = sim_data, n_pairs = 10)
}
}
}
\seealso{
\code{\link{RMlocdepQ3}}, \code{\link{RMlocdepQ3Cutoff}},
\code{\link{RMlocdepGammaPlot}}
}
