\name{rBIRT}
\alias{rBIRT}

\title{
  Simulate data according to various IRT models for bounded continuous items}
\description{
  This function simulates data according to various IRT models for bounded continuous items.
Available models include the Beta IRT model by Noel and Dauvier (2007), the continuous response
model by Samejima (1973), the unbounded normal model by Mellenbergh (1994), and the Simplex IRT model
by Flores et al. (2020). All models can be simulated  with or without zero and/or one inflation (Molenaar et al., 2022).}

\usage{
rBIRT(N,nit,alpha,beta,phi,theta,
      gamma0=NULL,
      gamma1=NULL,
      model=c("beta","samejima","simplex","normal"))

}
\arguments{

  \item{N}{Number of subjects}
  \item{nit}{Number of items}
  \item{alpha}{A nit-dimensional array of true discrimination parameter values}
  \item{beta}{A nit-dimensional array of true easiness parameter values}
  \item{phi}{A nit-dimensional array of true dispersion parameter values}
  \item{theta}{A N-dimensional array of true person parameter values}
  \item{gamma0}{Optional: A nit-dimensional array of true zero inflation parameters}
  \item{gamma1}{Optional: A nit-dimensional array of true one inflation parameters}

    \item{model}{A character string indicating what model to use to simulate the data. The options are:
        \describe{
              \item{"beta"}{(Default) The Beta IRT model by Noel and Dauvier (2007) with item specific discrimination parameter.}
              \item{"samejima"}{The IRT model by Samejima (1973).}
              \item{"simplex"}{The Simplex IRT model by Flores et al. (2020).}
              \item{"normal"}{The (unbounded) unidimensional normal linear factor model by Mellenbergh (1994)}
        }}
     }

\details{
  If arguments gamma0 and gamma1 are not provided, data is simulated according to the conventional models. Zero and one inflation can be introduced seperately by only providing gamma0 or gamma1, or zero and one inflation can both be introduced by specifying both gamma0 and gamma1. If the interest is in simulating some -but not all- items with zero and/or one inflation, the uninflated items can be coded as -Inf in gamma0 and Inf in gamma1. See \link{fitBIRT} for the exact parameterization of the models.}


\value{
  A matrix of size \code{N} by \code{nit} containing the simulated item responses.
}
\references{



Flores, S., Bazan, J.L., & Bolfarine, H. (2020). A hierarchical joint model for bounded
response time and response accuracy. In M. Wiberg, D. Molenaar, J. González,
U. Bockenholt, & K. S. Kim (Eds.), \emph{Quantitative psychology: The 84th Annual
Meeting of the Psychometric Society, Santiago de Chile, Chile} (pp. 95-109). Springer.
\doi{10.1007/978-3-030-43469-4_8}


Mellenbergh, G. J. (1994). A unidimensional latent trait model for continuous item
responses. \emph{Multivariate Behavioral Research}, \bold{29}(3), 223-236.
\doi{10.1207/s15327906mbr2903_2}

Molenaar, D., Cúri, M., & Bazán, J.L. (2022). Zero and One Inflated Item Response Theory Models for Bounded Continuous Data. \emph{Journal of Educational and Behavioral Statistics}, \bold{47}, 693-735.
\doi{10.3102/10769986221108455}

Noel, Y., & Dauvier, B. (2007). A beta item response model for continuous bounded
responses. \emph{Applied Psychological Measurement}, \bold{31}(1), 47-73.
\doi{10.1177/0146621605287691}

Samejima, F. (1973). Homogeneous case of the continuous response model. \emph{Psychometrika},
\bold{38}(2), 203-219.\doi{10.1007/BF02291114}

Stan Development Team (2025). RStan: the R interface to Stan. R package version 2.32.7.
\url{https://mc-stan.org/}

}
\author{ Dylan Molenaar \email{d.molenaar@uva.nl}}

\seealso{

\code{\link{fitBIRT}} to estimate various bounded continuous IRT models to data.

\code{\link{plot.BoundIRT}} to plot the item and test information curves and predicted densities for the different models.

\code{\link{coef.BoundIRT}} to extract item parameter estimates from a \code{BoundIRT} object.

\code{\link{loglikBIRT}} to calculate the log-likelihood for each person and each posterior sample. Needed to calculate WAIC and LOOIC for a given model.

\code{\link{repBIRT}} to simulate replicated datasets using (a subset of) the posterior parameter samples. For posterior predictive model checking.

\code{\link{bridgeBIRT}} to use bridge sampling to calculate the marginal loglikelihood for a model in a \code{BoundIRT} object.

\code{\link{latregBIRT}} to conduct a latent regression of the person parameters on some observed predictor variables.

}

\examples{

 # data sim with 100 subjects and 10 items according to
 # beta IRT model with zero and one inflation

 nit=10
 N=100
 beta=runif(nit,.5,1)
 alpha=runif(nit,.5,.7)
 gamma0=runif(nit,-3,-1.5)
 gamma1=runif(nit,1.5,3)

 theta=rnorm(N)

 phi=seq(1.5,2.5,length=nit)
 z=rBIRT(N,nit,alpha,beta,phi,theta,gamma0,gamma1,model="beta")

}
\keyword{models}
\keyword{multivariate}
