HMM Regime Terminal

🏗️ Architecture

The project follows a clean three-layer architecture. Each file has a single responsibility and they compose through simple Python imports.

🧠 GMM-HMM Engine

The core model is a 7-state Gaussian Mixture Model Hidden Markov Model (hmmlearn.hmm.GMMHMM) with 2 Gaussian mixture components per state and full covariance matrices. Unlike a plain Gaussian HMM (one Gaussian per state), each GMM-HMM state models observations as a weighted blend of 2 Gaussians — capturing multi-modal within-state behaviour such as a Bull Run that sometimes produces moderate gains and sometimes explosive ones.

Auto-labelling (Option B)

After fitting, each state's mean return is ranked. The top 3 states by mean return are labelled Bull Run, the bottom 2 are labelled Bear/Crash, and the remaining 2 become Neutral/Transition. No manual tuning required.

Why regime labels change with lookback period: The HMM is refit from scratch on every lookback window. Different training data → different emission parameters → different state-to-regime mappings. Additionally, the Viterbi decoder is globally optimal over the full sequence, so adding older bars changes the most-likely path and can alter the label on the final bar. Regime labels are in-sample statistical artefacts, not forward predictions.

🔢 7 Hidden Sub-States NEW

The 7 internal HMM states are ranked by mean return (lowest → highest) and collapsed into three tradeable regimes. The dashboard displays the current sub-state inside the Detected Regime box (e.g. "State 6 · Steady Uptrend") so you can see which specific micro-regime is active within the broader Bull/Bear/Neutral classification.

Sub-state Rank Source FIXED

Sub-state ranks are derived directly from engine.bear_states and engine.bull_states — the sets frozen at fit time — rather than re-sorting by mean return at render time. This guarantees the sub-state is always consistent with the Detected Regime label:

• Ranks 1–2 → always Bear states (bottom 2 by mean return at fit time)
• Ranks 3–4 → always Neutral states (middle 2)
• Ranks 5–7 → always Bull states (top 3)

Previously, an independent re-sort could place a Neutral state at rank 6 (labeled "Steady Uptrend") while the Detected Regime box showed "Neutral/Transition" — a contradiction caused by NaN mean-return values for rare states disturbing Python's sort order.

Sub-state vs. Confirmations

It is possible to be in a Bear/Crash sub-state while all technical confirmations are met. The HMM evaluates the statistical pattern of a sequence of bars; confirmations are point-in-time momentum signals evaluated on the current bar only. A classic scenario: a strong dead-cat bounce causes all confirmations to pass on a single day, while the HMM still classifies the session as Bear because the surrounding sequence of crash bars dominates the pattern. The regime always takes precedence — the strategy exits on Bear regardless of confirmation count.

📐 Engineered Features

Four features are computed from daily OHLCV data and fed into the GMM-HMM. All features are standardised (zero mean, unit variance) before fitting. Outliers beyond ±5σ are clipped to prevent HMM instability. An extra 150 calendar-day warmup is downloaded beyond the user-selected lookback so that SMA-100 and MACD-26 are valid from bar 1. Warmup rows are trimmed before backtesting.

Live Data Pipeline

data_loader.py uses yf.Ticker.history(start=..., no end) instead of yf.download. The key difference: yf.download only returns fully-closed sessions, while Ticker.history without an end date always returns the current live bar. UTC date comparison (datetime.now(timezone.utc).date()) is used to avoid filtering out today's bar when the bar is labeled with a UTC timestamp.

🚦 Market Regimes

The Viterbi algorithm decodes the most likely sequence of hidden states for every bar. Regimes change at most once per day (daily bar). Only the first bar of a new regime triggers a trading action — ongoing regime bars have no new signal.

⚡ Strategy Logic

Transition-Based Entry & Exit

Unlike "always-in" strategies that enter on every Bull bar, this system is transition-triggered: actions fire only on the first bar of a new regime, not on every ongoing bar. The Bear exit requires bear_confirm_days (default 5) consecutive Bear-labeled bars before closing the position — preventing premature exits on single-bar noise. Once Bear is confirmed the position closes immediately (no minimum hold gate).

Equity Mark-to-Market

At every bar, the equity curve is updated with the position's unrealised P&L (leveraged). This happens before the exit check, so the equity curve accurately reflects the floating value through both Bull and Neutral periods.

if position_open:
    bar_return     = (close - entry_price) / entry_price
    unrealised     = equity × leverage × bar_return
    current_equity = equity + unrealised     # updated every bar

✅ Technical Confirmations (10 Checks)

Entry on a Bull Run transition also requires a minimum number of technical confirmations to be True. The default threshold is 3 out of 10, configurable in the dashboard sidebar.

• 1 Positive Momentum (14-period)
• 2 Volatility Expansion (ATR > ATR MA)
• 3 Volume Above 20-period Average
• 4 ADX Trending (> 25)
• 5 Price Above SMA-50
• 6 MACD Histogram Positive
• 7 Stochastic %K > %D
• 8 SMA-20 > SMA-50
• 9 SMA-50 > SMA-100
• 10 RSI > 50

