Hidden Regime v1.0.0 Release

calendar Sep 30, 2025 · 5 min read · hidden-regime Python GitHub PyPI  ·
Share on: linkedin copy

I am pleased to announce the release of v1.0.0 of the hidden-regime Python module.

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[1.0.0] - 2025-09-30

Added

  • Complete Documentation Overhaul

    • Rewrote root README.md focused on v1.0.0 capabilities (removed all aspirational content)
    • Created 10 comprehensive module READMEs with accurate API documentation
    • Completely rewrote examples/README.md documenting all 12 working examples
    • Added installation instructions, quick start guides, and learning paths

  • Production-Ready Examples (12 total)

    • Basic examples: 00_basic_regime_detection, 01_real_market_analysis, 02_regime_comparison_analysis
    • Intermediate examples: 03_trading_strategy_demo, 04_multi_stock_comparative_study
    • Advanced examples: 05_advanced_analysis_showcase, improved_features
    • Case study examples: case_study, case_study_basic, case_study_comprehensive, case_study_multi_asset, financial_case_study
    • All examples tested and verified working with documented runtimes (15s-180s)

  • Proper Dependency Management

    • Moved scikit-learn to main dependencies (used for KMeans initialization and metrics)
    • Created visualization optional dependency group (seaborn, plotly, Pillow)
    • Clear separation between core, visualization, dev, and docs dependencies

  • Test Infrastructure

    • Organized test suite with proper markers (slow, network, performance)
    • 177 passing fast tests (100% pass rate)
    • Comprehensive coverage across all modules

Changed

  • Data Validation

    • Relaxed NaN validation threshold from 0% to 10% for practical use with pct_change() calculations
    • More realistic handling of missing data in time series

  • Package Metadata

    • Updated classifier to “Development Status :: 5 - Production/Stable”
    • Enhanced optional dependencies with visualization group

Fixed

  • Test Suite Fixes (5 total)

    • 4 model tests: Removed references to deleted online learning attributes (_current_state_probs, _last_observation, _sufficient_stats)
    • 1 analysis test: Corrected attribute name from indicator_calculator to indicator_analyzer

  • Example Fixes

    • Fixed 5 examples requiring model_component parameter for data-driven regime interpretation
    • Fixed 1 example with incorrect API usage (old DataLoader pattern)
    • All 12 examples now execute successfully

Documentation

  • Module Documentation: Complete README for each of 10 modules (config, data, observations, models, analysis, reporting, pipeline, utils, visualization, financial)
  • API Documentation: Full docstring coverage with examples
  • Examples Guide: Comprehensive examples/README.md with:
    • Runtime estimates for each example
    • Complexity levels (Beginner/Intermediate/Advanced)
    • Learning paths for different user types
    • Command reference for running tests
  • Configuration Guide: Documentation of all config classes and presets

Technical Details

  • Architecture: Pipeline-based (Data → Observation → Model → Analysis → Report)
  • HMM Implementation: Gaussian emissions with Baum-Welch training
  • Financial Regime Types: Bear, Bull, Sideways, Crisis (data-driven classification)
  • Trading Simulation: Regime-based strategies with realistic backtesting
  • Temporal Control: Proper data isolation for V&V backtesting

[Unreleased]

Added

  • Enhanced PyPI packaging with pyproject.toml support
  • Comprehensive CI/CD pipeline with GitHub Actions
  • Performance testing and benchmarking infrastructure
  • Security scanning with Bandit
  • Code quality checks with Black, isort, flake8

Changed

  • Improved package metadata with project URLs and enhanced classifiers
  • Centralized version management in _version.py
  • Enhanced MANIFEST.in for better file inclusion control

Fixed

  • Unit test compatibility issues across Python versions
  • Log-likelihood sign assertions in test suite
  • DataFrame assignment warnings in preprocessing
  • Performance test rate limiting issues

[0.1.0] - 2025-01-XX

