% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/infit_cutoff_mi.R
\name{RMitemInfitCutoffMI}
\alias{RMitemInfitCutoffMI}
\title{Simulation-Based Infit MSQ Cutoff Determination for Multiply Imputed Data}
\usage{
RMitemInfitCutoffMI(
  mids_object,
  iterations = 500,
  parallel = TRUE,
  n_cores = NULL,
  verbose = FALSE,
  seed = NULL,
  cutoff_method = "hdci",
  hdci_width = 0.999
)
}
\arguments{
\item{mids_object}{A \code{mids} object (multiply imputed dataset) as returned by
\code{mice::mice()}. Each completed dataset must contain only the item response
columns to be analysed (i.e., no ID or grouping variables). Items must be
scored starting at 0 (non-negative integers).}

\item{iterations}{Integer. Total number of simulation iterations to run
across all imputations. These are distributed approximately evenly across
the \code{m} imputed datasets (default 500).}

\item{parallel}{Logical. Use parallel processing via \code{mirai} within each
imputed dataset (default \code{TRUE}). Passed to \code{\link{RMitemInfitCutoff}}.}

\item{n_cores}{Integer or \code{NULL}. Number of parallel workers. Passed to
\code{\link{RMitemInfitCutoff}}.}

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

\item{seed}{Integer or \code{NULL}. Master random seed for reproducibility. A
unique per-imputation seed is derived from this value.}

\item{cutoff_method}{Character string specifying how cutoff intervals are
computed from the stacked distribution. 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"}.}
}
\value{
A list with the same structure as \code{\link{RMitemInfitCutoff}}, so
that the result can be passed directly to \code{\link{RMitemInfit}},
\code{\link{RMitemInfitMI}}, and \code{\link{RMitemInfitPlot}}:
\describe{
\item{\code{results}}{data.frame with columns \code{iteration}, \code{imputation},
\code{Item}, \code{InfitMSQ}, \code{OutfitMSQ} — the stacked simulation results from
all imputed datasets.}
\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}. Computed from
the stacked distribution.}
\item{\code{actual_iterations}}{Total number of successful iterations across
all imputations.}
\item{\code{sample_n}}{Number of rows (respondents) per imputed dataset.}
\item{\code{sample_summary}}{Summary statistics of estimated person parameters
from the first imputed dataset.}
\item{\code{item_names}}{Character vector of item names.}
\item{\code{cutoff_method}}{The method used to compute cutoffs.}
\item{\code{hdci_width}}{The HDCI width used.}
\item{\code{n_imputations}}{Number of imputed datasets used.}
\item{\code{iterations_per_imputation}}{Integer vector of requested iterations
per imputed dataset.}
\item{\code{actual_iterations_per_imputation}}{Integer vector of successful
iterations per imputed dataset.}
}
}
\description{
Extends \code{\link{RMitemInfitCutoff}} to work with multiply imputed datasets
produced by the \code{mice} package. Runs the parametric bootstrap simulation on
each imputed dataset and stacks the resulting distributions, so that the
final cutoff intervals reflect both sampling variability and imputation
uncertainty.
}
\details{
The function completes each of the \code{m} imputed datasets via
\code{mice::complete()}, then calls \code{\link{RMitemInfitCutoff}} on each one. The
total number of iterations is split approximately evenly across imputations
(i.e., each imputed dataset receives \code{ceiling(iterations / m)} or
\code{floor(iterations / m)} iterations). The per-imputation simulation results
are stacked into a single distribution from which cutoff intervals are
computed, naturally incorporating imputation uncertainty.

Imputed datasets that cause model convergence failures are dropped with a
warning. If all imputations fail, the function stops with an error.

The \code{mice} package must be installed (it is in Suggests, not Imports).
}
\examples{
\donttest{
if (requireNamespace("mice", quietly = TRUE) &&
    requireNamespace("iarm", quietly = TRUE) &&
    requireNamespace("ggdist", quietly = TRUE)) {
  # Create example data with ~10\% MCAR missingness
  set.seed(42)
  mat <- matrix(sample(0:1, 200 * 8, replace = TRUE), nrow = 200, ncol = 8)
  mat[sample(length(mat), round(0.10 * length(mat)))] <- NA
  sim_data <- as.data.frame(mat)
  colnames(sim_data) <- paste0("Item", 1:8)

  # mice's ordinal method (`polr`) requires the items to be ordered
  # factors, so code them as such before imputing. RMitemInfitCutoffMI()
  # converts the completed factors back to numeric internally.
  sim_data[] <- lapply(sim_data, function(x) factor(x, ordered = TRUE))

  # Impute (use more imputations, e.g. m = 5+, in real analyses)
  imp <- mice::mice(sim_data, m = 2, method = "polr", seed = 123,
                    printFlag = FALSE)

  # Compute simulation-based cutoffs across imputations
  # (use more iterations, e.g. 250+, in real analyses)
  cutoff_mi <- RMitemInfitCutoffMI(imp, iterations = 50, parallel = FALSE,
                                seed = 42)
  cutoff_mi$item_cutoffs

  # Use with RMitemInfitMI()
  RMitemInfitMI(imp, cutoff = cutoff_mi)
}
}
}
\seealso{
\code{\link{RMitemInfitCutoff}}, \code{\link{RMitemInfitMI}},
\code{\link{RMitemInfitPlot}}
}
