% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/sequence-covariate-hmm.R
\name{fit_covariate_sequence_hmm}
\alias{fit_covariate_sequence_hmm}
\title{Fit a covariate-dependent categorical hidden Markov model}
\usage{
fit_covariate_sequence_hmm(
  data,
  n_states,
  initial_covariate_cols = NULL,
  transition_covariate_cols = NULL,
  sequence_id_col = "sequence_id",
  order_col = "sequence_order",
  state_col = "state",
  symbol_levels = NULL,
  state_names = NULL,
  emission_probs = NULL,
  max_iter = 100L,
  inner_maxit = 100L,
  tolerance = 1e-06,
  pseudocount = 1e-06,
  ridge = 1e-06,
  seed = 1L,
  keep_posteriors = FALSE
)
}
\arguments{
\item{data}{Long-format sequence data.}

\item{n_states}{Number of latent states.}

\item{initial_covariate_cols}{Numeric sequence-constant covariates for
initial-state probabilities.}

\item{transition_covariate_cols}{Numeric row-level covariates for transition
probabilities.}

\item{sequence_id_col, order_col, state_col}{Core sequence columns.}

\item{symbol_levels}{Optional observed-symbol order.}

\item{state_names}{Optional latent-state names.}

\item{emission_probs}{Optional starting emission matrix.}

\item{max_iter}{Maximum EM iterations.}

\item{inner_maxit}{Maximum BFGS iterations in each multinomial M-step.}

\item{tolerance}{Relative log-likelihood tolerance.}

\item{pseudocount}{Emission smoothing count.}

\item{ridge}{Non-negative coefficient penalty.}

\item{seed}{Reproducibility seed.}

\item{keep_posteriors}{Retain final posteriors.}
}
\value{
An object of class \code{gp3_covariate_sequence_hmm}.
}
\description{
Fits a categorical HMM whose initial-state and transition probabilities may
depend on explicitly declared numeric covariates. Multinomial-logit
coefficients are estimated inside the EM algorithm with a small ridge
penalty. Emission probabilities remain time-homogeneous.
}
\examples{
sequences <- data.frame(
  sequence_id = rep(paste0("s", 1:8), each = 5L),
  sequence_order = rep(1:5, times = 8L),
  state = rep(c("A", "B", "C", "B", "A"), times = 8L),
  condition = rep(rep(c(0, 1), each = 4L), each = 5L),
  time_scaled = rep(seq(-1, 1, length.out = 5L), times = 8L)
)
fit_covariate_sequence_hmm(
  sequences, 2L,
  initial_covariate_cols = "condition",
  transition_covariate_cols = c("condition", "time_scaled"),
  max_iter = 3L, inner_maxit = 10L, seed = 1L
)
}
