% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/fit_cat.R
\name{fit_cat}
\alias{fit_cat}
\title{Fit categorical antedependence model by maximum likelihood}
\usage{
fit_cat(
  y,
  order = 1,
  blocks = NULL,
  homogeneous = TRUE,
  n_categories = NULL,
  na_action = c("fail", "complete", "marginalize", "em"),
  em_max_iter = 100,
  em_tol = 1e-06,
  em_epsilon = 1e-08,
  em_safeguard = TRUE,
  em_verbose = FALSE
)
}
\arguments{
\item{y}{Integer matrix with n_subjects rows and n_time columns. Each entry
should be a category code from 1 to c, where c is the number of categories.}

\item{order}{Antedependence order p. Must be 0, 1, or 2. Default is 1.}

\item{blocks}{Optional integer vector of length n_subjects specifying group
membership. If NULL, all subjects are treated as one group.}

\item{homogeneous}{Logical. If TRUE (default), parameters are shared across
all groups (blocks are ignored for estimation). If FALSE, separate
transition probabilities are estimated for each group.}

\item{n_categories}{Number of categories. If NULL (default), inferred from
the maximum value in y.}

\item{na_action}{Handling of missing values in \code{y}. One of
\code{"fail"} (default, error if any missing), \code{"complete"}
(drop subjects with any missing values), or \code{"marginalize"}
(maximize observed-data likelihood by integrating over missing outcomes),
or \code{"em"} (use \code{\link{em_cat}} for orders 0 and 1).}

\item{em_max_iter}{Maximum EM iterations used when \code{na_action = "em"}.}

\item{em_tol}{EM convergence tolerance used when \code{na_action = "em"}.}

\item{em_epsilon}{Numerical smoothing constant used when \code{na_action = "em"}.}

\item{em_safeguard}{Logical; if \code{TRUE}, use step-halving safeguard in
\code{\link{em_cat}} when \code{na_action = "em"}.}

\item{em_verbose}{Logical; print EM progress when \code{na_action = "em"}.}
}
\value{
A list of class \code{"cat_fit"} containing:
\item{marginal}{List of marginal/joint probabilities for initial time points}
\item{transition}{List of transition probability arrays for k = p+1 to n}
\item{log_l}{Log-likelihood at MLE}
\item{aic}{Akaike Information Criterion}
\item{bic}{Bayesian Information Criterion}
\item{n_params}{Number of free parameters}
\item{cell_counts}{List of cell counts: observed counts for closed-form fits
(\code{na_action = "fail"/"complete"}), expected counts from the final E-step
for EM fits (\code{na_action = "em"}), and \code{NULL} for
\code{na_action = "marginalize"}}
\item{convergence}{Optimizer convergence code (0 for closed-form solutions)}
\item{settings}{List of model settings}
}
\description{
Computes maximum likelihood estimates for the parameters of an AD(p) model
for categorical longitudinal data. The model is parameterized by transition
probabilities, and MLEs are obtained in closed form.
}
\details{
For AD(p), the model decomposes as:
\deqn{P(Y_1, \ldots, Y_n) = P(Y_1, \ldots, Y_p) \times \prod_{k=p+1}^{n} P(Y_k | Y_{k-p}, \ldots, Y_{k-1})}

MLEs are computed as empirical proportions:
\itemize{
\item Marginal/joint probabilities: count / N
\item Transition probabilities: conditional count / marginal count
}

Empty cells receive probability 0 (if denominator is also 0).

When \code{na_action = "em"}, \code{fit_cat()} dispatches to
\code{\link{em_cat}}. In that case, \code{em_safeguard} controls step-halving
protection against likelihood-decreasing updates, and returned
\code{log_l}/AIC/BIC/\code{cell_counts} are synchronized via a final E-step
under the returned parameters.
For \code{order = 2}, \code{na_action = "em"} is not available and errors
explicitly; use \code{na_action = "marginalize"}.
}
\examples{
\donttest{
# Simulate binary AD(1) data
set.seed(123)
y <- simulate_cat(n_subjects = 100, n_time = 5, order = 1, n_categories = 2)

# Fit model
fit <- fit_cat(y, order = 1)
print(fit)

# Compare orders
fit0 <- fit_cat(y, order = 0)
fit1 <- fit_cat(y, order = 1)
fit2 <- fit_cat(y, order = 2)
c(AIC_0 = fit0$aic, AIC_1 = fit1$aic, AIC_2 = fit2$aic)

# EM fit with missing data
y_miss <- y
y_miss[sample(length(y_miss), size = round(0.15 * length(y_miss)))] <- NA
fit_em <- fit_cat(
  y_miss,
  order = 1,
  na_action = "em",
  em_max_iter = 80,
  em_tol = 1e-6
)
fit_em$settings$n_iter
fit_em$settings$cell_counts_type
}

}
\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.
}
