% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sim.data.MIRT.R
\name{sim.data.MIRT}
\alias{sim.data.MIRT}
\title{Simulate Data from the Multidimensional IRT (MIRT) Model}
\usage{
sim.data.MIRT(
  N = 500,
  I = 20,
  D = 2,
  model = "m2pl",
  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{model}{Character; one of \code{"m1pl"}, \code{"m2pl"} (default),
\code{"m3pl"}, \code{"m4pl"}.}

\item{Q.matrix}{An optional \eqn{I \times D} 0/1 matrix. If \code{NULL},
a default structure with triangular identification pattern is used.}

\item{Corr}{An optional \eqn{D \times D} correlation matrix. If
\code{NULL}, the identity matrix is used (orthogonal factors).}

\item{rotate}{Optional rotation method name (passed to
\pkg{GPArotation} or \code{stats::promax}). Applicable only when
\eqn{D > 1} and all Q-matrix entries are non-zero.}

\item{promax_m}{Integer; power parameter for \code{"promax"} rotation
(default: 4).}
}
\value{
An object of class \code{"data.MIRT"}, a list containing:
\describe{
\item{\code{data}, \code{response}}{\eqn{N \times I} binary response
matrix (identical).}
\item{\code{theta}}{\eqn{N \times D} matrix of true latent trait
values.}
\item{\code{par}}{\eqn{I \times (D+3)} matrix of true item parameters
(columns \code{a1..aD, b, c, d}).}
\item{\code{probability}}{\eqn{N \times I} matrix of response
probabilities.}
\item{\code{Q.matrix}}{\eqn{I \times D} Q-matrix used.}
\item{\code{Corr}}{\eqn{D \times D} correlation matrix.}
\item{\code{model}, \code{N}, \code{I}, \code{D}}{Data-generating
parameters.}
}
}
\description{
Generates binary response data, latent trait vectors, and item parameters
from the multidimensional extension of the 1PL--4PL item response models.
The latent traits are drawn from a multivariate normal distribution with
a user-specified correlation matrix. Discrimination parameters respect a
Q-matrix structure and may be optionally rotated.
}
\section{Data Generation Process}{


\enumerate{
\item \strong{Latent traits:}
\eqn{\boldsymbol{\theta}_j \sim N_D(\mathbf{0}, \boldsymbol{\Sigma})},
where \eqn{\boldsymbol{\Sigma}} is the \eqn{D \times D} correlation
matrix \code{Corr}.
\item \strong{Item parameters:}
\itemize{
\item \eqn{a_{id} \sim \text{Lognormal}(0.25, 0.25)} for
\eqn{q_{id} = 1} (M2PL/M3PL/M4PL);
\eqn{a_{id} = 1} for all items and dimensions in M1PL.
\item \eqn{b_i \sim N(0, 1)} (difficulty).
\item \eqn{c_i \sim U(0, 0.35)} (lower asymptote; M3PL/M4PL only).
\item \eqn{d_i \sim U(0.65, 1)} (upper asymptote; M4PL only).
}
\item \strong{Response probabilities:}
\eqn{P_{ij} = P(Y_{ij} = 1 \mid \boldsymbol{\theta}_j)} per the
specified MIRT model (see \code{\link{fit.MIRT}} for the IRF
equations).
\item \strong{Binary responses:}
\eqn{Y_{ij} \sim \text{Bernoulli}(P_{ij})}.
}

Optional rotation of the loading matrix \code{a} and corresponding
transformation of \code{theta} and \code{Corr} is applied before
response generation.
}

\examples{
# Basic 2D 2PL simulation
sim <- sim.data.MIRT(N = 20, I = 6, D = 2, model = "m2pl")

# With correlated factors and rotation
Corr <- matrix(c(1, 0.5, 0.5, 1), 2, 2)
sim_rot <- sim.data.MIRT(N = 20, I = 6, D = 2, model = "m2pl",
                         Q.matrix = matrix(1, 6, 2),
                         Corr = Corr, rotate = "oblimin")

# Fit the simulated data
fit <- fit.MIRT(
  sim$response, model = "m2pl", D = 2, method = "iStEM",
  control.method = list(
    vis = FALSE, seed = 123,
    M = 2, B = 2, burnin.maxitr = 2,
    maxitr = 3, eps1 = 10, eps2 = 10,
    estimate.se = FALSE)
)
cor(fit$theta$est, sim$theta)  # trait recovery

}
\seealso{
\code{\link{fit.MIRT}} for fitting the MIRT model,
\code{\link{model.MIRT}} for computing response probabilities.
}
