\name{plot.BoundIRT}
\alias{plot.BoundIRT}

\title{
  Plotting function for \code{BoundIRT}-objects.}
\description{
  This function can be used to produce item and test information curves, and the model implied densities of a fitted bounded continuous IRT model.
}

\usage{
\method{plot}{BoundIRT}(x,
     what=c("icc","iic","tic","density"),
     items=NULL,
     separate=FALSE,
     range=c(-3,3),
     by=.001,
     ymax=NULL,
     xlab=NULL,
     ylab=NULL,
     main=NULL,
     col=NULL,
     lwd_prob=2,
     ...)
}
\arguments{

  \item{x}{A \code{BoundIRT}-object to produce the plots for.}

    \item{what}{ A character string indicating what plot to produce. The options are:
      \describe{
              \item{"icc"}{(Default) Item characteristic curves.}
              \item{"iic"}{Item information curves.}
              \item{"tic"}{Test information curves.}
              \item{"density"}{The model implied density for the observed data.}
        }}
    \item{items}{A numeric vector indicating which items to consider for the plots. If NULL all items are plotted (default). If \code{items} is provided and \code{what="tic"}, the test information is based only on these items.}
    \item{separate}{If \code{separate=TRUE} the different items are depicted in separate plots}
    \item{range}{Range of the latent variable on the x-axis. Argument will be neglected for \code{what="density"}.}
    \item{by}{increment for the x-axis of the plot.}
    \item{ymax}{Specify the maximum value for the y-axis. For multiple items, this can be an array of size length(items), or a single value      for all items.}
    \item{xlab}{Specify an alternative label for the x-axis.}
    \item{ylab}{Specify an alternative label for the y-axis.}
    \item{main}{Specify an alternative title for plot.}
    \item{col}{The color code to be used for plotting different items. Can be an array and will be recycled if length(items)!=length(col). Argument can be any valid R color specification. Default is 1:6.}
    \item{lwd_prob}{For \code{what="density"} and a model with zero and/or one inflation, the probabilities of zero and one scores are depicted using vertical lines. The width of these lines can be set using this argument. Default is 2. Width of the other lines can be set using \code{...} below.}
    \item{...}{Other arguments to be passed to \code{\link{matplot}}}.

  }

\details{
  Plotting the model implied densities is relatively slow due to the numerical integration involved in marginalizing over the latent variable. In the presence of zero and/or one inflation, model implied densities inclulde the probability of zero and/or one scores by a vertical line. As this vertical line represents a probability and the rest of the plot is about density, the zero/one probabilities may be masked if density values are large even if the zero/one inflation is quite substantial. See \bold{Examples} how to extract the zero/one probabilities in the case these are hard to see from the plot.
}
\value{
  A matrix containing x-axis values (either the latent variable or the observed variable) and the y-axis values for each item.}

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

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

\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.

\code{\link{rBIRT}} simulate data according to a (zero/one inflated) bounded IRT model.
}
\examples{

 #load results for zero inflated beta IRT model fit to the Abasement data
 # see ?Abasement and ?out_beta
 data(out_beta)

 # plots for item 1
 oldpar=par(mfrow=c(2,2))
 plot(out_beta,what="icc",items=1)
 plot(out_beta,what="iic",items=1)
 plot(out_beta,what="tic",items=1)
 den_plot=plot(out_beta,what="density",items=1)
 par(oldpar)

 #extract zero probabilities (there are no ones in the Abasement data)
 den_plot$out[1]        # zero probabilities

}
\keyword{models}
\keyword{multivariate}
