% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/lrt_order_cat.R
\name{test_order_cat}
\alias{test_order_cat}
\title{Likelihood ratio test for antedependence order (categorical AD data)}
\usage{
test_order_cat(
  y = NULL,
  order_null = 0,
  order_alt = 1,
  blocks = NULL,
  homogeneous = TRUE,
  n_categories = NULL,
  fit_null = NULL,
  fit_alt = NULL,
  test = c("lrt", "score", "mlrt", "wald")
)
}
\arguments{
\item{y}{Integer matrix with n_subjects rows and n_time columns. Each entry
should be a category code from 1 to c. Can be NULL if both fit_null and
fit_alt are provided.}

\item{order_null}{Order under the null hypothesis (default 0).}

\item{order_alt}{Order under the alternative hypothesis (default 1).
Must be greater than order_null.}

\item{blocks}{Optional integer vector of length n_subjects specifying group
membership.}

\item{homogeneous}{Logical. If TRUE (default), parameters are shared across
all groups.}

\item{n_categories}{Number of categories. If NULL, inferred from data.}

\item{fit_null}{Optional pre-fitted model under null hypothesis (class "cat_fit").
If provided, y is not required for fitting under H0.}

\item{fit_alt}{Optional pre-fitted model under alternative hypothesis.
If provided, y is not required for fitting under H1.}

\item{test}{Type of test statistic. One of \code{"lrt"} (default),
\code{"score"}, \code{"mlrt"}, or \code{"wald"}.}
}
\value{
A list of class \code{"cat_lrt"} containing:
\describe{
\item{method}{Inference method used: one of \code{"lrt"}, \code{"score"},
\code{"mlrt"}, or \code{"wald"}.}
\item{lrt_stat}{Likelihood ratio test statistic}
\item{df}{Degrees of freedom}
\item{p_value}{P-value from chi-square distribution}
\item{fit_null}{Fitted model under H0}
\item{fit_alt}{Fitted model under H1}
\item{order_null}{Order under null}
\item{order_alt}{Order under alternative}
\item{table}{Summary data frame}
}
}
\description{
Tests whether a higher-order AD model provides significantly better fit
than a lower-order model for categorical longitudinal data.
}
\details{
The likelihood ratio test statistic is:
\deqn{\lambda = -2[\ell_0 - \ell_1]}
where \eqn{\ell_0} and \eqn{\ell_1} are the maximized log-likelihoods under
the null and alternative hypotheses.

Under H0, \eqn{\lambda} follows a chi-square distribution with degrees of
freedom equal to the difference in the number of free parameters.

For testing AD(p) vs AD(p+1), the degrees of freedom are:
\deqn{df = (c-1)^2 \times c^p \times (n - p - 1)}
where c is the number of categories and n is the number of time points.

If \code{y} contains missing values and models are fit internally, this
function defaults to \code{na_action = "marginalize"} for fitting.
Score- and Wald-based variants currently require complete data.
}
\examples{
\donttest{
# Simulate AD(1) data
set.seed(123)
y <- simulate_cat(200, 6, order = 1, n_categories = 2)

# Test AD(0) vs AD(1)
test_01 <- test_order_cat(y, order_null = 0, order_alt = 1)
print(test_01$table)

# Test AD(1) vs AD(2)
test_12 <- test_order_cat(y, order_null = 1, order_alt = 2)
print(test_12$table)

# Using pre-fitted models
fit0 <- fit_cat(y, order = 0)
fit1 <- fit_cat(y, order = 1)
test_prefitted <- test_order_cat(fit_null = fit0, fit_alt = fit1)
}

}
\references{
Xie, Y. and Zimmerman, D. L. (2013). Antedependence models for nonstationary
categorical longitudinal data with ignorable missingness: likelihood-based
inference. \emph{Statistics in Medicine}, 32, 3274-3289.
}
\seealso{
\code{\link{fit_cat}}, \code{\link{bic_order_cat}}
}
