\name{latregBIRT}
\alias{latregBIRT}

\title{
  Latent regression of the latent variable from a bounded IRT model on observed predictor variables}
\description{
  This function takes a fitted \code{BoundIRT} object and subjects the posterior latent variable distribution to a linear regression model.
}

\usage{
latregBIRT(formula, X, object, method=c("posterior","Croon"), nboot=1000)}
\arguments{

  \item{formula}{A formula to specify the linear regression of the latent variable on the predictor variables in \code{X}. See \bold{Examples}.}

    \item{X}{A matrix of predictor variables. The column names of the matrix should at least include the predictor names provided in \code{formula}. All other variables are ignored.}

    \item{object}{A \code{BoundIRT} object obtained with \code{fitBIRT()}.}
    \item{method}{The method to conduct the latent regression. Default is "posterior" which uses the posterior latent variable draws. Other option is "Croon" and "CroonSE" which uses the correction by Croon (2002). See \bold{Details}.}
    \item{nboot}{The number of bootstrap samples for method="Croon". See \bold{Details}.}

  }

\details{
  By default (\code{method="posterior"}), \code{latregBIRT} fits a linear regression model to the posterior latent variable distribution from a bounded continuous IRT model:

  \eqn{\theta=\bold{x\gamma}+\epsilon}

  where \eqn{\bold{x}} is a vector of predictors variables, \eqn{\bold{\gamma}} is a vector of regression parameters, and \eqn{\epsilon} is a vector of residuals. Using the existing draws from the posterior latent variable distribution, \eqn{\tilde{\theta}} in \code{BoundIRT.object}, samples are drawn from the posterior of \eqn{\bold{\gamma}} conditional on \eqn{\tilde{\theta}}. This posterior is normal with its mean being equal to the least square estimate of \eqn{\bold{\gamma}}, and its variance equal to \eqn{V\sigma^2} where \eqn{V} is the inverse of \code{cov(X)}, and \eqn{\sigma^2} is the residual variance which is sampled from it's scaled inverse-chi-square posterior distribution. Note that the posterior of the latent variable is misspecified with respect to the predictor variables. The posterior is however unbiased for the number of items approaching infinity. As most applications of (bounded continuous) IRT models typically involve a limited number of items, the posterior covariance matrix of the latent variable and the predictor variables is adjusted for the nonzero variance in the latent variable posterior. The correction is based on the two-step approach by Croon (2002) in which the factor scores from a linear factor model are estimated in step 1 and used in a regression model in step 2. As such, Croon's method is a statistically valid alternative to fitting the factor model and latent regression model simultaneously. Vermunt (2025) discusses how Croon's method can be generalized to models with heterogenous measurement error like IRT models. \code{latregBIRT} implements this idea by correcting the covariance matrix of the latent variable and the predictor variables for each posterior latent variable draw using the formula from Vermunt (2025). Next, a linear regression is fit to each sample as described above.

For method="Croon" the above correction is applied on the EAP latent variable scores. Drawback is that no standard deviation corrections are available. These are therefore bootstrapped using \code{nboot} resamples.
}
\value{
  \item{output}{A matrix containing the postrior means and standard deviations of the regression slopes for each predictor (if method="posterior") or the regression slope estimates with boostrapped standard errors (if method="Croon").}
  \item{samples}{A matrix containing the samples from the postrior distribution of the regression parameter (if method="posterior") or the regression parameter estimates on the bootstrapped samples (if method="Croon").}
}
\references{

Croon, M. (2002). Using predicted latent scores in general latent structure models. In G. Marcoulides and I. Moustaki (Eds.), \emph{Latent Variable and Latent Structure Models} (pp. 195-224). Lawrence Erlbaum.

Vermunt J.K. (2025). Stepwise estimation of latent variable models: An overview of approaches. \emph{Statistical Modelling}, \bold{25}(6),530-551. \doi{10.1177/1471082X251355693}

}
\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{rBIRT}} simulate data according to a (zero/one inflated) bounded IRT model.
}
\examples{

 # open pre-estimated Beta IRT model on Abasement data (see ?Abasement)
  data(out_beta)

 # simulate a latent regression with 2 covariates

 EAP=out_beta$theta[,1]
 N=length(EAP)
 age=.4*EAP+sqrt(1-.4^2)*rnorm(N)
 ses=.3*EAP+sqrt(1-.3^2)*rnorm(N)

 # conduct latent regression
 predictors=cbind(age,ses)
 latregBIRT(~age+ses,predictors,out_beta)

}
\keyword{models}
\keyword{multivariate}
