% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sim.data.FCGDINA.R
\name{sim.data.FCGDINA}
\alias{sim.data.FCGDINA}
\title{Simulate Forced-Choice GDINA Data}
\usage{
sim.data.FCGDINA(
  N.person = 1000,
  N.block = 10,
  I.block = 2,
  D = 3,
  model = "GDINA",
  fc.type = "RANK",
  control = NULL
)
}
\arguments{
\item{N.person}{Number of persons.}

\item{N.block}{Number of forced-choice blocks.}

\item{I.block}{Number of items per block when \code{control$block.items} is
not supplied. Must be at least 2.}

\item{D}{Number of latent attributes. If \code{control$Q.matrix} is supplied,
\code{D} is reset to \code{ncol(control$Q.matrix)}.}

\item{model}{CDM item model: \code{"DINA"}, \code{"DINO"}, \code{"ACDM"}, or
\code{"GDINA"}.}

\item{fc.type}{Forced-choice response type: \code{"RANK"}, \code{"MOLE"}, or
\code{"PICK"}. A scalar value is recycled to all blocks; a vector of
length \eqn{B} may be supplied for mixed block formats.}

\item{control}{Optional named list controlling the data-generating process.
Supported entries are described below.}
}
\value{
An object of class \code{"data.FCGDINA"}, a list containing:
\describe{
\item{\code{data}}{\eqn{N \times B} character matrix of forced-choice
responses, such as \code{"1>3>2"} for ranking blocks.}
\item{\code{response}}{\eqn{N \times B} integer matrix of 1-based pattern
indices matching \code{patterns}.}
\item{\code{alpha}}{\eqn{N \times D} binary matrix of true latent
attribute profiles.}
\item{\code{gs}}{\eqn{I \times 2} matrix of item probability bounds
\code{P0} and \code{P1}.}
\item{\code{delta.list}}{List of true CDM delta vectors, one per
statement.}
\item{\code{design.matrix.list}}{List of CDM design matrices used to map
delta parameters to item endorsement probabilities.}
\item{\code{Q.matrix}}{\eqn{I \times D} Q-matrix.}
\item{\code{block.items}}{List of statement indices per forced-choice
block.}
\item{\code{model}}{CDM item model used for simulation.}
\item{\code{patterns}}{List of observed response-pattern matrices per
block.}
\item{\code{patterns.total}}{List of full-ranking pattern matrices per
block.}
\item{\code{prob.item}}{\eqn{N \times I} matrix of item-level endorsement
probabilities for sampled persons.}
\item{\code{prob.states}}{\eqn{I \times 2^D} matrix of item endorsement
probabilities for every attribute pattern.}
\item{\code{prob}}{\eqn{N \times \sum_b P_b} matrix of forced-choice
response-pattern probabilities.}
\item{\code{N.person}, \code{N.block}, \code{I.block}, \code{D},
\code{I.states}, \code{fc.type}}{Final data-generating dimensions
and response type.}
\item{\code{call}, \code{arguments}}{Matched call and effective
simulation arguments.}
}
}
\description{
Generates forced-choice response data from a cognitive diagnostic item
model. The item-level model may be DINA, DINO, ACDM, or GDINA. The resulting
statement endorsement probabilities are transformed into forced-choice
response probabilities for \code{"RANK"}, \code{"MOLE"}, or \code{"PICK"}
blocks using the same sequential Luce--Plackett mechanism used by
\code{\link{sim.data.FCMIRT}} and \code{\link{sim.data.FCGGUM}}.
}
\section{Data-Generating Process}{


The simulation proceeds in four steps:
\enumerate{
\item Generate or validate the Q-matrix and forced-choice block
structure.
\item Generate latent attribute profiles \eqn{\boldsymbol{\alpha}_n}.
\item Generate item-level CDM endorsement probabilities using guessing
and slipping-style bounds \code{P0} and \code{P1}; then recover the
corresponding CDM delta parameters from the design matrix.
\item Convert item endorsement probabilities into block-level
forced-choice pattern probabilities and sample observed responses.
}

Attribute profiles can be generated from a higher-order latent trait model,
a thresholded multivariate normal model, a uniform distribution over all
attribute patterns, or supplied directly through \code{control$alpha}.
}

\section{Control List}{


\describe{
\item{\code{Q.matrix}}{Optional \eqn{I \times D} binary Q-matrix. If
omitted, a Q-matrix is generated by \code{sim.data.Q.CDM()}.}
\item{\code{block.items}}{Optional list of item indices per block. If
omitted, blocks are formed sequentially using \code{N.block} and
\code{I.block}.}
\item{\code{single}}{Logical passed to \code{sim.data.Q.CDM()} when
\code{Q.matrix} is generated internally. Default \code{TRUE}.}
\item{\code{alpha}}{Optional \eqn{N \times D} binary matrix of true
attribute profiles. If supplied, latent attributes are not
generated.}
\item{\code{distribution}}{Latent attribute distribution when
\code{alpha} is not supplied. Options are \code{"horder"}
(default; alias \code{"higher.order"}), \code{"mvnorm"}, and
\code{"uniform"}.}
\item{\code{delta1}, \code{delta0}, \code{theta}}{Higher-order
discrimination, threshold, and person trait values used when
\code{distribution = "horder"}. Defaults are generated from
log-normal, normal, and standard normal distributions.}
\item{\code{Corr}, \code{threshold}}{Correlation matrix and thresholds
used when \code{distribution = "mvnorm"}.}
\item{\code{gs}}{Optional \eqn{I \times 2} matrix with columns
\code{P0} and \code{P1}; \code{P0} is the lower endorsement
probability and \code{P1} is the upper endorsement probability for
each statement. Defaults are sampled from \code{U(0, .2)} and
\code{U(.8, 1)}.}
\item{\code{mono.constraint}}{Logical; whether to enforce monotonic item
probabilities for GDINA item generation. Default \code{TRUE}.}
}
}

\examples{
set.seed(123)
sim <- sim.data.FCGDINA(N.person = 20, N.block = 3, I.block = 2,
                        D = 2, model = "DINA", fc.type = "RANK")

str(sim$data)
head(sim$response)
head(sim$alpha)
sim$Q.matrix

# Mixed response formats across blocks.
sim.mix <- sim.data.FCGDINA(
  N.person = 12, N.block = 3, I.block = 3, D = 2,
  model = "GDINA", fc.type = c("RANK", "MOLE", "PICK")
)
vapply(sim.mix$patterns, nrow, integer(1))

}
\references{
de la Torre, J. (2011). The generalized DINA model framework.
\emph{Psychometrika}, 76(2), 179--199.
\doi{10.1007/s11336-011-9207-7}
}
\seealso{
\code{\link{fit.FCGDINA}}, \code{\link{model.FCGDINA}},
\code{\link{sim.data.FCMIRT}}, \code{\link{sim.data.FCGGUM}},
\code{\link{sim.data.FCDCM}}
}
