% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/lrtest.twoPhaseSPML.R
\name{lrtest}
\alias{lrtest}
\alias{lrtest.twoPhaseSPML}
\title{Likelihood ratio test for \code{twoPhaseSPML} models}
\usage{
lrtest(object, object2, ...)

\method{lrtest}{twoPhaseSPML}(object, object2, ...)
}
\arguments{
\item{object}{a fitted object of class \code{"twoPhaseSPML"} representing
the \emph{smaller} (null / restricted) model.}

\item{object2}{a fitted object of class \code{"twoPhaseSPML"} representing
the \emph{larger} (alternative / unrestricted) model.  The two models
must have been fitted to the same data and with the same \code{miscov},
\code{auxvar}, and \code{family}.  The larger model must have at least
as many parameters as the smaller one.}

\item{\dots}{further arguments, currently unused.}
}
\value{
An object of class \code{"lrtest.twoPhaseSPML"}, which is a
  \code{data.frame} with one row per model and the following columns:
  \describe{
    \item{\code{#Df}}{number of estimated regression coefficients.}
    \item{\code{LogLik}}{maximised log-likelihood.}
    \item{\code{Df}}{change in degrees of freedom relative to the
      previous row (\code{NA} for the first row).}
    \item{\code{Chisq}}{LRT statistic (\code{NA} for the first row).}
    \item{\code{Pr(>Chisq)}}{two-sided \eqn{p}-value from the
      \eqn{\chi^2} distribution (\code{NA} for the first row).}
  }
  The object also carries a \code{"heading"} attribute (a character vector)
  and is printed via \code{\link{print.lrtest.twoPhaseSPML}}.
}
\description{
Compares two nested \code{\link{twoPhaseSPML}} models via a likelihood ratio
test (LRT), mirroring the interface of \code{lmtest::lrtest()}.
}
\details{
The test statistic is
\deqn{LRT = -2 \bigl(\ell_0 - \ell_1\bigr),}
where \eqn{\ell_0} and \eqn{\ell_1} are the maximised log-likelihoods of
the smaller and larger models, respectively.  Under the null hypothesis
that the additional parameters are zero, \eqn{LRT} follows a
\eqn{\chi^2} distribution with degrees of freedom equal to the difference
in the number of estimated regression coefficients between the two models.

The function determines model order automatically: whichever of
\code{object} and \code{object2} has fewer regression coefficients is
treated as the null model, regardless of the order in which they are
supplied.
}
\examples{
data.table::setDTthreads(1)
data <- DataGeneration_TPD(N=200)
set.seed(1)
R <- rep(0L, nrow(data))
R[sample(nrow(data), 175)] <- 1L
data[R == 0L, c("G1")] <- NA

# Null model (no G1)
res_Ho <- twoPhaseSPML(
  formula = Y ~ Z,
  miscov  = ~ G1,
  auxvar  = ~ Z,
  data   = data
)

# Alternative model (with G1)
res_Ha <- twoPhaseSPML(
  formula = Y ~ Z + G1,
  miscov  = ~ G1,
  auxvar  = ~ Z,
  data   = data
)

lrtest(res_Ho, res_Ha)

}
\seealso{
\code{\link{twoPhaseSPML}}, \code{\link{print.lrtest.twoPhaseSPML}}
}
