% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/em_cat.R
\name{em_cat}
\alias{em_cat}
\title{EM algorithm for categorical AD model estimation}
\usage{
em_cat(
  y,
  order = 1,
  blocks = NULL,
  homogeneous = TRUE,
  n_categories = NULL,
  max_iter = 100,
  tol = 1e-06,
  epsilon = 1e-08,
  safeguard = TRUE,
  verbose = FALSE
)
}
\arguments{
\item{y}{Integer matrix with n_subjects rows and n_time columns. Values are
category codes in \code{1, ..., n_categories}; \code{NA} is allowed.}

\item{order}{Antedependence order. Supported values are \code{0} and
\code{1}. Order \code{2} is not yet implemented in \code{em_cat()}.}

\item{blocks}{Optional block/group vector of length \code{n_subjects}. Any
coding is accepted (e.g., non-sequential integers or factor levels).}

\item{homogeneous}{Logical. If \code{TRUE}, a single parameter set is fitted
across blocks. If \code{FALSE}, separate parameters are fitted by block.}

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

\item{max_iter}{Maximum number of EM iterations.}

\item{tol}{Convergence tolerance on absolute log-likelihood change.}

\item{epsilon}{Small positive constant used for smoothing and numerical
stability.}

\item{safeguard}{Logical; if \code{TRUE}, apply step-halving when an M-step
update decreases observed-data log-likelihood.}

\item{verbose}{Logical; if \code{TRUE}, print EM progress.}
}
\value{
A \code{cat_fit} object with fields matching \code{\link{fit_cat}}.
In EM mode, \code{cell_counts} stores expected counts from the final
E-step, with \code{settings$cell_counts_type = "expected"}.
}
\description{
Fits categorical antedependence models with missing outcomes using the
Expectation-Maximization (EM) algorithm for orders 0 and 1.
}
\details{
For complete data (no missing values), this function defers to
\code{\link{fit_cat}} with closed-form MLEs.

For missing data and orders 0/1, each EM iteration computes expected
sufficient statistics with a forward-backward E-step, then updates
probabilities by normalized expected counts in the M-step.
If \code{safeguard = TRUE}, a step-halving line search is applied to the
M-step update whenever the observed-data likelihood decreases.

A final E-step is run before returning so that \code{log_l}/AIC/BIC and
expected cell counts correspond exactly to the returned parameter values.
}
\examples{
set.seed(1)
y <- simulate_cat(n_subjects = 40, n_time = 5, order = 1, n_categories = 3)
y[sample(length(y), 10)] <- NA
fit <- em_cat(y, order = 1, n_categories = 3, max_iter = 20, tol = 1e-5)
fit$settings$na_action

}
\seealso{
\code{\link{fit_cat}}, \code{\link{logL_cat}}
}
