Development Guide

Setting Up Development Environment

Clone the repository and install in development mode:

git clone https://github.com/yourusername/election-forecasting.git
cd election-forecasting
uv pip install -e .
uv sync

Running Tests

Run the test suite:

make test

Run tests with coverage:

make test-cov

This generates:

Terminal coverage report
HTML coverage report in htmlcov/
XML coverage report for CI tools

Code Quality

Linting

Check code style and formatting:

make lint

Auto-format code:

make format

Quality Check

Run both linting and tests:

make quality-check

Building Documentation

Build the Sphinx documentation:

make docs

The documentation will be built to docs/build/html/. Open docs/build/html/index.html in a browser to view.

Building Distribution Packages

Build source and wheel distributions:

make build

This creates:

dist/election_forecasting-X.Y.Z.tar.gz (source distribution)
dist/election_forecasting-X.Y.Z-py3-none-any.whl (wheel)

Profiling

Profile sequential execution:

make profile        # Profile with 8 forecast dates (sequential)
make profile-view   # Opens snakeviz to view results

Profile parallel execution:

make profile-parallel        # Profile with 8 dates, 4 workers
make profile-view-parallel   # Opens snakeviz for parallel profile

The profiling targets help identify performance bottlenecks and compare sequential vs parallel execution overhead.

Parallel Execution

The forecasting models support parallel execution via the --parallel flag:

# Sequential execution (default)
election-forecast --dates 16

# Parallel execution with 4 workers
election-forecast --dates 16 --parallel 4

How it works:

Parallelization is done at the forecast date level
Each worker processes all states for a single date
Most beneficial with 8+ forecast dates
Maintains reproducibility with --seed argument

Performance characteristics:

Best speedup with many dates (16+) on multi-core machines
Process spawning overhead can dominate for small workloads

Docker Development

Build and test using Docker:

# Build the image
docker build -t election-forecasting .

# Run tests in container
docker run election-forecasting make test

# Run forecasts with volume mounts
docker run -v $(pwd)/predictions:/app/predictions \
           -v $(pwd)/metrics:/app/metrics \
           election-forecasting election-forecast --dates 8

# Use parallel execution in Docker
docker run -v $(pwd)/predictions:/app/predictions \
           -v $(pwd)/metrics:/app/metrics \
           election-forecasting election-forecast --dates 16 --parallel 4

The Docker container includes all dependencies and ensures reproducible builds across platforms.