% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/residual_pca.R
\name{RMdimResidualPCACutoff}
\alias{RMdimResidualPCACutoff}
\title{Simulation-based Cutoff for First-Contrast Eigenvalue}
\usage{
RMdimResidualPCACutoff(
  data,
  iterations = 250,
  parallel = TRUE,
  n_cores = NULL,
  verbose = FALSE,
  seed = NULL
)
}
\arguments{
\item{data}{A data.frame or matrix of item responses (0-based,
non-negative integers).}

\item{iterations}{Integer. Number of simulation iterations. Default \code{250}.}

\item{parallel}{Logical. Use parallel processing via \code{mirai}. 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,
\code{parallel = TRUE} falls back to sequential with a warning.}

\item{verbose}{Logical. Show a progress bar. Default \code{FALSE}.}

\item{seed}{Integer or \code{NULL}. Random seed for reproducibility.}
}
\value{
A list with components:
\describe{
\item{\code{results}}{data.frame: \code{iteration}, \code{eigenvalue}.}
\item{\code{p95}, \code{p99}, \code{p995}, \code{p999}}{Empirical percentiles of
\code{eigenvalue}.}
\item{\code{max}}{The largest simulated eigenvalue.}
\item{\code{suggested_cutoff}}{The 99th percentile (\code{p99}) — pass this list
back into \code{\link{RMdimResidualPCA}} via \verb{cutoff = }, or use
\code{suggested_cutoff} directly.}
\item{\code{suggested_cutoff_percentile}}{The percentile used for
\code{suggested_cutoff}, currently always \code{99}.}
\item{\code{actual_iterations}}{Number of successful iterations.}
\item{\code{sample_n}}{Number of complete cases used.}
\item{\code{item_names}}{Character vector of item names.}
}
}
\description{
Parametric bootstrap producing an empirical upper percentile for the
largest eigenvalue from a PCA of standardized residuals under a correctly
fitting Rasch model. For each iteration the function resamples theta
values from the data-based estimates, simulates response data, refits the
appropriate Rasch model, and extracts the first-contrast eigenvalue.
Several upper-tail percentiles of the resulting distribution are returned;
the 99th percentile is reported as the suggested cutoff (matching the
convention used by \code{\link{RMlocdepQ3Cutoff}}).
}
\details{
Rule-of-thumb cutoffs for the first-contrast eigenvalue depend strongly on
sample size, test length, and item-parameter spread; simulation-based
cutoffs tailored to the data are more defensible (Chou & Wang, 2010).

The generating model uses CML item parameters (\code{psychotools}) and WLE person
locations. Per iteration: theta values are sampled with replacement from the
WLE estimates; response data are simulated under the model
(\code{psychotools::rrm} for dichotomous, partial-credit simulator for
polytomous); CML/WLE standardized residuals are computed (the same engine as
the observed analysis); \code{prcomp()} is run; the first-contrast eigenvalue is
recorded.

Iterations that fail (e.g., due to a degenerate simulated dataset where
some category isn't represented) are silently dropped. The \code{iarm} package
is \strong{not} required.
}
\examples{
\donttest{
set.seed(1)
dat <- as.data.frame(
  matrix(sample(0:1, 200 * 12, replace = TRUE), nrow = 200, ncol = 12)
)
colnames(dat) <- paste0("I", 1:12)

# Few iterations for a fast example; use 250+ in real analyses
bound <- RMdimResidualPCACutoff(dat, iterations = 50, parallel = FALSE, seed = 1)
bound$suggested_cutoff

RMdimResidualPCA(dat, cutoff = bound)
}
}
\references{
Chou, Y.-T., & Wang, W.-C. (2010). Checking dimensionality in item
response models with principal component analysis on standardized
residuals. \emph{Educational and Psychological Measurement, 70}(5), 717-731.
\doi{10.1177/0013164410379322}
}
\seealso{
\code{\link{RMdimResidualPCA}}
}
