Epidemiological Weeks Calculation

2.4.0 · active · verified Thu Apr 16

EpiWeeks is a Python package designed for accurate epidemiological week calculations, adhering to both the US CDC (MMWR) and ISO week numbering systems. It provides reliable week calculations, validated against official reference data, making it essential for disease surveillance, public health reporting, and epidemiological research. The library boasts zero runtime dependencies, supports Python versions 3.10 and newer, and is actively maintained with frequent updates.

Common errors

```
TypeError: 'validate' argument must be keyword-only
```
cause Attempting to pass the `validate` argument positionally after v2.4.0.

fix Change positional `validate` argument to a keyword argument. Example: `Week(2023, 1, validate=True)` instead of `Week(2023, 1, True)`.
```
AttributeError: module 'epiweeks' has no attribute 'Week'
```
cause This error can occur in older versions if `epiweeks` was a module and you tried to import `Week` directly, or if there's a circular import issue. In modern versions, it could indicate an incorrect import path if the package structure was misunderstood.

fix Ensure you are using `from epiweeks import Week` (and `Year`). If using an old version where `epiweeks` was a single file, the correct import would likely be `from epiweeks_module_name import Week` or `import epiweeks_module_name; epiweeks_module_name.Week`.
```
SyntaxError: invalid syntax (related to Python version)
```
cause Running `epiweeks` v2.4.0 (or newer) on unsupported Python versions (e.g., Python 3.8 or 3.9).

fix Upgrade your Python environment to version 3.10 or higher. Alternatively, downgrade `epiweeks` to a compatible version for your Python environment (e.g., `pip install epiweeks==2.3.0` for Python 3.10-3.12).

Warnings

breaking Python 3.8 and 3.9 are no longer supported as of v2.4.0. Prior versions dropped support for Python 3.6 and 3.7.
Fix: Upgrade to Python 3.10 or newer. For older Python versions, use an older `epiweeks` release (e.g., v2.3.0 for 3.10+, v2.2.0 for 3.11+).
breaking The `validate` argument in various functions has been changed to a keyword-only argument.
Fix: If you were passing `validate` positionally, you must now pass it as a keyword argument (e.g., `Week(year, week, validate=True)` instead of `Week(year, week, True)`).
breaking Rich comparison operations (e.g., `==`, `<`, `>`) between `Week` objects and non-`Week` objects now correctly return `NotImplemented` instead of potentially raising an error or returning an unexpected boolean value.
Fix: Ensure you are only comparing `Week` objects with other `Week` objects. Explicitly convert other date types to `Week` objects before comparison if needed.
gotcha The project structure changed from a single module to a package in v2.1.3. While `from epiweeks import Week` is the standard, older code might have used `import epiweeks` and accessed `epiweeks.Week`.
Fix: Always use explicit imports like `from epiweeks import Week, Year` for clarity and compatibility.

Install

pip install epiweeks Install with pip

Imports

Week
```
from epiweeks import Week
```
Year
```
from epiweeks import Year
```

Quickstart

Demonstrates how to create `Week` and `Year` objects, convert dates to epiweeks, and iterate through a year's weeks using both CDC and ISO systems.

from datetime import date
from epiweeks import Week, Year

# Create a Week object from year and week number
week_obj = Week(2023, 1)
print(f"Week 2023-01 starts on: {week_obj.startdate()}")
print(f"Week 2023-01 ends on: {week_obj.enddate()}")

# Get the epidemiological week for a specific date
some_date = date(2023, 1, 15)
current_week = Week.fromdate(some_date)
print(f"Date {some_date} is in epiweek: {current_week}")

# Iterate through all weeks in a year
print("First 3 weeks of 2024:")
for i, week in enumerate(Year(2024).iterweeks()):
    if i >= 3: break
    print(f"  {week} ending {week.enddate()}")

# Use ISO system
iso_week = Week.fromdate(date(2024, 1, 1), system='iso')
print(f"Date 2024-01-01 (ISO system): {iso_week} ending {iso_week.enddate()}")

view raw JSON →