Behavioral States, Transitions & Synthetic Sequences
BehaviorSim models agent behavior as a sequence of transitions across discrete internal states. Learn how the framework decouples internal behavioral state progression from observable parametric emissions.
1. The Generative Sequence Structure
Unlike standard tabular synthesizers that generate independent, identically distributed (IID) rows, BehaviorSim structures data as temporally coherent trajectories.
In real-world systems—whether financial trading, user engagement, or educational learning—an action at step t strongly depends on the preceding state at step t - 1. BehaviorSim formalizes this sequential dependency by producing structured trajectories indexed by sequence_id and ordered by interaction_id.
2. Behavioral States & Transition Dynamics
Agents occupy discrete states that dictate both their propensity to transition to new states and the probability distributions of their emitted features.
A State represents a domain-neutral discrete cognitive, health, or behavioral phase (for example, Stable, Volatile, or Drawdown in the finance preset).
Transition dynamics govern how an agent migrates between states. At each interaction step, the next state s_{t+1} is sampled conditionally:
Transitions can be defined either through stationary probability matrices or through evaluable TransitionRules that inspect historical aggregations (e.g. cumulative session time or maximum volatility spikes) to trigger state transitions dynamically.
3. Observable Features & Generated Labels
The internal state is latent. What the outside world (and downstream machine learning models) observes are parametric feature emissions.
State-Conditioned Feature Emissions
Each state maps to one or more FeatureDistribution configurations. Supported distributions include Normal, Lognormal, Exponential, Poisson, Bernoulli, and Categorical distributions. An agent in an "Engaged" state emits higher interaction counts than an agent in an "Idle" state.
Outcome Labels & Anomaly Flags
Labels can be derived directly from active states (such as binary churn flags) or computed via threshold checks on continuous emissions (such as a risk_alert triggered when drawdowns exceed a calibrated threshold).
4. Agent Profiles & Deterministic Seeds
Calibrate behavioral heterogeneity across cohorts while maintaining bitwise reproducibility.
Agent Profiles
A Profile represents a distinct agent persona or archetype (for instance, a balanced_investor vs. an aggressive trader). Profiles allow you to assign different initial state priors, transition probabilities, and feature parameter overrides to simulate population heterogeneity.
Seed-Guaranteed Reproducibility
Scientific research demands exact reproducibility. BehaviorSim uses seeded NumPy random generators so that providing an explicit integer seed (e.g. seed=42) guarantees that identical sequence traces, state transitions, and emission values are generated every time.
Ready for the mathematical formulation?
Explore the formal mathematical definitions, transition matrices, and parameter boundaries.