simulate_hmm: Simulate a hidden Markov model

In simulab: Simulates a Wide Variety of Data Shapes, Sizes and Distributions

Simulate a hidden Markov model

Description

Draws an initial hidden state for each sequence from initial, evolves it with transition for chain_length occasions, and emits one observed category per occasion from emission.

Usage

simulate_hmm(
  n,
  transition,
  chain_length,
  emission,
  initial = NULL,
  state_labels = NULL,
  observation_labels = NULL,
  seed = NULL,
  batch = NULL
)

Arguments

n	Number of sequences. A single positive whole number.
transition	Hidden-state transition matrix, or a tidy data frame with columns from, to and probability. Square, with rows indexing the current state and columns the next state; every row must sum to one.
chain_length	Sequence length. A single positive whole number; every sequence has the same length.
emission	Hidden-state-by-observed-category probability matrix, or a tidy data frame with columns state, observation and probability. Rows index the hidden states and must sum to one; columns index the observed categories.
initial	Initial hidden-state probabilities, one per hidden state, summing to one. NULL (the default) starts every sequence in the first hidden state with probability one; supply a vector for a random start.
state_labels, observation_labels	Optional labels, one unique value per hidden state and per observed category. They default to "State 1", "State 2", ... and "Observation 1", "Observation 2", ...
seed	Optional random seed.
batch	Optional single positive whole number. When given, the simulator runs batch times and returns a plain list of batch results, each exactly what the same call without batch returns. With a seed, every dataset gets its own seed drawn from seed, so the whole batch is reproducible; without one the datasets are consecutive draws from the session's random-number stream. The default NULL returns a single result.

Value

A long-form simulab_sim base data.frame with one row per sequence-occasion (n * chain_length rows) and columns id, occasion, state (the true hidden state label) and observation (the emitted category label). Components transitions (columns from, to, probability), emissions (columns state, observation, probability) and initial_probabilities (columns state, probability) hold the generating parameters in tidy form.

Examples

result <- simulate_hmm(
  n = 50,
  transition = matrix(c(0.7, 0.3, 0.4, 0.6), nrow = 2, byrow = TRUE),
  chain_length = 20,
  emission = matrix(c(0.9, 0.1, 0.2, 0.8), nrow = 2, byrow = TRUE),
  seed = 1
)
head(result)
components(result)

simulab documentation built on Oct. 15, 2026, 5:08 p.m.