% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sim.data.MGGUM.R
\name{sim.data.MGGUM}
\alias{sim.data.MGGUM}
\title{Simulate Data from the Multidimensional Generalized Graded Unfolding Model}
\usage{
sim.data.MGGUM(
  N = 500,
  I = 20,
  D = 2,
  length.poly = 5,
  Q.matrix = NULL,
  Corr = NULL
)
}
\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 indicating the number of
categories for each item. A scalar is recycled to length \eqn{I}.}

\item{Q.matrix}{Optional \eqn{I \times D} matrix with values -1, 0, or 1.
\itemize{
\item \code{1}: active dimension with positive-side \code{delta}
\item \code{-1}: active dimension with negative-side \code{delta}
\item \code{0}: \code{a} and \code{delta} fixed to 0 (inactive dimension)
}
The sign controls the item-location side, not the sign of discrimination.
If \code{NULL}, a default matrix of randomly signed active entries is used.}

\item{Corr}{Optional \eqn{D \times D} correlation matrix. If \code{NULL},
the identity matrix is used.}
}
\value{
An object of class \code{"data.MGGUM"}, 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 (2D + \max_i K_i)} matrix of GGUM item
parameters: discrimination columns, location columns, and stacked
threshold 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{N}, \code{I}, \code{D}, \code{call}}{Data-generating
metadata.}
}
}
\description{
Generates polytomous responses from the same distance-based MGGUM
probability function used by \code{\link{model.MGGUM}} and
\code{\link{fit.MGGUM}}. For each item, active discriminations are drawn
from \eqn{U(0.5, 2)}, active locations follow the sign of the Q-matrix,
\eqn{\tau_{i0}=0}, and the remaining \eqn{\tau} values are ordered
negative thresholds.
}
\section{Data Generation Process}{

\enumerate{
\item Draw latent traits from
\eqn{N_D(\mathbf{0}, \boldsymbol{\Sigma})}.
\item Generate discrimination, location, and threshold parameters under
the sign constraints encoded by \code{Q.matrix}.
\item Compute stacked category probabilities with
\code{\link{model.MGGUM}}.
\item Sample one ordinal response per person and item. A category can be
absent in a finite sample; \code{length.poly} retains the intended
support.
}
}

\examples{
set.seed(123)
sim <- sim.data.MGGUM(N = 20, I = 5, D = 2, length.poly = 4)
str(sim$response)
dim(sim$par)
table(sim$response[, 1])

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