% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ld_partgam.R
\name{RMlocdepGammaPlot}
\alias{RMlocdepGammaPlot}
\title{Plot Distribution of Simulated Partial Gamma LD Values}
\usage{
RMlocdepGammaPlot(simfit, data, items = NULL, n_pairs = NULL)
}
\arguments{
\item{simfit}{The return value of \code{\link{RMlocdepGammaCutoff}} (a list with
components \code{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 partial gamma values. Items must be scored starting
at 0 (non-negative integers). When provided, the plot includes orange
diamond markers for the observed partial gamma 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 absolute partial gamma values
are plotted, sorted by \verb{|gamma|} descending. When \code{data} is
supplied, the ranking uses the \emph{observed} partial gammas (the
diamonds you actually want to interpret); otherwise it falls back
to the per-pair median of the simulated distributions. Applied
\emph{after} the \code{items} filter when both are supplied. Values larger
than the number of available pairs are silently capped.}
}
\value{
A \code{ggplot} object.
}
\description{
Visualises the distribution of simulation-based partial gamma LD values
from \code{\link{RMlocdepGammaCutoff}}, optionally overlaying observed partial
gamma values computed from real data via \code{\link[iarm]{partgam_LD}}.
}
\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 plot shows one row per item pair (labelled as "Item1 - Item2"). Only
direction 1 (rest score = total - Item2) is plotted, matching the
convention used in the simulation.

When \code{data} is \strong{not} supplied, the function plots the simulated partial
gamma 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 partial gamma values via
\code{iarm::partgam_LD()}.
\item Overlays observed gamma 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}, and optionally \code{iarm} packages must be installed
(they are in Suggests, not Imports).
}
\examples{
\donttest{
if (requireNamespace("iarm", quietly = TRUE) &&
    requireNamespace("ggdist", quietly = TRUE) &&
    requireNamespace("ggplot2", 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
  cutoff_res <- RMlocdepGammaCutoff(sim_data, iterations = 100,
                                    parallel = FALSE, seed = 42)

  # Simulated distribution only
  RMlocdepGammaPlot(cutoff_res)

  # With observed partial gamma overlaid
  RMlocdepGammaPlot(cutoff_res, data = sim_data)

  # Plot only a subset of items
  RMlocdepGammaPlot(cutoff_res, data = sim_data,
                    items = c("Item1", "Item2", "Item3"))
}
}
}
\seealso{
\code{\link{RMlocdepGammaCutoff}}, \code{\link{RMlocdepGamma}}
}
