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

Version 0.11.1 - Publication-Ready Reporting Tools with ModelReport

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 to understand when and how to use epydemics.

✅ v0.11.1 New: ModelReport class for one-line exports to Markdown, LaTeX tables, and publication-ready 300-600 DPI figures. Automated summary statistics, forecast accuracy evaluation, and model comparison utilities.

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.
• Publication Tools (v0.11.1): ModelReport class for Markdown, LaTeX, and high-DPI figure generation in one call. Model comparison utilities and automated summary statistics.

✅ Native Multi-Frequency: v0.9.0+ processes annual/monthly/weekly/business-day data without artificial daily reindexing. See User Guide for frequency guidance.

✅ Publication-Ready Reports: v0.11.1 includes ModelReport for generating Markdown reports, LaTeX tables, and multi-panel figures. See examples/notebooks/07_reporting_and_publication.ipynb.

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.

Installation

You can install epydemics from PyPI:

pip install epydemics

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

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

Documentation

User Documentation:

• User Guide: Complete guide on when to use epydemics, data preparation, and frequency handling
• Tutorial: Step-by-step guide for COVID-19 forecasting
• CHANGELOG.md: Version history and detailed changes

Developer Documentation:

• Architecture: High-level architecture overview
• Contributing: Contribution guidelines and workflow
• CLAUDE.md: Developer guide for AI assistants
• Documentation Index: Complete documentation organization and navigation

Release Documentation:

• v0.10.0 Release Notes: Latest release details (fractional recovery lag fix)
• v0.9.0 Release Notes: Native multi-frequency support
• Migration Guide: Upgrade from v0.8.0 to v0.9.0
• PyPI Publication Guide: Publishing to PyPI

Further work

Recent additions in v0.10.0:

• ✅ Fractional Recovery Lag: Annual frequency now uses 14/365 years (0.0384) instead of 0, fixing LinAlgError with incidence mode
• ✅ Annual + Incidence Mode: Production-ready native support for annual surveillance data with incident cases
• ✅ Enhanced Testing: 10 new tests for fractional lag validation (421/423 tests passing)

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