hmmlearn deep-dive: a solid HMM baseline, with a look-ahead trap

TL;DR

• What it is: a Python library for unsupervised Hidden Markov Models with a scikit-learn-style API (fit, predict, predict_proba, score, sample, aic, bic).¹
• Verdict: Selective fit. It's a good, tested engine for an HMM regime baseline in research (the SOE backtester and MCI benchmarking). It's not something to wire into live bot gating as-is.
• Two things to know first: the README says it is in limited-maintenance mode,² and predict / predict_proba run over the whole sequence you pass in. On a full history, that leaks future bars into past labels.¹

Evidence

Pinned to default branch main at commit e01a10e (committed 2024-10-31). Evidence was collected anonymously on 2026-10-16.³

Architecture

• Models: GaussianHMM, GMMHMM, CategoricalHMM, MultinomialHMM and PoissonHMM (EM, in hmm.py). There are also VariationalGaussianHMM and VariationalCategoricalHMM (vhmm.py); the changelog calls variational inference provisional.⁶
• Core: base.py holds the EM loop, a ConvergenceMonitor, decoders viterbi and map, and two numerics modes (scaling, log).¹ The forward, backward and Viterbi recursions run in C++ (ext/_hmmc.cpp).
• No online API: there's no partial_fit or step-by-step filtering call. Each prediction re-runs over the array you pass.

Claims checked against the pinned source

1. "predict_proba returns smoothed posteriors." predict_proba calls score_samples (L378-L396), which runs a forward pass and a backward pass over the whole sub-sequence (L253-L271). The probability at bar t therefore uses bars after t.¹
2. "predict is Viterbi over the full sequence." predict returns decode(X) (L358-L376). Decoders are viterbi and map (L17-L18), and both use the whole sequence.¹
3. "Limited maintenance." Stated in the README (L29), and consistent with zero commits in the last 90 days.²⁴
4. "Tested across platforms." The CI matrix covers 3 OSes × 6 CPython versions, and pytest runs inside cibuildwheel (L17-L36).⁷

Verdict

Selective fit. Use it for research and benchmarking. Don't make it a production dependency of MCI or live gating without a wrapper and a maintenance plan.

Roadmap

• Now: use GaussianHMM in SOE research notebooks as an HMM baseline. Always compute causal probabilities (expanding window, keep the last row, or a small forward-filter helper).
• Next: benchmark MCI conditions against HMM states on the same 4H history (see the experiment below).
• Later: if HMM gates prove useful, write a small in-house forward filter (a few dozen lines on top of the fitted startprob_, transmat_ and emission parameters). Live gating then doesn't depend on a library in limited maintenance.
• Borrow without adopting: the scikit-learn-style model interface, the aic / bic model-selection helpers, and the multi-sequence lengths convention for fitting across many symbols.

Bounded experiment

experiment:
  id: hmm-vs-mci-4h-separation
  question: Do MCI conditions separate forward returns and volatility better than a causal 3-state Gaussian HMM?
  data: BTC and ETH 4H OHLC, same history for both labelers
  method: walk-forward; refit the HMM on each training window; filtered (causal) HMM states vs MCI conditions; 1-bar lag
  metric: difference in forward 20-bar return and volatility distributions between labels (effect size), out-of-sample only
  success: MCI shows clearly larger out-of-sample separation than the HMM on both symbols
  stop_if:
    - HMM fails to converge on more than a small share of windows
    - causal HMM states flip so often they are unusable as a gate
    - time box of one working day is used up
  owner: SOE research

Strategy hooks

hooks:
  - id: causal-hmm-gate
    family: regime switching
    idea: Gate any bot with the filtered probability of the high-volatility HMM state.
    markets: [crypto majors, index ETFs]
    timeframes: [4H, 1D]
    data_needed: [OHLC returns]
    complexity: intermediate
    gate: run while P(high-vol | data up to t) is below a threshold
    test: walk-forward with costs; compare to an ungated bot
    success: lower drawdown at similar return after costs
  - id: hmm-state-count-by-bic
    family: ML/AI
    idea: Let BIC pick 2–4 states per market instead of fixing 3.
    markets: [any]
    timeframes: [4H, 1D]
    data_needed: [OHLC returns]
    complexity: beginner
    gate: none; model selection only
    test: compare BIC-selected models across symbols and periods for stability
    success: a stable state count per market

Try it in Trade Holistic

Build a two-regime switch on the 4H chart: call it calm when ATR as a percent of price is below its 50-bar average and stressed when it is above. In calm, take long entries when price closes above the 50 EMA; in stressed, take no new entries and tighten the stop on open trades to 1.5 ATR. Only use values from closed bars.

Add a volatility-spike exit to my long strategy: when ATR as a percent of price jumps above 1.5 times its 50-bar average, take half the position off and move the stop to break-even, then trail the rest with a 3 ATR chandelier stop.

Method and safety

Anonymous access only. Repository text was treated as untrusted data and none of its instructions were followed. No repo code was executed; the review is static, against the pinned commit. Optional viewers for a second look: GitDiagram, Gitingest, GitMCP, GitHub1s.