epiweeks

What it is and what it does

EpiWeeks is a Python package for calculating epidemiological weeks according to two standards: the US CDC's MMWR (Morbidity and Mortality Weekly Report) system and the ISO week numbering system. It provides week-to-date conversions, date-to-week lookups, and iteration over weeks within a year, all validated against CDC reference data. The package is designed for disease surveillance, public health reporting, and epidemiological research where precise week boundaries matter.

The package offers a clean API with Week and Year objects that support comparison, arithmetic (addition and subtraction), and containment checks. It includes full type annotations, comprehensive input validation, and zero runtime dependencies, making it straightforward to integrate into public health applications or data pipelines.

Use it for:

• Generate CDC MMWR week boundaries for disease surveillance reports and epidemiological data aggregation.
• Convert between calendar dates and epidemiological week numbers for public health data analysis.
• Iterate over all weeks in a year to populate surveillance dashboards or export weekly summaries.
• Validate and normalize week-based data from multiple public health sources using a single standard.
• Build time-series analyses aligned to epidemiological weeks rather than calendar months or ISO weeks.

Worth the install?

AI-flagged interpretation of the facts on this page — verify before relying

Calculates epidemiological weeks using US CDC (MMWR) and ISO week numbering systems, with validated accuracy against CDC reference data.

Yes. Active maintenance, zero dependencies, permissive license, production-stable status, and validated accuracy against CDC data make this a reliable choice for any epidemiological or public health application that needs precise week calculations. The low install friction and broad Python version support (3.10–3.14) add to its appeal.

Install

epiweeks on PyPI

pip install epiweeks

uv add epiweeks

poetry add epiweeks

Installing epiweeks

Before you install

Low friction: pure Python wheel with zero runtime dependencies and active maintenance. Last commit 2026-08-06, production-stable status, supports Python 3.10 through 3.14.

License in practice

MIT license (permissive): you may use, modify, and distribute this package freely in commercial and private projects, with minimal restrictions.

Quickstart

from epiweeks import Week, Year

week = Week(2019, 1)
print(week.enddate())
# 2019-01-05

for week in Year(2019).iterweeks():
    print(week.enddate())

Requires Python 3.10 or later.

Verify before relying

• Whether CDC reference validation covers all edge cases or only specific year ranges
• Performance characteristics when iterating large numbers of weeks or years

Package facts

Evidence: epiweeks-2.4.0-py3-none-any.whl

Keywords: calendar, cdc, epidemiology, epiweek, iso, mmwr, public health, surveillance

Tags

More Scientific/Engineering packages