enum helper refactor

[nick-fournier]

Description

The long awaited ENUM helper for passing human readable enums into the config instead of integers!

Robo summary 🤖
This pull request refactors the way mode and purpose codes are handled throughout the trip-linking pipeline, shifting from using integer codes to using enum labels for greater clarity and maintainability. It introduces a new utility, resolve_enum_labels, to convert enum labels to their corresponding code values, and updates function signatures, documentation, and configuration files to use enum labels instead of raw integer codes. This change improves code readability and reduces the risk of errors related to mismatched or unclear code values.

Key changes include:

Core pipeline and utilities:

• Introduced src/utils/enum_helpers.py with the resolve_enum_labels function, which maps enum labels to their corresponding values using Pydantic model metadata. This utility is now used throughout the trip-linking process.
• Refactored the link_trips, link_trip_ids, and aggregate_linked_trips functions in src/processing/link_trips/link.py to accept and process enum labels (change_mode_enum, transit_mode_enums) instead of integer codes, resolving them to code values internally. Updated all related docstrings and argument names accordingly. [1] [2] [3] [4] [5] [6] [7] [8]

Configuration and documentation:

• Updated YAML config files (projects/bats_2019/config.yaml, projects/bats_2023/config.yaml, and README.md files) to use enum labels (e.g., CHANGE_MODE, FERRY, TRANSIT, LONG_DISTANCE) instead of integer codes for trip linking parameters. [1] [2] [3] [4] [5]
• Revised documentation in src/processing/link_trips/README.md and analysis scripts to reflect the new enum-based parameter names and usage. [1] [2] [3] [4] [5]

Tests and fixtures:

• Updated all test cases and fixtures to use the new change_mode_enum and transit_mode_enums parameters, passing enum labels or values as appropriate. [1] [2] [3] [4] [5] [6]

These changes collectively make the codebase more robust, easier to understand, and less error-prone by standardizing on enum labels for all mode and purpose code references.

Type of Change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update
• Code refactoring
• Performance improvement

Testing

• All existing tests pass
• Added new tests to cover changes
• Manually tested the changes

Checklist

• My code follows the style guidelines of this project (runs ruff check . without errors)
• My code is properly formatted (runs ruff format .)
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• I have added tests that prove my fix is effective or that my feature works
• New and existing unit tests pass locally with my changes
• Any dependent changes have been merged and published

[nick-fournier]

Will prob just merge this in but making a PR for visibility / posterity.