> ## Documentation Index
> Fetch the complete documentation index at: https://mathematicalcompany.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Regime Detection
> Real-time market regime classification using a Rust Hidden Markov Model (HMM). Baum-Welch training, Viterbi decoding, and O(N^2) online forward filter.
**Pro Feature.** Requires a Pro or Ultra subscription. [Get started at api.mathematicalcompany.com](https://api.mathematicalcompany.com)
# Markov Regime Detection
Horizon includes a Hidden Markov Model (HMM) with Gaussian emissions, implemented entirely in Rust. It classifies the current market into regimes (e.g., calm vs. volatile) in real time, with a per-tick cost of O(N^2) where N is the number of states (typically 2-3).
Regime detection lets your strategy adapt its behavior to market conditions. Widen spreads in volatile regimes, reduce size in crisis regimes, or disable quoting entirely when the model signals a regime change.
## Overview
Full Baum-Welch EM training, Viterbi decoding, forward-backward smoothing. All in Rust with zero Python overhead.
Per-tick forward filter costs \~9 multiplies for 3 states. Effectively zero latency added to your pipeline.
No pre-trained model? Collect prices during warmup and train inline. Works in both live and backtest.
Drop `hz.markov_regime()` into any pipeline. Injects regime info into `ctx.params` for downstream use.
***
## Quick Start
### Pre-Trained Model
Train offline on historical returns, then use in live trading:
```python theme={null}
import horizon as hz
# 1. Train on historical log returns
model = hz.MarkovRegimeModel(n_states=2)
model.fit(historical_returns, max_iters=100)
# 2. Use in pipeline
hz.run(
name="regime_mm",
markets=["election-winner"],
feeds={"book": hz.PolymarketBook("election-winner")},
pipeline=[
hz.markov_regime(model=model, feed="book"),
my_strategy, # ctx.params["regime"] = 0 (calm) or 1 (volatile)
],
)
```
### Auto-Train Mode
No historical data? Train inline during warmup:
```python theme={null}
hz.run(
pipeline=[
hz.markov_regime(n_states=2, warmup=200, feed="book"),
my_strategy,
],
...
)
```
The model collects 200 price ticks, computes log returns, trains the HMM, then starts classifying. Before training completes, `ctx.params["regime"]` is not set.
***
## MarkovRegimeModel (Rust)
The core HMM class. Use this directly for offline analysis, or pass it to `hz.markov_regime()` for pipeline use.
### Constructor
```python theme={null}
model = hz.MarkovRegimeModel(n_states=2)
```
| Parameter | Type | Default | Description |
| ---------- | ----- | -------- | ----------------------------- |
| `n_states` | `int` | required | Number of hidden states (2-8) |
### fit()
Train the model using Baum-Welch EM on a series of observations (log returns).
```python theme={null}
log_likelihood = model.fit(data, max_iters=100, tol=1e-6)
```
| Parameter | Type | Default | Description |
| ----------- | ------------- | -------- | -------------------------------------------------------- |
| `data` | `list[float]` | required | Observation sequence (log returns). Min 10 observations. |
| `max_iters` | `int` | `100` | Maximum EM iterations |
| `tol` | `float` | `1e-6` | Convergence tolerance on log-likelihood |
Returns the final log-likelihood. States are automatically sorted by variance after training (state 0 = lowest variance = calmest regime).
### decode()
Find the most likely state sequence using the Viterbi algorithm.
```python theme={null}
states = model.decode(data)
# [0, 0, 0, 1, 1, 1, 0, 0, ...]
```
Returns a list of state indices (0 to n\_states-1) for each observation.
### filter\_step()
Online forward filter. Process one observation and update state probabilities. This is the hot path for live trading.
```python theme={null}
probs = model.filter_step(observation)
# [0.85, 0.15] -> 85% probability of state 0
```
Returns a list of state probabilities (sums to 1.0).
### predict()
One-step-ahead prediction: given the current filtered state, what are the probabilities for the next time step?
```python theme={null}
next_probs = model.predict()
# [0.78, 0.22]
```
### smooth()
Full forward-backward smoothing on a batch of observations. More accurate than filtering alone.
```python theme={null}
smoothed = model.smooth(data)
# [[0.9, 0.1], [0.85, 0.15], ...] # one row per observation
```
### Other Methods
| Method | Returns | Description |
| --------------------- | --------------------------- | ------------------------------------------------- |
| `transition_matrix()` | `list[list[float]]` | N x N state transition probabilities |
| `emission_params()` | `list[tuple[float, float]]` | (mean, variance) for each state's Gaussian |
| `current_regime()` | `int` | Most likely current state from the filter |
| `filtered_probs()` | `list[float]` | Current filtered state probabilities |
| `reset_filter()` | `None` | Reset filter to initial state (for re-processing) |
| `n_states()` | `int` | Number of states |
| `is_trained()` | `bool` | Whether fit() has been called |
***
## hz.prices\_to\_returns
Convenience function to convert a price series to log returns.
```python theme={null}
prices = [100.0, 101.0, 99.0, 102.0]
returns = hz.prices_to_returns(prices)
# [0.00995, -0.02005, 0.02985]
```
Handles zero prices gracefully (returns 0.0 for that period). Requires at least 2 prices.
***
## hz.markov\_regime() Pipeline Factory
Creates a pipeline function that classifies the current regime on each tick.
```python theme={null}
fn = hz.markov_regime(
model=None, # Pre-trained model (or None for auto-train)
n_states=2, # States for auto-train (ignored if model provided)
warmup=100, # Ticks before auto-training
feed="book", # Feed name to read prices from
param_name="regime", # Key in ctx.params
)
```
| Parameter | Type | Default | Description |
| ------------ | ------------------- | ---------- | ----------------------------------------------------- |
| `model` | `MarkovRegimeModel` | `None` | Pre-trained model. If None, auto-trains after warmup. |
| `n_states` | `int` | `2` | Number of states (only used if model is None) |
| `warmup` | `int` | `100` | Ticks to collect before auto-training |
| `feed` | `str` | `None` | Feed name to read price from. None = first available. |
| `param_name` | `str` | `"regime"` | Key prefix in ctx.params |
### Injected Parameters
After training and sufficient data, the function injects:
| Key | Type | Description |
| -------------------------------- | ------------- | ------------------------------------------------ |
| `ctx.params["regime"]` | `int` | Most likely state (0 = calm, highest = volatile) |
| `ctx.params["regime_probs"]` | `list[float]` | State probabilities |
| `ctx.params["regime_vol_state"]` | `float` | P(highest-volatility state) |
***
## Examples
### Regime-Adaptive Market Maker
Widen spreads in volatile regimes:
```python theme={null}
import horizon as hz
# Train on historical data
model = hz.MarkovRegimeModel(n_states=2)
model.fit(historical_returns, max_iters=100)
def adaptive_quoter(ctx):
regime = ctx.params.get("regime", 0)
vol_prob = ctx.params.get("regime_vol_state", 0.0)
# Base spread widens with volatility
base_spread = 0.04
spread = base_spread + vol_prob * 0.06 # 4-10 cents
# Reduce size in volatile regime
size = 10.0 if regime == 0 else 3.0
fair = ctx.feed.price
return hz.quotes(fair=fair, spread=spread, size=size)
hz.run(
name="regime_mm",
markets=["election-winner"],
feeds={"book": hz.PolymarketBook("election-winner")},
pipeline=[
hz.markov_regime(model=model, feed="book"),
adaptive_quoter,
],
risk=hz.Risk(max_position=100),
)
```
### Regime-Gated Trading
Only trade in calm regimes:
```python theme={null}
def regime_gate(ctx):
regime = ctx.params.get("regime", 0)
if regime != 0:
return None # Skip quoting in volatile regime
return True # Pass through to next pipeline stage
hz.run(
pipeline=[
hz.markov_regime(n_states=3, warmup=200, feed="book"),
regime_gate,
my_quoter,
],
...
)
```
### Backtest with Regime Detection
```python theme={null}
import horizon as hz
# Train model on historical returns
model = hz.MarkovRegimeModel(n_states=2)
model.fit(historical_returns, max_iters=100)
def regime_quoter(ctx):
regime = ctx.params.get("regime", 0)
spread = 0.06 if regime == 1 else 0.04
return hz.quotes(fair=ctx.feed.price, spread=spread, size=5)
result = hz.backtest(
data=tick_data,
pipeline=[hz.markov_regime(model=model), regime_quoter],
)
print(result.summary())
```
### Offline Analysis
Use the HMM directly for research without a pipeline:
```python theme={null}
import horizon as hz
# Fit model
model = hz.MarkovRegimeModel(n_states=3)
model.fit(returns, max_iters=200)
# Decode most likely state sequence
states = model.decode(returns)
print(f"Regime sequence: {states[:20]}")
# Inspect learned parameters
for i, (mean, var) in enumerate(model.emission_params()):
print(f"State {i}: mean={mean:.6f}, std={var**0.5:.6f}")
# Transition matrix
tm = model.transition_matrix()
for row in tm:
print([f"{p:.3f}" for p in row])
# Smooth for full posterior
smoothed = model.smooth(returns)
# smoothed[t] = [P(state_0|all_data), P(state_1|all_data), ...]
```
***
## Mathematical Background
An HMM models a system that transitions between N hidden states. At each time step:
1. The system transitions from state i to state j with probability A\[i]\[j] (transition matrix)
2. In state j, it emits an observation from a Gaussian distribution N(mu\_j, sigma^2\_j)
The model parameters are: initial state probabilities (pi), transition matrix (A), and emission parameters (mu, sigma^2) for each state.
The Baum-Welch algorithm (a special case of EM) iteratively:
1. **E-step**: Run forward-backward to compute state occupation probabilities given current parameters
2. **M-step**: Re-estimate parameters (A, mu, sigma^2) from the occupation probabilities
Converges to a local maximum of the observation likelihood. Horizon uses quantile-based initialization to improve convergence.
The Viterbi algorithm finds the single most likely state sequence using dynamic programming. Runs in O(T \* N^2) time where T is the sequence length and N is the number of states.
The forward filter recursively computes P(state\_t | observations\_1..t):
```
alpha_t(j) = sum_i [alpha_{t-1}(i) * A[i][j]] * B(j, o_t)
```
Then normalize: `P(state_t = j) = alpha_t(j) / sum(alpha_t)`. This is O(N^2) per time step. For N=3 (typical), that's 9 multiplies plus normalization.
HMMs assume stationary dynamics. If market regimes shift structurally (e.g., new regulation), retrain the model periodically. Use the auto-train mode with a reasonable warmup for adaptive behavior.