Each confirmation can be individually enabled or disabled in the dashboard sidebar. Disabled confirmations are excluded from the count and shown in grey on the scorecard. The entry threshold slider automatically adjusts to the number of enabled confirmations.

Note: When Regime-Only Mode is active, the entire confirmation gate is bypassed — entry fires immediately on any Bull (or Bear→Neutral) transition. The scorecard remains visible for reference but does not influence trading.

⚡ Regime-Only Mode

Toggling Regime-Only Mode in the sidebar removes the confirmation gate entirely. The strategy trades solely on HMM regime transitions — no technical indicators required. This is useful for benchmarking how much of the edge comes from regime detection alone versus the layered confirmation filters.

Entry Rules (Regime-Only)

Exit Rules (Regime-Only)

All other sidebar controls (leverage, trailing stop, min hold days, look-back period) remain active in Regime-Only Mode. The confirmation scorecard is still displayed for reference but shown with a note that it has no effect on trading.

🛡️ Risk Management

🔍 Parameter Optimizer

Different assets have different volatility profiles. The Parameter Optimizer grid-searches the three most impactful strategy parameters on the asset's own historical data and surfaces the best combination — maximising Total Return.

Parameters Searched

Up to 7 × 10 × 6 = 420 combinations are evaluated. Because the HMM is fitted only once (via _prepare()) and reused across all combinations, the full grid-search typically completes in seconds.

🔮 10-Day Kernel Regression Forecast NEW

Instead of predicting a single price target, the forecast asks: "Given today's feature vector, what distribution of 10-day returns did similar historical situations produce?" A Gaussian kernel regression over past bars yields both an expected path and a ±1σ uncertainty band — more useful for position sizing than a point prediction.

Features (per bar)

Algorithm

Features are z-score normalised using the training portion of the data (all bars except the last 10). For today's feature vector, a Gaussian kernel weight exp(−d²/2h²) is computed against every historical bar, where h is the median pairwise distance (bandwidth heuristic). The kernel-weighted mean and standard deviation of the 10-day forward return paths give:

• Expected path — kernel-weighted mean of historical 10-day forward returns, projected as price levels
• +1σ band — upper confidence bound
• −1σ band — lower confidence bound

Future dates are computed as business days for equities and calendar days for crypto tickers (detected by suffix: -USD, etc.). On the first bar (no prior history), the anchor falls back to using the open price.

Chart Rendering

All three paths are rendered as dashed amber lines anchored to today's close, extending 10 bars into the future. The expected return percentage is shown in the chart legend (e.g. "10-Day Forecast +3.2%"). The ±1σ bands are rendered at reduced opacity (rgba(255,215,64,0.4)) so they don't obscure the price action.

🔍 Stock Screener UPDATED

scanner.py runs the same GMM-HMM pipeline on every constituent of the selected index universe and surfaces the stocks that have most recently entered a Bull Run regime, ranked by a composite entry-quality score.

Supported Index Universes

Entry-Quality Score (0–100)

Dashboard integration

The screener is accessible via the 📡 Backtester / 🔍 Stock Screener radio selector at the top of the sidebar. The index universe is selected from a dropdown (S&P 500, Nasdaq 100, Russell 2000). Results are cached for 2 hours per unique parameter combination.

📡 Dashboard (Streamlit) UPDATED

Running streamlit run dashboard.py launches the full "Regime Terminal" UI. The dashboard caches data for 5 minutes (300s TTL). Any sidebar change triggers an immediate re-run.

Sidebar Controls

Chart Cache Architecture

The TradingView chart function _build_tv_chart_html() uses @st.cache_data(ttl=300). Because Streamlit excludes underscore-prefixed arguments from the cache key, the cache key is explicitly formed from four non-underscore parameters:

• ticker — busts cache on symbol change
• live_key — busts cache when live price changes (e.g. "83412.5")
• regime_key — busts cache when last-bar regime changes (e.g. "2026-03-10_Bull Run")
• prediction_json — serialised kernel forecast; busts cache when forecast changes

This ensures the chart always reflects the current regime from backtester.df, eliminating stale-chart / fresh-signal mismatches.

Day-Change Tooltip Fix FIXED

The OHLC crosshair tooltip previously computed daily change as close − open. It now computes close − previous bar's close, matching the convention used by all professional charting platforms. A prevCloseMap (built from CANDLE_DATA at chart init time) provides O(1) lookup per bar.

🚀 Setup & Run

1 — Install dependencies

pip install -r requirements.txt

2 — (Optional) Run standalone data check

python data_loader.py

3 — (Optional) Run backtest in terminal

python backtester.py

4 — Launch the full dashboard

streamlit run dashboard.py

The dashboard will open in your default browser at http://localhost:8501. On first load it downloads ~365 daily candles (+150 warmup) and fits the GMM-HMM (~10–30 seconds). Subsequent loads use the 5-minute cache.

Requirements

yfinance
hmmlearn
pandas
numpy
scikit-learn
streamlit
plotly
pandas-ta

The price chart uses lightweight-charts v4.2.1 loaded from the unpkg CDN at runtime — no additional pip install required.