Metadata-Version: 2.4
Name: epydemics
Version: 0.9.0
Summary: Advanced epidemiological modeling and forecasting using discrete SIRD/SIRDV models with time series analysis
Author-email: Juliho David Castillo Colmenares <juliho.colmenares@gmail.com>
Maintainer-email: Juliho David Castillo Colmenares <juliho.colmenares@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/julihocc/epydemics
Project-URL: Documentation, https://github.com/julihocc/epydemics#readme
Project-URL: Repository, https://github.com/julihocc/epydemics.git
Project-URL: Bug Tracker, https://github.com/julihocc/epydemics/issues
Project-URL: Changelog, https://github.com/julihocc/epydemics/blob/main/CHANGELOG.md
Keywords: epidemiology,modeling,forecasting,sird,time-series,var,monte-carlo,covid,pandemic
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Healthcare Industry
Classifier: Topic :: Scientific/Engineering :: Medical Science Apps.
Classifier: Topic :: Scientific/Engineering :: Mathematics
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.24.0
Requires-Dist: pandas>=2.0.0
Requires-Dist: matplotlib>=3.7.0
Requires-Dist: scipy>=1.10.0
Requires-Dist: statsmodels>=0.14.0
Requires-Dist: scikit-learn>=1.2.0
Requires-Dist: python-box>=7.0.0
Requires-Dist: pytest>=8.4.2
Requires-Dist: pydantic-settings>=2.0.0
Requires-Dist: ipykernel>=6.31.0
Requires-Dist: jupyter>=1.1.1
Requires-Dist: notebook>=7.5.0
Requires-Dist: seaborn>=0.13.2
Requires-Dist: factor-analyzer>=0.5.1
Requires-Dist: pytest-cov>=7.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.0.0; extra == "dev"
Requires-Dist: black>=23.0.0; extra == "dev"
Requires-Dist: flake8>=6.0.0; extra == "dev"
Requires-Dist: mypy>=1.0.0; extra == "dev"
Requires-Dist: pre-commit>=3.0.0; extra == "dev"
Requires-Dist: ipython>=8.0.0; extra == "dev"
Requires-Dist: jupyter>=1.0.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=7.0.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.3.0; extra == "docs"
Requires-Dist: myst-parser>=2.0.0; extra == "docs"
Requires-Dist: sphinxcontrib-napoleon>=0.7; extra == "docs"
Provides-Extra: test
Requires-Dist: pytest>=7.0.0; extra == "test"
Requires-Dist: pytest-cov>=4.0.0; extra == "test"
Requires-Dist: pytest-xdist>=3.0.0; extra == "test"
Requires-Dist: tox>=4.0.0; extra == "test"
Dynamic: license-file

# Epydemics: Forecasting COVID-19 using time series and machine learning

**Version 0.9.0** - Native Multi-Frequency (Daily, Business Day, Weekly, Monthly, Annual)

`epydemics` is a Python library for epidemiological modeling and forecasting. It provides tools for creating, fitting, and evaluating discrete SIRD/SIRDV models with time-dependent parameters. The library is designed to be flexible and extensible, allowing users to easily incorporate their own data and models.

**📖 New Users?** Start with the **[User Guide](docs/USER_GUIDE.md)** to understand when and how to use epydemics.

## Features

-   **Discrete SIRD Model**: A discrete Susceptible-Infected-Recovered-Deceased (SIRD) model with time-dependent parameters.
-   **SIRDV Vaccination Model** (v0.7.0): Extended model including Vaccinated compartment (V) and vaccination rate (δ).
-   **Time Series Forecasting**: Use of VAR (Vector Autoregression) models to forecast epidemic rates with logit transformation.
-   **Multi-Frequency Support** (v0.9.0): Native processing of daily, business day, weekly, monthly, and annual data with automatic detection and handler-based validation (no artificial reindexing).
-   **Temporal Aggregation** (v0.9.0): Frequency-aware aggregation that skips resampling when source and target frequencies match.
-   **Business Day Support** (v0.9.0): Dedicated handler for trading-day calendars (252 days/year) with validated lags and recovery windows.
-   **Data Container**: A convenient class for loading, preprocessing, and storing epidemiological data.
-   **Parallel Simulations**: Multi-core support for faster Monte Carlo simulations (27 scenarios for SIRD, 81 for SIRDV).
-   **Result Caching**: File-based caching to avoid recomputing identical analyses.
-   **Model Evaluation**: Tools for evaluating model performance with MAE, MSE, RMSE, MAPE, SMAPE metrics.
-   **Visualization**: Professional plotting functions for results and forecasts.

