% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/logLik.FCDCM.R, R/logLik.FCGDINA.R,
%   R/logLik.FCGGUM.R, R/logLik.FCMIRT.R, R/logLik.MGGUM.R, R/logLik.MGPCM.R,
%   R/logLik.MIRT.R, R/logLik.R, R/logLik.TIRT.R
\name{logLik.FCDCM}
\alias{logLik.FCDCM}
\alias{logLik.FCGDINA}
\alias{logLik.FCGGUM}
\alias{logLik.FCMIRT}
\alias{logLik.MGGUM}
\alias{logLik.MGPCM}
\alias{logLik.MIRT}
\alias{logLik-class}
\alias{logLik.TIRT}
\title{Extract Log-Likelihood from Fitted Models}
\usage{
\method{logLik}{FCDCM}(object, theta.low = NULL, theta.up = NULL, L = NULL, ...)

\method{logLik}{FCGDINA}(object, ...)

\method{logLik}{FCGGUM}(object, theta.low = NULL, theta.up = NULL, L = NULL, ...)

\method{logLik}{FCMIRT}(object, theta.low = NULL, theta.up = NULL, L = NULL, ...)

\method{logLik}{MGGUM}(object, theta.low = NULL, theta.up = NULL, L = NULL, ...)

\method{logLik}{MGPCM}(object, theta.low = NULL, theta.up = NULL, L = NULL, ...)

\method{logLik}{MIRT}(object, theta.low = NULL, theta.up = NULL, L = NULL, ...)

\method{logLik}{TIRT}(object, theta.low = NULL, theta.up = NULL, L = NULL, ...)
}
\arguments{
\item{object}{A fitted model object of class \code{"MIRT"},
\code{"MGPCM"}, \code{"MGGUM"}, \code{"FCMIRT"}, \code{"FCDCM"},
\code{"FCGDINA"}, \code{"FCGGUM"}, or \code{"TIRT"}.}

\item{theta.low}{Numeric; lower bound for the quadrature grid on the
latent scale. Used by continuous-trait models; if \code{NULL}, the value
stored in the fitted object's controls is used, falling back to
\code{-6}.}

\item{theta.up}{Numeric; upper bound for the quadrature grid on the latent
scale. Used by continuous-trait models; if \code{NULL}, the value stored
in the fitted object's controls is used, falling back to \code{6}.}

\item{L}{Integer; number of quadrature points per dimension. If
\code{NULL}, the package chooses a dimension-dependent default.}

\item{...}{Additional arguments passed to the method. Currently ignored by
the implemented methods.}
}
\value{
An object of class \code{"logLik"} with attributes:
\itemize{
\item \code{nobs}: number of observations (\eqn{N})
\item \code{df}: number of free parameters
\item \code{theta.norm}: continuous-trait quadrature grid points, when
applicable
\item \code{prob}: model-implied response probabilities at grid points,
when applicable
\item \code{pi}: quadrature weights or FCGDINA class probabilities
\item \code{L}: quadrature grid size used, when applicable
\item \code{prob.class}: FCGDINA class-conditional forced-choice
probabilities, when applicable
}

An object of class \code{"logLik"}: a length-one numeric vector
containing the marginal log-likelihood, with at least attributes
\code{nobs} (sample size) and \code{df} (number of free parameters).
Continuous-trait methods also attach quadrature diagnostics such as
\code{theta.norm}, \code{prob}, \code{pi}, and \code{L}; FCGDINA attaches
latent-class probabilities and class-conditional response probabilities.
}
\description{
Extracts the marginal log-likelihood from a fitted ForceChoice model
object. For continuous-trait IRT models, the log-likelihood is computed
by numerically integrating the joint likelihood of the observed responses
over the latent trait distribution using Cartesian-product normal
quadrature. For FCGDINA, the marginal likelihood is obtained by summing
over the \eqn{2^D} discrete attribute profiles.

For a sample of \eqn{N} independent persons with responses
\eqn{\mathbf{Y}_j}, the marginal log-likelihood is:
\deqn{
  \ell = \sum_{j=1}^{N} \log \int
  P(\mathbf{Y}_j \mid \boldsymbol{\theta})\,
  \phi_D(\boldsymbol{\theta}; \mathbf{0}, \boldsymbol{\Sigma})\,
  d\boldsymbol{\theta},
}
where \eqn{\phi_D(\cdot)} is the \eqn{D}-variate normal density with
correlation matrix \eqn{\boldsymbol{\Sigma}}. The integral is approximated
on a Cartesian-product quadrature grid over \eqn{[-6, 6]^D}.

The continuous-trait quadrature weights are normalized normal densities
computed on the grid points, with the fitted correlation matrix used when
available. FCGDINA instead uses the estimated class-proportion vector
\eqn{\boldsymbol{\pi}} over attribute profiles.

S3 methods for extracting marginal log-likelihoods from fitted
\pkg{ForceChoice} model objects.
}
\details{
For MIRT, MGPCM, MGGUM, FCMIRT, FCGGUM, TIRT, and FCDCM objects, the
likelihood is evaluated by marginalizing over a normal quadrature grid
(and, for FCDCM, over attribute profiles conditional on the higher-order
trait). For FCGDINA objects, the likelihood is evaluated exactly over the
\eqn{2^D} latent attribute profiles.
}
\section{Functions}{
\itemize{
\item \code{logLik(FCDCM)}: FCDCM model: higher-order trait quadrature with exact
marginalization over discrete attribute profiles.

\item \code{logLik(FCGDINA)}: FCGDINA model: marginal forced-choice probabilities over
all \eqn{2^D} attribute profiles.

\item \code{logLik(FCGGUM)}: FCGGUM model: forced-choice unfolding block
probabilities with multivariate normal quadrature.

\item \code{logLik(FCMIRT)}: FCMIRT model: forced-choice block pattern
probabilities with multivariate normal quadrature.

\item \code{logLik(MGGUM)}: MGGUM model: polytomous unfolding responses with
per-item block-structured quadrature evaluation.

\item \code{logLik(MGPCM)}: MGPCM model: polytomous responses integrated over the
fitted multivariate normal latent distribution.

\item \code{logLik(MIRT)}: MIRT model: multivariate normal quadrature over
\eqn{D}-dimensional latent space with Gaussian correlation structure.

\item \code{logLik(TIRT)}: TIRT model: pairwise binary probit probabilities
with multivariate normal quadrature over traits.

}}
\examples{
sim <- sim.data.MIRT(N = 20, I = 6, D = 2, model = "m2pl")
fit <- fit.MIRT(
  sim$response, model = "m2pl", D = 2, method = "iStEM",
  control.method = list(
    vis = FALSE, seed = 123,
    M = 2, B = 2, burnin.maxitr = 2,
    maxitr = 3, eps1 = 10, eps2 = 10,
    estimate.se = FALSE)
)
ll <- logLik(fit, L = 9)
as.numeric(ll)
attr(ll, "df")

}
\seealso{
\code{\link{fit.MIRT}}, \code{\link{get.fit.index}},
\code{\link{good.of.fit}}
}
\keyword{internal}
