% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/dif_partgam.R
\name{RMdifGammaPlot}
\alias{RMdifGammaPlot}
\title{Plot Distribution of Simulated Partial Gamma DIF Values}
\usage{
RMdifGammaPlot(simfit, data, dif_var)
}
\arguments{
\item{simfit}{The return value of \code{\link{RMdifGammaCutoff}} (a list with
components \code{results}, \code{item_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{dif_var}{Required when \code{data} is supplied. A vector (factor, character,
or integer) defining group membership for the DIF analysis. Must have the
same length as \code{nrow(data)}.}
}
\value{
A \code{ggplot} object.
}
\description{
Visualises the distribution of simulation-based partial gamma DIF values
from \code{\link{RMdifGammaCutoff}}, optionally overlaying observed partial
gamma values computed from real data via \code{\link[iarm]{partgam_DIF}}.
}
\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)}.

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 (along with \code{dif_var}), the function:
\enumerate{
\item Computes observed partial gamma values via
\code{iarm::partgam_DIF()}.
\item Overlays observed gamma values as orange diamond markers on the
simulated distributions.
\item Shows per-item cutoff intervals (from \code{simfit$item_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)
  dif_group <- factor(sample(c("A", "B"), 200, replace = TRUE))

  # Run simulation
  cutoff_res <- RMdifGammaCutoff(sim_data, dif_var = dif_group,
                                 iterations = 100, parallel = FALSE,
                                 seed = 42)

  # Simulated distribution only
  RMdifGammaPlot(cutoff_res)

  # With observed partial gamma overlaid
  RMdifGammaPlot(cutoff_res, data = sim_data, dif_var = dif_group)
}
}
}
\seealso{
\code{\link{RMdifGammaCutoff}}, \code{\link{RMdifGamma}}
}
