% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/ld_partgam.R
\name{RMlocdepGammaCutoff}
\alias{RMlocdepGammaCutoff}
\title{Simulation-Based Partial Gamma LD Cutoff Determination}
\usage{
RMlocdepGammaCutoff(
  data,
  iterations = 250,
  parallel = TRUE,
  n_cores = NULL,
  verbose = FALSE,
  seed = NULL,
  cutoff_method = "hdci",
  hdci_width = 0.99
)
}
\arguments{
\item{data}{A data.frame or matrix of item responses. Items must be scored
starting at 0 (non-negative integers). Only complete cases (rows without
any \code{NA}) are used.}

\item{iterations}{Integer. Number of simulation iterations (default 250).}

\item{parallel}{Logical. Use parallel processing via \code{mirai} if available
(default \code{TRUE}).}

\item{n_cores}{Integer or \code{NULL}. Number of parallel workers. When \code{NULL},
\code{getOption("mc.cores")} is checked first. If neither is set and
\code{parallel = TRUE}, a warning is issued and execution falls back to
sequential (single core) processing.}

\item{verbose}{Logical. Show a progress bar (default \code{FALSE}).}

\item{seed}{Integer or \code{NULL}. Random seed for reproducibility.}

\item{cutoff_method}{Character string specifying how cutoff intervals are
computed. Either \code{"hdci"} (default) for the Highest Density Interval via
\code{ggdist::hdci()}, or \code{"quantile"} for the 2.5th/97.5th percentiles via
\code{stats::quantile()}.}

\item{hdci_width}{Numeric. Width of the HDCI when \code{cutoff_method = "hdci"}.
Default is \code{0.99} (99\\% HDCI). Ignored when
\code{cutoff_method = "quantile"}.}
}
\value{
A list with components:
\describe{
\item{\code{results}}{data.frame with columns \code{iteration}, \code{Item1}, \code{Item2},
and \code{gamma} (one row per item pair per successful iteration). Contains
results from direction 1 only (rest score = total - Item2), which is
the conventional direction.}
\item{\code{pair_cutoffs}}{data.frame with per-pair cutoff summaries: \code{Item1},
\code{Item2}, \code{gamma_low}, \code{gamma_high}. Bounds are computed using the method
specified by \code{cutoff_method}.}
\item{\code{actual_iterations}}{Number of successful iterations.}
\item{\code{sample_n}}{Number of complete cases used.}
\item{\code{sample_n_total}}{Number of respondents in the raw input data,
before the complete-case filter.}
\item{\code{sample_has_na}}{Logical. Whether the raw input data contained
any missing values.}
\item{\code{sample_summary}}{Summary statistics of estimated person
parameters.}
\item{\code{item_names}}{Character vector of item names from data.}
\item{\code{cutoff_method}}{The method used to compute cutoffs (\code{"hdci"} or
\code{"quantile"}).}
\item{\code{hdci_width}}{The HDCI width used (only meaningful when
\code{cutoff_method = "hdci"}).}
}
}
\description{
Uses parametric bootstrap simulation to determine appropriate cutoff values
for partial gamma Local Dependence analysis via
\code{\link[iarm]{partgam_LD}}. Under a correctly fitting Rasch model where
items are locally independent, this function generates the expected
distribution of partial gamma values per item pair, providing empirical
critical values.
}
\details{
For each simulation iteration the function:
\enumerate{
\item Resamples person parameters (thetas) with replacement from the
WLE person locations.
\item Simulates item response data under a Rasch model (dichotomous via
\code{psychotools::rrm()} or polytomous via an internal partial credit
simulator).
\item Computes partial gamma LD statistics via
\code{iarm::partgam_LD()}.
}

Because the data are simulated under the Rasch model, items are locally
independent by construction. The distribution of partial gamma values
across iterations provides empirical critical values per item pair. Values
from real data that fall outside these bounds suggest local dependence that
exceeds what would be expected by chance. Failed iterations (e.g., due to
convergence issues or degenerate data) are silently discarded.

The generating model uses CML item thresholds via \code{psychotools::pcmodel()}
(a dichotomous item is a 2-category PCM) and WLE person locations,
consistent with the rest of the package; responses are simulated with
\code{psychotools::rrm()} (dichotomous) or an internal partial credit score
simulator (polytomous).

Parallel processing is provided by the \code{mirai} package (optional). Install
it with \code{install.packages("mirai")} to enable parallelisation.

The \code{iarm} package must be installed (it is in Suggests, not Imports).
}
\examples{
\donttest{
if (requireNamespace("iarm", 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 100 iterations sequentially for a quick demo
  cutoff_res <- RMlocdepGammaCutoff(sim_data, iterations = 100,
                                    parallel = FALSE, seed = 42)
  cutoff_res$pair_cutoffs
}
}
}
\references{
Christensen, K. B., Kreiner, S. & Mesbah, M. (Eds.) (2013).
\emph{Rasch Models in Health}, pp. 133--135. ISTE & Wiley.
\doi{10.1002/9781118574454}
}
\seealso{
\code{\link[iarm]{partgam_LD}}, \code{\link{RMlocdepGamma}},
\code{\link{RMlocdepGammaPlot}}
}