Added

  • Complete Data Pipeline

    • Multi-source data loading with yfinance integration
    • Comprehensive 6-layer data validation system
    • Advanced preprocessing with outlier detection and missing value handling
    • Intelligent caching with rate limiting and automatic retry logic
    • Quality scoring system (0.0-1.0 scale) for quantitative data assessment
    • Multi-asset support with timestamp alignment and batch processing

  • Hidden Markov Models (HMM)

    • 3-state regime detection optimized for Bear, Sideways, Bull markets
    • Baum-Welch EM training algorithm with numerical stability enhancements
    • Viterbi algorithm for most likely regime sequence inference
    • Forward-Backward algorithm for state probability computation
    • Real-time regime tracking with online state probability updates
    • Model persistence with save/load functionality (JSON/Pickle formats)

  • Regime Analysis & Interpretation

    • Comprehensive regime analysis with duration statistics
    • Automatic regime interpretation (Bull/Bear/Sideways with volatility levels)
    • Regime transition analysis and timing predictions
    • Performance statistics by regime type

  • Configuration System

    • Flexible configuration classes for data loading, validation, and preprocessing
    • Factory methods for common use cases (market data, high-frequency data)
    • Validation of configuration parameters against data characteristics

  • Error Handling & Exceptions

    • Comprehensive exception hierarchy for different error types
    • Graceful error handling with informative error messages
    • Data quality warnings and validation feedback

  • Testing & Quality Assurance

    • Comprehensive unit test suite (80%+ coverage)
    • Integration tests for end-to-end workflows
    • Performance tests and benchmarking
    • Mock data generation for consistent testing
    • Type hints and static analysis support

  • Examples & Documentation

    • Complete API documentation in models/README.md
    • Practical examples for common use cases
    • Data pipeline demonstrations
    • HMM training and analysis examples
    • Portfolio analysis integration examples

Technical Details

  • Dependencies: numpy, pandas, scipy, matplotlib, yfinance
  • Python Support: 3.8, 3.9, 3.10, 3.11, 3.12
  • Operating Systems: Linux, macOS, Windows
  • Architecture: Modular design with clear separation of concerns
  • Performance: Optimized algorithms with numerical stability enhancements

Package Structure

hidden_regime/
├── config/          # Configuration management
├── data/            # Data loading, validation, preprocessing
├── models/          # HMM implementation and algorithms
├── utils/           # Shared utilities and exceptions
examples/            # Usage examples and demonstrations
tests/               # Comprehensive test suite

Known Limitations

  • Currently supports Gaussian emission models only
  • Online learning capabilities are basic (planned for future releases)
  • Limited to 3-state models by default (configurable up to 6 states)
  • Fat-tailed emission models not yet implemented
  • Duration modeling for regime persistence is planned for v0.2.0

[0.0.1] - 2025-01-XX

Added

  • Initial project structure
  • Basic package configuration
  • Placeholder PyPI package (published as placeholder)

Release Notes

Version 0.1.0 - “Foundation Release”

This is the first production-ready release of Hidden Regime, providing a complete toolkit for market regime detection using Hidden Markov Models. The package includes:

🚀 Production-Ready Components:

  • Robust data pipeline with comprehensive validation
  • Numerically stable HMM implementation
  • Real-time regime detection capabilities
  • Extensive testing and documentation

📊 Proven Performance:

  • Successfully tested on major market indices (SPY, QQQ, etc.)
  • Handles various market conditions and time periods
  • Reliable regime detection with quantified uncertainty

🔧 Developer-Friendly:

  • Clean, well-documented API
  • Comprehensive examples and tutorials
  • Flexible configuration system
  • Extensive error handling

🎯 Target Users:

  • Quantitative analysts and researchers
  • Algorithmic trading developers
  • Financial data scientists
  • Academic researchers in finance

Upgrade Path

This is the first stable release. Future versions will maintain backward compatibility for the public API while adding new features and improvements.

Support

  • Documentation: Available in the models/README.md and inline docstrings
  • Examples: See the examples/ directory for practical usage patterns
  • Issues: Report bugs and feature requests on GitHub
  • Community: Join discussions in GitHub Discussions

Acknowledgments

Special thanks to the open-source community and the contributors who helped make this release possible.