generalized-timeseries 0.1.21

A package for time series data processing and modeling using ARIMA and GARCH models

Generalized Timeseries

 ▗▄▄▖▗▄▄▄▖▗▖  ▗▖▗▄▄▄▖▗▄▄▖  ▗▄▖ ▗▖   ▗▄▄▄▖▗▄▄▄▄▖▗▄▄▄▖▗▄▄▄ 
▐▌   ▐▌   ▐▛▚▖▐▌▐▌   ▐▌ ▐▌▐▌ ▐▌▐▌     █     ▗▞▘▐▌   ▐▌  █
▐▌▝▜▌▐▛▀▀▘▐▌ ▝▜▌▐▛▀▀▘▐▛▀▚▖▐▛▀▜▌▐▌     █   ▗▞▘  ▐▛▀▀▘▐▌  █
▝▚▄▞▘▐▙▄▄▖▐▌  ▐▌▐▙▄▄▖▐▌ ▐▌▐▌ ▐▌▐▙▄▄▖▗▄█▄▖▐▙▄▄▄▖▐▙▄▄▖▐▙▄▄▀
     ▗▄▄▄▖▗▄▄▄▖▗▖  ▗▖▗▄▄▄▖ ▗▄▄▖▗▄▄▄▖▗▄▄▖ ▗▄▄▄▖▗▄▄▄▖ ▗▄▄▖
       █    █  ▐▛▚▞▜▌▐▌   ▐▌   ▐▌   ▐▌ ▐▌  █  ▐▌   ▐▌
       █    █  ▐▌  ▐▌▐▛▀▀▘ ▝▀▚▖▐▛▀▀▘▐▛▀▚▖  █  ▐▛▀▀▘ ▝▀▚▖
       █  g▄█▄m▐▌  ▐▌▐▙▄▄▖▗▄▄▞▘▐▙▄▄▖▐▌ ▐▌▗▄█▄▖▐▙▄▄▖▗▄▄▞▘

A Python package for timeseries data processing and modeling using ARIMA and GARCH models with both univariate and bivariate capabilities.

TODO: Add C4 diagrams for levels 2-4.

TODO: Reformat README in accordance with other repos.

Architecture and Design Decisions

This package follows best development practices:

• Modular Design: Extracted from a larger thesis replication project to increase maintainability and reusability, published on pypi as package
• Modern Build System: Uses pyproject.toml instead of legacy setup.py for more robust dependency management and packaging. requirements.txt allows users to easily construct venv virtual environments.
• Self-Documenting Code: Extensive docstrings and type hints allow automated documentation generation via Sphinx and publication on readthedocs.io. Variable annotations (myvar: int = 5) are just too visually distracting, and are not used
• Test Coverage: Comprehensive unit tests with pytest with goal of 70%+ code coverage, as indicated by Codecov dashboard
• CI/CD Pipeline: Automated testing, documentation, package publishing and Docker image building
• Cross-Platform: OS-agnostic design with automated testing across OS environments
• Multi-Version Support: Compatible with Python 3.11+ with automated testing across language versions
• Containerization: Docker support with optimized multi-stage builds for reproducible environments
• Code Quality: OOP, DRY, secure programming practices are followed, resulting in high code quality score
• Minimal reinvention: Relies on well-maintained libraries instead of DIY solutions

Features

• Price series generation for single and multiple assets
• Data preprocessing with configurable missing data handling and scaling options
• Stationarity testing and transformation for time series analysis
• ARIMA modeling for time series forecasting
• GARCH modeling for volatility forecasting and risk assessment
• Bivariate GARCH modeling with both Constant Conditional Correlation (CCC) and Dynamic Conditional Correlation (DCC) methods
• EWMA covariance calculation for dynamic correlation analysis
• Portfolio risk assessment using volatility and correlation matrices

Installation

Install from PyPI (recommended):

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install generalized-timeseries

Install from GitHub (latest development version):

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install git+https://github.com/garthmortensen/generalized-timeseries.git

Quick Start

For univariate time series analysis:

python -m generalized_timeseries.examples.example_univariate_garch

For bivariate GARCH analysis (correlation between two assets):

python -m generalized_timeseries.examples.example_bivariate_garch

Docker Support

Run with Docker for isolated environments:

# build the image
docker build -t generalized-timeseries:latest ./

# Run the univariate example
docker run -it generalized-timeseries:latest /app/generalized_timeseries/examples/example_univariate_garch.py

# Run the bivariate example
docker run -it generalized-timeseries:latest /app/generalized_timeseries/examples/example_bivariate_garch.py

# Get into interactive shell
docker run -it --entrypoint /bin/bash generalized-timeseries:latest

Development

Environment Setup

Option 1 (recommended):

mkdir generalized-timeseries
cd generalized-timeseries

# create and activate virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

pip install generalized-timeseries

Option 2

# clone the repository
git clone https://github.com/garthmortensen/generalized-timeseries.git
cd generalized-timeseries

# create and activate virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

pip install -e ".[dev]"

Testing

pytest --cov=generalized_timeseries

Tag & Publish

Iirc, much of the CI/CD actions are gated not behind pushed branches, but pushed tags. It will fail if you don't version += 1

1. Bump version in README.md and pyproject.toml (e.g., v0.1.21)
2. Commit and tag:

   git add pyproject.toml README.md
   git commit -m "version bump"
   git tag v0.1.21
   git push && git push --tags
   

Overall Process

• Triggers: Runs when code is pushed to branches main or dev
• pytest: Validates code across multiple Python versions and OS
• The following are gated behind all tests passing:
  • Building: Creates package distributions and documentation
  • Publishing: Deploys to PyPI, Docker Hub and ReadTheDocs.

Documentation

Full documentation is available at generalized-timeseries.readthedocs.io.

License

Released under the MIT License.

glhf...