Add directional wave features and release v1.1.0

[nickreich]

Summary

This PR adds directional wave features to the GBQR model for capturing spatial-temporal patterns in disease spread, and releases version 0.2.0 1.1.0 of the package.

Key Features

Directional Wave Features:

• Distance-weighted spatial features in 8 directions (N, NE, E, SE, S, SW, W, NW)
• Temporal lags for historical patterns (configurable, default: lag1, lag2)
• Optional velocity features for rate of change
• Aggregate feature for overall neighborhood influence
• Fully backwards compatible (disabled by default)

Spatial Utilities:

• New spatial_utils.py module with haversine distance and bearing calculations
• Bundled state centroid data (state_centroids.csv) from US Census Bureau TIGER/Line Shapefiles
• Efficient caching and neighbor precomputation
• Extensible design for county/HSA levels in future

Configuration Example:

model_config.use_directional_waves = True
model_config.wave_directions = ['N', 'NE', 'E', 'SE', 'S', 'SW', 'W', 'NW']
model_config.wave_temporal_lags = [1, 2]
model_config.wave_max_distance_km = 1000

Files Added

Core Implementation:

• src/idmodels/spatial_utils.py - Spatial utilities with distance/bearing calculations
• src/idmodels/data/state_centroids.csv - Geographic coordinates for 50 states + DC + PR
• src/idmodels/data/README.md - Data source documentation

Tests:

• tests/unit/test_spatial_utils.py - 20 unit tests for spatial utilities
• tests/unit/test_directional_wave_features.py - 14 unit tests for feature generation
• tests/integration/test_gbqr_wave_features.py - 7 integration tests for GBQR pipeline

Documentation:

• docs/directional_wave_features.md - Comprehensive user guide with examples

Files Modified

• src/idmodels/preprocess.py - Added create_directional_wave_features() function
• src/idmodels/gbqr.py - Integrated wave features into preprocessing pipeline
• pyproject.toml - Updated package data inclusion
• src/idmodels/__init__.py - Bumped version to 0.2.0
• CHANGELOG.md - Added v0.2.0 release notes

Data Source & Transparency

The state centroids are now bundled as a CSV file rather than hardcoded, providing:

• Transparency: Clear documentation of data source (US Census Bureau)
• Maintainability: Easy updates without touching code
• Extensibility: Simple to add county, HSA, or other geographic levels
• Auditability: Users can inspect coordinate values

Data Accuracy: ~10 meters (4 decimal places), suitable for state-level spatial analysis

Test Results

✅ 45 tests pass including all new directional wave feature tests

• 20 unit tests for spatial utilities
• 14 unit tests for feature generation
• 7 integration tests for GBQR pipeline
• Full backwards compatibility verified

❌ 3 pre-existing failures in SARIX Fourier tests (unrelated to this PR)

Backwards Compatibility

✅ Fully backwards compatible

• Wave features disabled by default (use_directional_waves = False)
• Existing model configurations work without modification
• Graceful handling of missing configuration attributes

Version

Bumped from 0.1.0 → 0.2.0 1.1.0

Documentation

See docs/directional_wave_features.md for:

• Detailed feature explanations
• Configuration parameter reference
• Usage examples and best practices
• Technical implementation details
• Troubleshooting guide

Quick Start

Enable with default settings:

model_config.use_directional_waves = True

Customize for 4 cardinal directions only:

model_config.use_directional_waves = True
model_config.wave_directions = ['N', 'S', 'E', 'W']

Future Enhancements

Potential extensions (not in this PR):

• County and HSA-level coordinate support
• Custom distance weighting functions
• Population-weighted features
• Temporal smoothing

🤖 Generated with Claude Code

[matthewcornell]

After a quick-ish scan, this looks good. Excited to see how models using this perform!

[lshandross]

Had a couple of questions but unless any of them stand out as something to be addressed, I don't want to slow down the development process and getting this merged in