R/simIPD.R

In irtQ: Unidimensional Item Response Theory Modeling

#' Simulated CAT Data for Item Parameter Drift (IPD) Detection
#'
#' @description
#' A simulated dataset designed to illustrate the use of the \code{\link{ripd}}
#' function for detecting item parameter drift (IPD) in computerized adaptive
#' testing (CAT). The dataset represents one replication of a CAT-based IPD
#' simulation study in which 5% of a 360-item pool (18 items) had both their
#' discrimination (\emph{a}) and difficulty (\emph{b}) parameters drift
#' downward by 0.5, under a 30-item adaptive test where all focal group
#' examinees were exposed to the drifted items (100% exposure rate).
#'
#' The data reflect a workflow of IPD detection using the residual-based IPD
#' (RIPD) framework (Lim & Han, in press): a focal group of examinees takes a
#' CAT using a drifted item pool, and a synthetic reference group is created by
#' re-running the CAT with the focal group's ability estimates as true abilities
#' but with the original (non-drifted) item parameters. RIPD statistics are then
#' used to detect which items have drifted between the two groups.
#'
#' @format A named list with eight elements:
#' \describe{
#'   \item{item_par}{A data frame with 360 rows and 6 columns containing the
#'     \strong{original} (pre-drift) item parameters in \code{irtQ} format
#'     (columns: \code{id}, \code{cats}, \code{model}, \code{par.1},
#'     \code{par.2}, \code{par.3}).  All items follow the 3PLM.}
#'   \item{key_item}{An integer vector of length 90 giving the row indices
#'     (in \code{item_par}) of the \emph{key items} - items selected by a
#'     preliminary CAT simulation as highly exposed and therefore most relevant
#'     for IPD analysis.}
#'   \item{item.skip}{An integer vector of length 270 giving the row indices of
#'     non-key items that should be excluded from RIPD analysis
#'     (i.e., the complement of \code{key_item} in \code{1:360}).
#'     Pass this vector to the \code{item.skip} argument of \code{ripd()}.}
#'   \item{ipd_item}{An integer vector of length 18 giving the row indices of
#'     items that were subjected to IPD manipulation.  These 18 items (5% of
#'     the 360-item pool) had both their discrimination (\emph{a}) and difficulty
#'     (\emph{b}) parameters decreased by 0.5.  All 18 items are members of
#'     \code{key_item}.}
#'   \item{foc_resp}{An integer matrix of dimensions 3000 x 360 containing the
#'     \strong{focal group} CAT response data.  Each row is one examinee; each
#'     column corresponds to an item in \code{item_par}.  Because CAT
#'     administers only 30 items per examinee, approximately 92% of entries
#'     are \code{NA}.  Responses were generated using the \emph{drifted} item
#'     parameters (all focal examinees were exposed to IPD items;
#'     exposure rate = 100%).}
#'   \item{foc_score}{A numeric vector of length 3000 containing the
#'     \strong{focal group} final maximum likelihood (ML) theta estimates
#'     obtained from the CAT.}
#'   \item{ref_resp}{An integer matrix of dimensions 3000 x 360 containing the
#'     \strong{synthetic reference group} CAT response data (same sparsity
#'     structure as \code{foc_resp}).  The reference group was constructed by:
#'     (1) using \code{foc_score} as true ability values (1F scaling, i.e.,
#'     the reference group has the same size as the focal group);
#'     (2) generating item responses from the \emph{original} (non-drifted)
#'     item parameters; and (3) running an independent CAT simulation.
#'     This synthetic reference group mirrors the construction described in
#'     Lim & Han (in press).}
#'   \item{ref_score}{A numeric vector of length 3000 containing the
#'     \strong{synthetic reference group} final ML theta estimates.}
#' }
#'
#' @details
#' \strong{Simulation conditions:}
#' \itemize{
#'   \item Item pool: 360 three-parameter logistic model (3PLM) items
#'   \item Test length: 30 items per examinee
#'   \item Item selection: Maximum Fisher Information (MFI) with target
#'     exposure rate 0.30
#'   \item Focal group: \eqn{n = 3{,}000}; true abilities drawn from
#'     \eqn{N(0, 1)}
#'   \item Reference group: \eqn{n = 3{,}000} (1F); true abilities =
#'     \code{foc_score}
#'   \item IPD items: 18 (5% of 360), randomly drawn from \code{key_item}
#'   \item IPD manipulation: both \emph{a} and \emph{b} decreased by 0.50
#'   \item Interim scoring: EAP; final scoring: ML
#'   \item Scaling constant: \eqn{D = 1.7}
#'   \item Random seed: 2024
#' }
#'
#' \strong{Note on reference group size:}
#' A 1F reference group (same size as the focal group) is used here for
#' compactness.  In practice, larger synthetic reference groups (e.g., 3F - 8F)
#' are recommended to improve RIPD detection power (Lim & Han, in press).
#' A larger reference group can be created by replicating the focal theta
#' estimates: e.g., \code{rep(foc_score, times = 3)} for a 3F group, then
#' re-running the CAT simulation with the original item parameters.
#'
#' @references
#' Lim, H., & Han, K. T. (in press). IRT residual-based approach to detecting
#' item parameter drift in CAT.
#' \emph{Journal of Educational and Behavioral Statistics}.
#'
#' @seealso \code{\link{ripd}}, \code{\link{pcd2}}, \code{\link{simCAT_DC}}, \code{\link{simCAT_MX}}
#'
#' @examples
#' data(simIPD)
#' str(simIPD, max.level = 1)
#'
#' # Item parameter data frame (first 6 rows)
#' head(simIPD$item_par)
#'
#' # Focal group response matrix (sparse)
#' dim(simIPD$foc_resp)
#' mean(is.na(simIPD$foc_resp))  # ~0.92 (92% NA due to CAT)
"simIPD"