simulate_sequences: Simulate basic or perturbed state sequences

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

Simulate basic or perturbed state sequences

Description

Simulate basic or perturbed state sequences

Usage

simulate_sequences(
  n = 100L,
  transition = NULL,
  chain_length = 20L,
  initial = NULL,
  states = NULL,
  n_states = 5L,
  state_categories = c("metacognitive", "cognitive"),
  concentration = 1,
  missing_tail = c(0L, 0L),
  stable_transitions = NULL,
  stability_probability = 0.95,
  instability = c("none", "random_jump", "perturb", "unlikely_jump"),
  instability_probability = 0.4,
  perturbation = 0.5,
  unlikely_threshold = 0.1,
  seed = NULL,
  batch = NULL
)

Arguments

n	Number of sequences, defaulting to 100.
transition	Optional transition matrix. When NULL, a random matrix is generated.
chain_length	Maximum sequence length, defaulting to 20.
initial	Initial probabilities or a fixed starting state. When NULL and transition is supplied, every sequence starts in the first state.
states	State labels.
n_states	Number of automatically generated states.
state_categories	Learning-state categories that name a generated state space, defaulting to c("metacognitive", "cognitive"); see learning_state_categories(). NULL labels the states ⁠State 1⁠, ⁠State 2⁠, and so on. Ignored when transition or states names the states.
concentration	Positive Dirichlet concentration used for automatic transition and initial probabilities.
missing_tail	Number or range of trailing positions removed from each sequence.
stable_transitions	Optional two-column data frame named from and to defining preferred transitions.
stability_probability	Probability of following a preferred transition.
instability	Instability mechanism for other transitions.
instability_probability	Probability of applying that mechanism.
perturbation	Multiplicative probability perturbation magnitude.
unlikely_threshold	Maximum probability considered unlikely.
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 columns id, period, and state, one row per observed sequence position. as.data.frame(x, what = ) also returns transitions (from, to, probability, row-stochastic in from), initial_probabilities (state, probability), wide (one row per sequence, columns id, S1, S2, ...), and a one-row settings table.

Examples

result <- simulate_sequences(n = 40, n_states = 4, chain_length = 20, seed = 1)
head(result)
components(result)

# With no arguments, a random transition matrix is drawn and reported.
drawn <- simulate_sequences(seed = 1)
as.data.frame(drawn, what = "transitions")

# Preferred transitions followed with a given probability.
stable <- data.frame(
  from = sprintf("State %d", 1:4),
  to = sprintf("State %d", c(2, 3, 4, 1))
)
head(simulate_sequences(
  n = 40, n_states = 4, chain_length = 20, state_categories = NULL,
  stable_transitions = stable, stability_probability = 0.85, seed = 1
))

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