\name{repBIRT}
\alias{repBIRT}

\title{
  Simulate replicated datasets using the posterior parameter samples from a BoundIRT-object}
\description{
  To facilitate posterior predictive model checking, this function can be used to simulate replicated datasets for each of the samples from the posterior parameter distribution in a \code{BoundIRT}-object.}

\usage{
repBIRT(object, nrep=1000, silent=FALSE)

}
\arguments{

  \item{object}{A \code{BoundIRT}-object}
  \item{nrep}{Number of replicated datasets to produce. See \bold{Details}.}
  \item{silent}{If TRUE no details are displayed about the progress}
}

\details{
  \code{repBIRT} is a wrapper around \code{rBIRT} extracting the posterior parameter samples, and simulating data for a subset of the samples. That is, for many posterior predictive purposes, not all posterior parameter samples are needed. Therefore, only the last \code{nrep} samples will be used. Setting \code{nrep} to be equal to the total number of posterior samples will use all of them.}


\value{
  An array of size \code{nrep} by \code{N} by \code{nit} containing the replicated datasets.
}
\references{
Gabry J, Simpson D, Vehtari A, Betancourt M, Gelman A (2019). Visualization in
  Bayesian workflow. \emph{Journal of the Royal Statistical Society, A}, \bold{182}, 389-402. \doi{10.1111/rssa.12378}

}
\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{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{
 #load the Abasement data and fitting results for the Beta IRT model
 data(Abasement)
 data(out_beta)

 #generate 10 replicated datasets
 z_rep=repBIRT(out_beta,nrep=10)

 #these can be used for e.g., posterior predictive checks
 #using the suggested bayesplot library
 if (requireNamespace("bayesplot", quietly = TRUE)) {
   bayesplot::ppc_dens_overlay(Abasement[,1],z_rep[,,1])  #for item 1
   bayesplot::ppc_dens_overlay(Abasement[,1],z_rep[,,2])  #for item 2, etc.
 }

}
\keyword{models}
\keyword{multivariate}
