% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/infit_cutoff.R
\name{RMitemInfitCutoff}
\alias{RMitemInfitCutoff}
\title{Simulation-Based Infit MSQ Cutoff Determination}
\usage{
RMitemInfitCutoff(
  data,
  iterations = 250,
  parallel = TRUE,
  n_cores = NULL,
  verbose = FALSE,
  seed = NULL,
  cutoff_method = "hdci",
  hdci_width = 0.999,
  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). 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.999} (99.9\% HDCI). Ignored when \code{cutoff_method = "quantile"}.}

\item{dgp}{Character. Data-generating process for the parametric bootstrap.
\code{"resample"} (default) resamples WLE person locations with replacement and
simulates responses under the model (a \emph{marginal} null). \code{"conditional"}
simulates each respondent's pattern from the exact Rasch conditional
distribution given their observed total score, item parameters fixed (a
\emph{conditional} null). Because the conditional infit/outfit statistic is
itself conditional on the total score, \code{"conditional"} is its naturally
matched null. \strong{Experimental.}}
}
\value{
A list with components:
\describe{
\item{\code{results}}{data.frame with columns \code{iteration}, \code{Item},
\code{InfitMSQ}, \code{OutfitMSQ} (one row per item per successful iteration).}
\item{\code{item_cutoffs}}{data.frame with per-item cutoff summaries: \code{Item},
\code{infit_low}, \code{infit_high}, \code{outfit_low}, \code{outfit_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"}).}
\item{\code{dgp}}{The data-generating process used (\code{"resample"} or
\code{"conditional"}).}
}
}
\description{
Uses parametric bootstrap simulation to determine appropriate cutoff values
for \code{\link{RMitemInfit}}. This function simulates data from a correctly fitting
Rasch model that mimics your data and returns per-item empirical cutoffs.
}
\details{
The generating model is CML item parameters (via \code{psychotools}) with WLE
person locations. For each iteration a dataset is simulated under the chosen
\code{dgp}, the model is refitted by CML (\code{psychotools::pcmodel()}, which handles
dichotomous and polytomous data and is accepted by \code{iarm}), and conditional
infit and outfit MSQ are computed via \code{iarm::out_infit()}. The distribution
of these statistics across iterations provides empirical critical values per
item. Failed iterations (e.g., degenerate simulated data) are silently
discarded.

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 <- RMitemInfitCutoff(sim_data, iterations = 100,
                                  parallel = FALSE, seed = 42)
  cutoff_res$item_cutoffs

  # Use the cutoffs in RMitemInfit()
  RMitemInfit(sim_data)
}
}
}
\seealso{
\code{\link{RMitemInfit}}
}
