% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sim.data.MGPCM.R
\name{sim.data.MGPCM}
\alias{sim.data.MGPCM}
\title{Simulate Data from the Multidimensional Generalized Partial Credit Model}
\usage{
sim.data.MGPCM(
  N = 500,
  I = 20,
  D = 2,
  length.poly = 5,
  Q.matrix = NULL,
  Corr = NULL,
  rotate = NULL,
  promax_m = 4
)
}
\arguments{
\item{N}{Integer; number of examinees (default: 500).}

\item{I}{Integer; number of items (default: 20).}

\item{D}{Integer; number of latent dimensions (default: 2).}

\item{length.poly}{Integer vector or scalar; number of categories per
item. Recycled to length \eqn{I} if scalar (default: 5).}

\item{Q.matrix}{Optional \eqn{I \times D} 0/1 matrix. \code{NULL} uses
a triangular identification pattern.}

\item{Corr}{Optional \eqn{D \times D} correlation matrix.}

\item{rotate}{Optional rotation method (\pkg{GPArotation} or
\code{"promax"}).}

\item{promax_m}{Power parameter for Promax (default: 4).}
}
\value{
An object of class \code{"data.MGPCM"}, a list containing:
\describe{
\item{\code{data}, \code{response}}{\eqn{N \times I} integer response
matrices with categories coded from 0 to \eqn{K_i - 1}.}
\item{\code{theta}}{\eqn{N \times D} matrix of true latent traits.}
\item{\code{par}}{\eqn{I \times (D + \max_i K_i)} matrix of item
parameters; discrimination columns are followed by category
intercept columns.}
\item{\code{probability}}{\eqn{N \times \sum_i K_i} matrix of stacked
category probabilities.}
\item{\code{Q.matrix}, \code{length.poly}, \code{Corr}}{Design matrix,
category counts, and latent correlation matrix used to generate
the data.}
\item{\code{model}, \code{N}, \code{I}, \code{D}, \code{call}}{
Data-generating metadata.}
}
}
\description{
Generates polytomous (multi-category) response data from the MGPCM.
Category probabilities use the same softmax formulation as
\code{\link{model.MGPCM}}: \eqn{\log P(Y=k)} is proportional to
\eqn{k\,\mathbf{a}_i'\boldsymbol{\theta}_j + d_{ik}}.
The requested category counts are retained even when a finite sample does
not contain every possible category.
}
\section{Data Generation Process}{

\enumerate{
\item \strong{Latent traits:}
\eqn{\boldsymbol{\theta}_j \sim N_D(\mathbf{0}, \boldsymbol{\Sigma})}.
\item \strong{Item parameters:}
\eqn{a_{id} \sim \text{Lognormal}(0.25, 0.25)} (active dimensions),
\eqn{d_{i0}=0}, and
\eqn{d_{i1},\dots,d_{i,K_i-1}} are sorted draws from
\eqn{N(0,1)} used as category intercepts.
\item \strong{Responses:}
\eqn{Y_{ij} \sim \text{Categorical}(P(Y_{ij} = k \mid \boldsymbol{\theta}_j))}
for \eqn{k = 0, \dots, K_i - 1}.
}
}

\examples{
set.seed(123)
sim <- sim.data.MGPCM(N = 20, I = 5, D = 2, length.poly = 4)
str(sim$response)
dim(sim$probability)
sim$length.poly

}
\seealso{
\code{\link{fit.MGPCM}}, \code{\link{model.MGPCM}}
}
