\name{fitBIRT}
\alias{fitBIRT}

\title{
  Fit various IRT models for bounded continuous items to data}
\description{
  This function fits various IRT models for bounded continuous items using MCMC sampling in R-package 'rstan' (Stan Development Team, 2025).
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 fitted with or without a zero and/or one inflation (Molenaar et al., 2022).}

\usage{
fitBIRT(z,
        model=c("beta","samejima","simplex","normal"),
        inflated=c("auto","zero","one","both","none"),
        iter=2000,
        warmup=NULL,
        nchains=1,
        prior=NULL,
        silent=FALSE,
        ...)
}
\arguments{

  \item{z}{A matrix of size \code{N} by \code{n} containing the bounded continuous item scores, where \code{N} is
        the number of subjects and \code{n} is the number of items. The items should be coded in a \eqn{(0,1)}, a \eqn{[0,1)}, a \eqn{(0,1]}, or \eqn{[0,1]} interval.}

    \item{model}{A character string indicating the model to be fit. 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)}
        }}
    \item{inflated}{A character string indicating the kind of inflation to use. The options are:
        \describe{
              \item{"auto"}{(Default) Zero and one inflation parameters are only added for items that actually contain zero and/or one scores               .}
              \item{"zero"}{Zero inflation parameters are estimated for all items.}
              \item{"one"}{One inflation parameters are estimated for all items.}
              \item{"both"}{Zero and one inflation parameters are estimated for all items.}
              \item{"none"}{No zero-one inflation. The data shouldn't contain 0 or 1 scores.}
        }
  }
  \item{iter}{Number of MCMC samples to draw, including warmup samples}
  \item{warmup}{Number of warmup samples. Default is floor(iter/2)}
  \item{nchains}{Number of MCMC chains to use. Default is 1.}
  \item{prior}{If \code{NULL}, the default priors are being used. Otherwise a list can be specified giving the prior standard deviation of (some of) the parameters. See \bold{Details}}
  \item{silent}{If TRUE no details are displayed during estimation}

  \item{...}{Additional arguments to pass to \code{rstan::sampling()}}

  }

\details{
  Function \code{fitBIRT} fits the models discussed by Molenaar et al. (2022) including the facilities for zero and/or one inflation. If \eqn{\alpha_{i}}, \eqn{\beta_{i}}, and \eqn{\phi_{i}} are respectively the discrimination, easiness, and dispersion parameters of item \code{i}, \eqn{\theta_{p}} is the latent variable position of subject \code{p}, and \eqn{z_{pi}} is the bounded continuous item score of subject \code{p} on item \code{i}, then the different models can be given as follows:

  \describe{
  \item{\bold{Beta model}}{

    \eqn{z_{pi} \sim \text{Beta} (a_{pi},b_{pi})}

    \eqn{a_{pi} = \exp(.5(\alpha_{i}\theta_{p}+\beta_{i} + \log(\phi_i)))}

    \eqn{b_{pi} = \exp(.5(-\alpha_{i}\theta_{p}-\beta_{i} + \log(\phi_i)))}
  }
  \item{\bold{Samejima model}}{

    \eqn{z_{pi}^{'} \sim \text{Normal} (\alpha_{i}\theta_{p}+\beta_{i},\phi_i)}

    \eqn{z_{pi}^{'} = \text{logit}(z_{pi})}
 }
  \item{\bold{Simplex model}}{

    \eqn{z_{pi} \sim \text{Simplex}(1/(1+\exp(-(\alpha_{i}\theta_{p}+\beta_{i}))),\phi_i)}
}
  \item{\bold{Normal model}}{

    \eqn{z_{pi} \sim \text{Normal} (\alpha_{i}\theta_{p}+\beta_{i},\phi_i)}
}
  \item{\bold{Zero and/or one inflation}}{

  To these models, zero and/or one inflation can be added as follows:

  \eqn{A = P(z_{pi}=0|\theta_{p}) = 1/(1+\exp(-(\gamma_{0i}-\alpha_{i}\theta_{p})))}

  \eqn{B = P(z_{pi}=1|\theta_{p}) = 1-1/(1+\exp(-(\gamma_{1i}-\alpha_{i}\theta_{p})))}

  where \eqn{\gamma_{0i}} and \eqn{\gamma_{1i}} model the amount of zero and one inflation respectively. The conventional models above are accommodated as follows:

  \eqn{f(z_{pi}|\theta_{p}) = A} for \eqn{z_{pi}=0}

  \eqn{f(z_{pi}|\theta_{p}) = B} for \eqn{z_{pi}=1}

  \eqn{f(z_{pi}|\theta_{p}) = [ (1-B) - A ] \times k(z_{pi}|\theta_{p})} for \eqn{z_{pi}\in(0,1)}


  where \eqn{k(.)} is the distribution according to the conventional model above. See Molenaar et al. (2022) for details.

  In estimating the models above, normal priors are specified for \eqn{\theta_p, \log(\alpha_i), \beta_i, \log(\phi_i), \gamma_{0i}, \text{and } \gamma_{1i}}. All priors have mean 0, and by default, a standard deviation of 1 for \eqn{\theta_p} (for identification purposes) and 10 for the other parameters. Changing (one of) the defaults involves specifying a list with elements \code{sT, sA, sB, sP} and/or \code{sG}, which overrides the default. It is thus possible to stick to the defaults, but change the prior standard deviation for \eqn{\log\alpha_i} and  \eqn{\beta_i} by using for instance \code{prior=list(sA=5,sB=5)}. Note that setting \code{sG} affects both the prior of \eqn{\gamma_{0i} \text{ and } \gamma_{1i}}.
}
}
}
\value{
  An object of class \code{BoundIRT} with values:
   \item{ output}{The posterior means and standard deviations of the item parameters.}
   \item{ theta}{The posterior means and standard deviations of the person parameters.}
   \item{ mcmc}{ The \code{stanfit} object containing all sampling results. See \code{\link[rstan:stanfit-class]{stanfit}}.}
    \item{ prior}{ The prior standard deviations used in the list format discussed above.}

For the \code{BoundIRT} object, the following methods are available:
  \item{summary.BoundIRT}{which gives the default \code{rstan} summary overview of the parameters.}
  \item{plot.BoundIRT}{which provides various IRT plotting facilities, see \code{\link{plot.BoundIRT}}}
  \item{print.BoundIRT}{which gives the posterior means and standard deviations of the item parameters.}
  \item{coef.BoundIRT}{which returns the posterior means of  the item parameters, see \code{\link{coef.BoundIRT}}.}
}
\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{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.

\code{\link{rBIRT}} simulate data according to a (zero/one inflated) bounded IRT model.
}
\examples{
 #load the Abasement data which contains zero inflation
 data(Abasement)

 # fit a zero inflated beta IRT model
 # for illustrative purposes, we only use 20 iterations.
 # In practice use many more!

 res=fitBIRT(Abasement,model="beta",iter=20)
 print(res)   # quick overview
 coef(res)   # extract posterior item parameter means
 summary(res,c("alpha","beta"))   # request the rstan summary


}
\keyword{models}
\keyword{multivariate}
