% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/lrt_homogeneity_cat.R
\name{test_homogeneity_cat}
\alias{test_homogeneity_cat}
\title{Likelihood ratio test for homogeneity across groups (categorical AD data)}
\usage{
test_homogeneity_cat(
  y = NULL,
  blocks = NULL,
  order = 1,
  n_categories = NULL,
  fit_null = NULL,
  fit_alt = NULL,
  test = c("lrt", "score", "mlrt")
)
}
\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{blocks}{Integer vector of length n_subjects specifying group membership.
Required unless pre-fitted models are provided.}

\item{order}{Antedependence order p. Default is 1.}

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

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

\item{fit_alt}{Optional pre-fitted heterogeneous model (class "cat_fit" with
homogeneous = FALSE). If provided, y is not required for fitting under H1.}

\item{test}{Type of test statistic. One of \code{"lrt"} (default),
\code{"score"}, or \code{"mlrt"}.}
}
\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 homogeneous model (H0)}
\item{fit_alt}{Fitted heterogeneous model (H1)}
\item{n_groups}{Number of groups}
\item{table}{Summary data frame}
}
}
\description{
Tests whether multiple groups share the same transition probability parameters
in a categorical antedependence model.
}
\details{
The null hypothesis is that all G groups share the same transition probability
parameters:
\deqn{H_0: \pi^{(1)} = \pi^{(2)} = \ldots = \pi^{(G)}}

The alternative hypothesis allows each group to have its own parameters.

The degrees of freedom are:
\deqn{df = (G-1) \times k}
where G is the number of groups and k is the number of free parameters per
population.
}
\examples{
\donttest{
# Simulate data with different transition probabilities for two groups
set.seed(123)
marg1 <- list(t1 = c(0.7, 0.3))
marg2 <- list(t1 = c(0.4, 0.6))
trans1 <- list(t2 = matrix(c(0.9, 0.1, 0.2, 0.8), 2, byrow = TRUE),
               t3 = matrix(c(0.9, 0.1, 0.2, 0.8), 2, byrow = TRUE))
trans2 <- list(t2 = matrix(c(0.5, 0.5, 0.5, 0.5), 2, byrow = TRUE),
               t3 = matrix(c(0.5, 0.5, 0.5, 0.5), 2, byrow = TRUE))

y1 <- simulate_cat(100, 3, order = 1, n_categories = 2,
                   marginal = marg1, transition = trans1)
y2 <- simulate_cat(100, 3, order = 1, n_categories = 2,
                   marginal = marg2, transition = trans2)
y <- rbind(y1, y2)
blocks <- c(rep(1, 100), rep(2, 100))

# Test homogeneity
test <- test_homogeneity_cat(y, blocks, order = 1)
print(test)
}

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