fit_covariate_sequence_hmm: Fit a covariate-dependent categorical hidden Markov model

In gp3sequences: Transparent Analysis of Ordered Categorical Sequences

Fit a covariate-dependent categorical hidden Markov model

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.

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

data	Long-format sequence data.
n_states	Number of latent states.
initial_covariate_cols	Numeric sequence-constant covariates for initial-state probabilities.
transition_covariate_cols	Numeric row-level covariates for transition probabilities.
sequence_id_col, order_col, state_col	Core sequence columns.
symbol_levels	Optional observed-symbol order.
state_names	Optional latent-state names.
emission_probs	Optional starting emission matrix.
max_iter	Maximum EM iterations.
inner_maxit	Maximum BFGS iterations in each multinomial M-step.
tolerance	Relative log-likelihood tolerance.
pseudocount	Emission smoothing count.
ridge	Non-negative coefficient penalty.
seed	Reproducibility seed.
keep_posteriors	Retain final posteriors.

Value

An object of class gp3_covariate_sequence_hmm.

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
)

gp3sequences documentation built on Aug. 23, 2026, 5:10 p.m.