> **✅ Native Multi-Frequency**: v0.9.0 processes annual/monthly/weekly/business-day data without artificial daily reindexing. See [User Guide](docs/USER_GUIDE.md#annual-surveillance-data-workaround) for frequency guidance.

## SIRDV Model (New in v0.7.0)

The SIRDV model extends the classical SIRD model by incorporating vaccination:

**Compartments:**
- S: Susceptible
- I: Infected (active cases)
- R: Recovered
- D: Deaths
- V: Vaccinated (new)

**Rates:**
- α: Infection rate
- β: Recovery rate
- γ: Mortality rate
- δ: Vaccination rate (new)

**Key Features:**
- Automatic detection from vaccination data
- 81 simulation scenarios (3⁴ confidence levels)
- Conservation law: N = S + I + R + D + V
- Parallel execution recommended for performance

## Getting Started

To get started with `epydemics`, we recommend following the tutorial in [TUTORIAL.md](TUTORIAL.md).

## Installation

You can install `epydemics` from PyPI:

```bash
pip install epydemics
```

To install the latest development version, you can clone this repository and install it in editable mode:

```bash
git clone https://github.com/julihocc/epydemics.git
cd epydemics
pip install -e .
```

## Documentation

**User Documentation**:
-   **[User Guide](docs/USER_GUIDE.md)**: Complete guide on when to use epydemics, data preparation, and frequency handling
-   **[Tutorial](TUTORIAL.md)**: Step-by-step guide for COVID-19 forecasting
-   **[CHANGELOG.md](CHANGELOG.md)**: Version history and detailed changes

**Developer Documentation**:
-   **[Architecture](ARCHITECTURE.md)**: High-level architecture overview
-   **[Contributing](CONTRIBUTING.md)**: Contribution guidelines and workflow
-   **[CLAUDE.md](CLAUDE.md)**: Developer guide for AI assistants
-   **[Documentation Index](docs/INDEX.md)**: Complete documentation organization and navigation

**Release Documentation**:
-   **[v0.9.0 Release Notes](docs/releases/RELEASE_NOTES_v0.9.0.md)**: Latest release details
-   **[Migration Guide](docs/releases/MIGRATION_GUIDE.md)**: Upgrade from v0.8.0 to v0.9.0
-   **[PyPI Publication Guide](docs/releases/PYPI_PUBLICATION_GUIDE.md)**: Publishing to PyPI

## Further work

Recent additions in v0.9.0:
-   ✅ **Native Multi-Frequency**: Daily, business day, weekly, monthly, annual handlers; no artificial reindexing
-   ✅ **Frequency-Aware Aggregation**: Skip resampling when source and target frequencies match
-   ✅ **Frequency-Aware Seasonality**: Adaptive seasonal detection per frequency
-   ✅ **Business Day Support**: Trading-day defaults (252 days/year, 10-lag VAR, 10-day recovery)

Previous releases (v0.6.1-v0.7.0):
-   ✅ **SIRDV Model Support**: Automatic detection and modeling of vaccination data
-   ✅ **Parallel Simulations**: Multi-core execution for improved performance
-   ✅ **Result Caching**: Optional caching to avoid recomputation
-   ✅ **Enhanced Testing**: Comprehensive test coverage with slow test markers

Future directions (v1.0.0+):

-   **Incidence-First Mode**: Direct modeling of incident cases (not just cumulative)
-   **Importation Modeling**: Handle external case introductions for eliminated diseases
-   **Probabilistic & Scenario Forecasting**: Monte Carlo and intervention comparison workflows
-   **More advanced time series models**: SARIMAX, Prophet, or deep learning approaches
-   **Support for other epidemiological models**: Extend to SEIR, SEIRD, or metapopulation models
-   **Improved visualization**: Interactive dashboards and real-time updating plots

## References

**Allen u.a. 2008** Allen, L.J.S. ; Brauer, F. ; Driessche, P. van den ;
 Bauch, C.T. ; Wu, J. ; Castillo-Chavez, C. ; Earn, D. ; Feng, Z. ;
 Lewis, M.A. ; Li, J. u.a.: Mathematical Epidemiology. Springer Berlin
 Heidelberg, 2008 (Lecture Notes in Mathematics).– URL https://books.
 google.com/books?id=gcP5l1a22rQC.– ISBN 9783540789109

**Andrade u.a. 2021** Andrade, Marinho G. ; Achcar, Jorge A. ; Conce
icc˜ ao, Katiane S. ; Ravishanker, Nalini: Time Series Regression Models
 for COVID-19 Deaths. In: J. Data Sci 19 (2021), Nr. 2, S. 269–292

**Hawas 2020** Hawas, Mohamed: Generated time-series prediction data of
 COVID-19s daily infections in Brazil by using recurrent neural networks. In:
 Data in brief 32 (2020), S. 106175

**Maleki u.a. 2020** Maleki, Mohsen ; Mahmoudi, Mohammad R. ; Wraith,
 Darren ; Pho, Kim-Hung: Time series modelling to forecast the confirmed
 and recovered cases of COVID-19. In: Travel medicine and infectious disease
 37 (2020), S. 101742

**Martcheva 2015** Martcheva, M.: An Introduction to Mathematical Epi
demiology. Springer US, 2015 (Texts in Applied Mathematics).– URL https:
 //books.google.com/books?id=tt7HCgAAQBAJ.– ISBN 9781489976123

**Singh u.a. 2020** Singh, Vijander ; Poonia, Ramesh C. ; Kumar, Sandeep ;
 Dass, Pranav ; Agarwal, Pankaj ; Bhatnagar, Vaibhav ; Raja, Linesh:
 Prediction of COVID-19 coronavirus pandemic based on time series data
 using Support Vector Machine. In: Journal of Discrete Mathematical Sciences
 and Cryptography 23 (2020), Nr. 8, S. 1583–1597

**Wacker und Schluter 2020** Wacker, Benjamin; Schluter, Jan: Time
continuous and time-discrete SIR models revisited: theory and applications.
 In: Advances in Difference Equations 2020 (2020), Nr. 1, S. 1–44.– ISSN
 1687-1847.– URL https://doi.org/10.1186/s13662-020-02907-9
