% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/dif_partgam.R
\name{RMdifGammaCutoff}
\alias{RMdifGammaCutoff}
\title{Simulation-Based Partial Gamma DIF Cutoff Determination}
\usage{
RMdifGammaCutoff(
  data,
  dif_var,
  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{dif_var}{A vector (factor, character, or integer) defining group
membership for DIF analysis. Must have the same length as \code{nrow(data)}.
The actual group labels are used to determine the number of groups and
their relative sizes; during simulation, respondents are randomly assigned
to groups with the same proportions, so there is no true DIF by
construction.}

\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{Item}, and
\code{gamma} (one row per item per successful iteration).}
\item{\code{item_cutoffs}}{data.frame with per-item cutoff summaries: \code{Item},
\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 removing rows with \code{NA} in \code{data} or \code{dif_var}.}
\item{\code{sample_has_na}}{Logical. Whether \code{data} or \code{dif_var} 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{dif_group_sizes}}{Named integer vector of group sizes used in the
simulation (matches proportions in the observed \code{dif_var}).}
\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 DIF analysis via \code{\link[iarm]{partgam_DIF}}. Under
a correctly fitting Rasch model where the DIF variable is unrelated to item
responses (i.e., no true DIF), this function generates the expected
distribution of absolute partial gamma values per item, 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 Creates a random DIF variable by sampling group labels with the
same proportions as the observed \code{dif_var}, so there is \strong{no true DIF}
by construction.
\item Computes partial gamma DIF statistics via
\code{iarm::partgam_DIF()}.
}

The distribution of partial gamma values across iterations provides
empirical critical values per item. Values from real data that fall
outside these bounds suggest DIF that exceeds what would be expected by
chance under a correctly fitting Rasch model. 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)
  dif_sex <- sample(c("male", "female"), 200, replace = TRUE)

  # Run 100 iterations sequentially for a quick demo
  cutoff_res <- RMdifGammaCutoff(sim_data, dif_var = dif_sex,
                                 iterations = 100, parallel = FALSE,
                                 seed = 42)
  cutoff_res$item_cutoffs
}
}
}
\references{
Bjorner, J. B., Kreiner, S., Ware, J. E., Damsgaard, M. T., &
Bech, P. (1998). Differential item functioning in the Danish translation
of the SF-36. \emph{Journal of Clinical Epidemiology, 51}(11), 1189--1202.
\doi{10.1016/S0895-4356(98)00111-5}

Henninger, M., Radek, J., Debelak, R., & Strobl, C. (2025).
Partial credit trees meet the partial gamma coefficient for quantifying
DIF and DSF in polytomous items. \emph{Behaviormetrika, 52}, 221--257.
\doi{10.1007/s41237-024-00252-3}
}
\seealso{
\code{\link[iarm]{partgam_DIF}}
}
