% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/infitcutoff_plot.R
\name{RMitemInfitPlot}
\alias{RMitemInfitPlot}
\alias{RMitemInfitCutoffPlot}
\title{Plot Distribution of Simulated Infit and Outfit MSQ Values}
\usage{
RMitemInfitPlot(simfit, data, statistic = "infit")

RMitemInfitCutoffPlot(...)
}
\arguments{
\item{simfit}{The return value of \code{\link{RMitemInfitCutoff}} (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 conditional item fit values. Items must be scored
starting at 0 (non-negative integers). When provided, the plot includes
orange diamond markers for the observed infit/outfit MSQ alongside the
simulated distribution, plus segment summaries from the cutoff intervals.}

\item{statistic}{Character string. Either \code{"infit"} (default) to show only the
infit panel, \code{"outfit"} to show only the outfit panel, or \code{"both"} to show
infit and outfit side by side (requires the \code{patchwork} package when
\code{data} is supplied).}

\item{...}{Arguments passed on to \code{RMitemInfitPlot()}.}
}
\value{
A \code{ggplot} object (or a \code{patchwork} object when \code{statistic = "both"}
and \code{data} is supplied).
}
\description{
Visualises the distribution of simulation-based conditional item fit values
from \code{\link{RMitemInfitCutoff}}, optionally overlaying observed item fit
from the original data.
}
\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.999)}.

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

When \code{data} \strong{is} supplied, the function:
\enumerate{
\item Fits a Rasch / Partial Credit model by CML via
\code{psychotools::pcmodel()} (a dichotomous item is a 2-category PCM)
and computes observed conditional infit and outfit MSQ via
\code{iarm::out_infit()}.
\item Overlays observed fit 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\% HDCI range and
black dots for the median.
}

The \code{ggplot2}, \code{ggdist}, and optionally \code{patchwork} packages must be
installed (they are in Suggests, not Imports).

\code{RMitemInfitCutoffPlot()} is a deprecated alias for \code{RMitemInfitPlot()},
retained for backward compatibility with code written against easyRasch2
0.8.0. It warns and forwards to \code{RMitemInfitPlot()}.
}
\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 <- RMitemInfitCutoff(sim_data, iterations = 100,
                                  parallel = FALSE, seed = 42)

  # Simulated distribution only (infit + outfit faceted)
  RMitemInfitPlot(cutoff_res)

  # With observed fit overlaid (infit only, the default)
  RMitemInfitPlot(cutoff_res, data = sim_data)

  # Both infit and outfit panels side by side
  if (requireNamespace("patchwork", quietly = TRUE)) {
    RMitemInfitPlot(cutoff_res, data = sim_data, statistic = "both")
  }
}
}
}
\seealso{
\code{\link{RMitemInfitCutoff}}, \code{\link{RMitemInfit}}
}
