Market Regime Detection¶

This document describes the market regime detection system using Hidden Markov Models (HMM) and Gaussian Mixture Models (GMM).

Overview¶

The regime detection module identifies different market states (trending, ranging, volatile, etc.) to enable adaptive trading strategies. It uses unsupervised machine learning to cluster market conditions and detect regime transitions.

Quick Start¶

from src.ml.models.regime_detector import RegimeDetector
import pandas as pd

# Load market data
data = pd.read_csv('btc_hourly.csv')

# Initialize detector
detector = RegimeDetector(
    n_regimes=4,           # Number of market regimes
    method='hmm',          # 'hmm', 'gmm', or 'ensemble'
    feature_set='all'      # 'price', 'volatility', 'volume', or 'all'
)

# Fit detector on historical data
detector.fit(data)

# Predict current regime
regimes = detector.predict(data)

# Get regime probabilities
probabilities = detector.predict_proba(data)

# Get regime information
for regime_id in range(detector.n_regimes):
    info = detector.get_regime_info(regime_id)
    print(f"{info['name']}: {info['characteristics']}")

# Save model
detector.save('models/regime_detector.pkl')

Regime-Aware Trading¶

from src.ml.regime_strategy import RegimeAwareStrategy
from src.backtesting.strategies import SMACrossover, BollingerBands, MeanReversion

# Define strategies for each regime
strategy_map = {
    0: (SMACrossover, {'fast_period': 10, 'slow_period': 30}),    # Trending
    1: (BollingerBands, {'period': 20, 'num_std': 2}),            # Ranging
    2: (MeanReversion, {'lookback': 20}),                         # Volatile
    3: (SMACrossover, {'fast_period': 5, 'slow_period': 15})      # Quiet
}

# Create adaptive strategy
adaptive_strategy = RegimeAwareStrategy(
    bars=bars,
    events_queue=events_queue,
    symbol_list=['BTCUSDT'],
    regime_detector=detector,
    strategy_map=strategy_map,
    min_regime_duration=5,
    transition_smoothing=True
)

# Use in backtesting
engine = EnhancedBacktestEngine(
    symbol_list=['BTCUSDT'],
    strategy_class=RegimeAwareStrategy,
    strategy_params={
        'regime_detector': detector,
        'strategy_map': strategy_map
    },
    # ... other params
)

results = engine.run()

Features¶

Automatic Feature Extraction¶

The detector extracts comprehensive features:

Price Features: - Returns and log returns - Moving averages (SMA, EMA) - Price momentum - Trend strength

Volatility Features: - Historical volatility - ATR (Average True Range) - Bollinger Band width - High-low range

Volume Features: - Volume changes - Volume ratios - OBV (On-Balance Volume) - Volume-price trend

Regime Identification¶

Automatically names regimes based on characteristics: - Bull Trending: Positive trend, medium volatility - Bear Trending: Negative trend, medium volatility - Ranging: Low trend, medium volatility - Volatile Trending: High volatility with trend - Volatile Ranging: High volatility, no trend - Quiet: Low volatility

Detection Methods¶

Hidden Markov Model (HMM)¶

Best for temporal modeling: - Captures regime transitions - Considers sequential dependencies - Good for trending markets

detector = RegimeDetector(method='hmm', n_regimes=3)
detector.fit(data)

Gaussian Mixture Model (GMM)¶

Best for state clustering: - Identifies distinct market states - No temporal assumptions - Good for identifying extremes

detector = RegimeDetector(method='gmm', n_regimes=4)
detector.fit(data)

Ensemble Method¶

Combines both approaches: - More robust predictions - Averaged probabilities - Best overall accuracy

detector = RegimeDetector(method='ensemble', n_regimes=4)
detector.fit(data)

Visualization¶

import matplotlib.pyplot as plt

# Plot regimes over time
fig = detector.plot_regimes(data)
plt.show()

# Analyze regime statistics
stats = adaptive_strategy.get_regime_statistics()
print(f"Regime distribution: {stats['regime_distribution']}")
print(f"Regime transitions: {stats['regime_transitions']}")
print(f"Performance by regime: {stats['performance_by_regime']}")

Best Practices¶

Sufficient Data: Use at least 1000+ samples for reliable detection
Feature Selection: Choose features relevant to your market
Regime Count: Start with 3-4 regimes, adjust based on results
Validation: Verify regimes make intuitive sense
Retraining: Periodically retrain as market characteristics evolve

API Reference¶

See src/ml/models/regime_detector.py and src/ml/regime_strategy.py for complete API documentation.

Examples¶

See notebooks/regime_detection.ipynb for detailed examples.