\name{bridgeBIRT}
\alias{bridgeBIRT}

\title{
  Estimate fully marginalized log-likelihood  using bridge sampling.}
\description{
  This function uses bridge sampling as discussed by Gronau et al. (2017) to obtain the fully marginalized likelihood of an estimated bounded IRT model.
}

\usage{
bridgeBIRT(object,niter=10000,tol=1e-7,silent=FALSE)
}
\arguments{

  \item{object}{A \code{BoundIRT}-object.}
  \item{niter}{Number of iterations of the algorithm.}
  \item{tol}{Tolerance for the algorithm. Algorithm stops if the change in \eqn{\log(r_1)} between subsequent iterations is smaller than this value, see \bold{Details}.}
  \item{silent}{If TRUE no progress is displayed during estimation.}
}

\details{
In bridge sampling, a so-called bridge function is used to estimate the fully marginalized likelihood by combining existing posterior samples with additional samples drawn from a proposal distribution. In \code{bridgeBIRT}, a multivariate normal proposal distribution is used. Using these proposal samples, the final expression for the marginal likelihood involves an iterative procedure (see Equation 4.1 from Meng & Wong, 1996) which stops if the change in marginal likelihood between iterations does not exceed the tolerance.

To improve numerical stability and avoid overflow in the \code{exp()} function, we follow the approach described in Appendix B of Gronau et al. (2017). Specifically, the median log-likelihood value, \eqn{l^\star}, is subtracted from the log-marginal likelihood, and only the remaining component, \eqn{r_1}, is estimated. After the iterative scheme has converged, these two components are recombined to obtain the final estimate of the marginal likelihood.
}
\value{
  A list containing:
  \item{log_ml}{The fully marginalized log-likelihood.}
  \item{r1}{The estimate of \eqn{r_1}.}
  \item{l_start}{The value of \eqn{l^\star} used (median log-likelihood across posterior samples).}
  }

\references{
Gronau, Q. F., et al. (2017). A tutorial on bridge sampling. \emph{Journal of mathematical psychology}, \bold{81}, 80-97.
\doi{10.1016/j.jmp.2017.09.005}


Meng, X. L., & Wong, W. H. (1996). Simulating ratios of normalizing constants via a simple identity: a theoretical exploration. \emph{Statistica Sinica}, \bold{6}, 831-860. \url{https://www.jstor.org/stable/24306045}
}

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

  \donttest{
  # read in the pre-estimated object containing the Abasement results
  # for the Beta IRT model and estimate the marginal likelihood
  \donttest{
  data(out_beta)
  bridgeBIRT(out_beta)
  }
  }

}
\keyword{models}
\keyword{multivariate}
