% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/local_dependence.R
\name{RMlocdepQ3Cutoff}
\alias{RMlocdepQ3Cutoff}
\title{Simulation-Based \eqn{Q_3} Cutoff Determination}
\usage{
RMlocdepQ3Cutoff(
  data,
  iterations = 500,
  parallel = TRUE,
  n_cores = NULL,
  verbose = FALSE,
  seed = NULL,
  cutoff_method = "hdci",
  hdci_width = 0.99,
  estimator = c("CML", "MML"),
  dgp = c("resample", "conditional")
)
}
\arguments{
\item{data}{A data.frame or matrix of item responses. Items must be scored
starting at 0 (non-negative integers).}

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

\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. Method used to compute per-pair \eqn{Q_3}
credible intervals in \code{pair_cutoffs}. One of \code{"hdci"} (the default,
Highest Density Continuous Interval via \code{ggdist::hdci()}) or
\code{"quantile"} (symmetric 2.5th / 97.5th percentiles). Only affects
\code{pair_cutoffs}; the global \verb{$suggested_cutoff} (99th percentile of
\code{max(Q3) - mean(Q3)}) is unaffected.}

\item{hdci_width}{Numeric in (0, 1). Width of the HDCI when
\code{cutoff_method = "hdci"}. Default \code{0.99}. Ignored when
\code{cutoff_method = "quantile"}.}

\item{estimator}{Character. Estimation engine for the simulated \eqn{Q_3} values,
passed through to the per-iteration computation. \code{"CML"} (default) uses
CML item parameters and WLE person locations; \code{"MML"} uses \code{mirt}. This
must match the \code{estimator} later given to \code{\link{RMlocdepQ3}}; the
value is stored in the returned object's \verb{$estimator} and reused
automatically.}

\item{dgp}{Character. Data-generating process for the parametric bootstrap.
\code{"resample"} (default) draws person locations by resampling the WLE
estimates with replacement and simulates responses under the model -- a
\emph{marginal} null. \code{"conditional"} instead simulates each respondent's
pattern from the exact Rasch conditional distribution given their observed
total score (and answered items), with item parameters fixed -- a
\emph{conditional} null that fixes the score margin and needs no latent
distribution, avoiding the over-dispersion of resampled point estimates.
The two give different cut-offs; see the package's comparison study.
\strong{Experimental.}}
}
\value{
A list with components:
\describe{
\item{\code{results}}{data.frame with columns \code{mean}, \code{max}, \code{diff} (one row
per successful iteration).}
\item{\code{pair_results}}{Long data.frame with columns \code{Item1}, \code{Item2},
\code{Q3}, \code{iteration} --- one row per item pair per successful iteration.
Used by \code{\link{RMlocdepQ3Plot}}.}
\item{\code{pair_cutoffs}}{data.frame with per-pair cutoff summaries:
\code{Item1}, \code{Item2}, \code{Q3_low}, \code{Q3_high}. Boundaries are computed via
the method specified by \code{cutoff_method}.}
\item{\code{actual_iterations}}{Number of successful iterations.}
\item{\code{sample_n}}{Number of persons used: respondents with no responses
at all (all-\code{NA} rows) are dropped, as in \code{\link{RMlocdepQ3}};
incomplete response patterns are retained.}
\item{\code{sample_n_total}}{Number of respondents in the raw input data,
before dropping all-\code{NA} rows.}
\item{\code{sample_has_na}}{Logical. Whether the 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 \code{data}.}
\item{\code{max_diff}, \code{sd_diff}}{Max and SD of the \code{diff} distribution.}
\item{\code{p95}, \code{p99}, \code{p995}, \code{p999}}{Empirical percentiles of \code{diff}.}
\item{\code{suggested_cutoff}}{The 99th percentile (\code{p99}) --- recommended
scalar cutoff for \code{\link{RMlocdepQ3}}.}
\item{\code{cutoff_method}}{The method used for \code{pair_cutoffs}
(\code{"hdci"} or \code{"quantile"}).}
\item{\code{hdci_width}}{The HDCI width used (only meaningful when
\code{cutoff_method = "hdci"}).}
\item{\code{estimator}}{The estimator used for the simulated \eqn{Q_3} (\code{"CML"} or
\code{"MML"}); reused by \code{\link{RMlocdepQ3}} and
\code{\link{RMlocdepQ3Plot}}.}
\item{\code{dgp}}{The data-generating process used (\code{"resample"} or
\code{"conditional"}).}
}
}
\description{
Uses parametric bootstrap simulation to determine an appropriate cutoff
value for \code{\link{RMlocdepQ3}}. Under a correctly fitting Rasch model,
\eqn{Q_3} residuals have an unknown distribution; this function simulates
that distribution and returns empirical percentiles.
}
\details{
The generating model is fitted once: CML item parameters (via
\code{psychotools}) and WLE person locations. For each simulation iteration,
those WLE thetas are resampled with replacement, response data are simulated
under the Rasch / Partial Credit model, the model is refitted, and \eqn{Q_3}
residuals are computed under \code{estimator}. The distribution of
\code{max(Q3) - mean(Q3)} across iterations provides empirical critical values.
Failed iterations (e.g., due to convergence issues) are silently discarded.

Supports both \strong{dichotomous} data (simulated via \code{psychotools::rrm()}) and
\strong{polytomous} data (via an internal partial credit score simulator).

Parallel processing is provided by the \code{mirai} package (optional). Install
it with \code{install.packages("mirai")} to enable parallelisation.
}
\examples{
\donttest{
if (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)

  # Few iterations for a fast example; use 500+ in real analyses
  cutoff_res <- RMlocdepQ3Cutoff(sim_data, iterations = 50, parallel = FALSE,
                                 seed = 42)
  cutoff_res$suggested_cutoff  # 99th percentile

  # Use the cutoff in RMlocdepQ3()
  RMlocdepQ3(sim_data, cutoff = cutoff_res$suggested_cutoff)
}
}
}
\seealso{
\code{\link{RMlocdepQ3}}
}
