API 2.0: Add Support for Load Data and Enhance Location Filtering

[andrewrosemberg]

Overview

This PR extends the ElectricityMarket API by adding support for load data fetching and enhancing existing functions to include location filtering. These changes align with the package's current style and structure while maintaining compatibility with existing functionality.

---

Key Changes

1. New Features

• Load Data Functions:

  • get_load_raw_data: Fetch raw load data.
  • get_load: Fetch processed load data.
  • get_load_forecast_raw_data: Fetch raw load forecast data.
  • get_load_forecast: Fetch processed load forecast data.

• Location Filtering:

  • Introduced locations parameter to filter results by specific nodes or categories (e.g., ZONE, LOAD, GEN, etc.).

2. Enhancements to Existing Functions

• Added locations support to:
  • get_real_time_lmp_raw_data
  • get_real_time_lmp
  • get_day_ahead_lmp_raw_data
  • get_day_ahead_lmp
• Ensured consistency in argument naming and behavior for new and existing functions.

3. New Utility Functions

• real_time_lmp_data_types: Lists available data types for real-time LMP.
• real_time_lmp_frequency: Lists available frequencies for real-time LMP.
• load_data_types: Lists available data types for load data.
• load_forecast_data_types: Lists available data types for load forecasts.

4. Improved Testing

• Added @test_throws for unimplemented functions in MockMarket.
• Comprehensive tests for:
  • get_load
  • get_load_raw_data
  • get_load_forecast
  • get_load_forecast_raw_data
  • Listing data types (data_types) and frequencies (frequency) for LMP and load data.

---

Testing

• Implemented unit tests using MockMarket to validate:
  • Error Handling: Ensures MethodError is thrown for unimplemented methods.
  • Data Filtering: Confirms proper handling of the locations parameter.
  • Date Conversions: Validates conversion between DateTime and ZonedDateTime.
• All tests pass successfully, ensuring robust functionality and error handling.

---

Usage Examples

Fetch Load Data

get_load(
    market, 
    ZonedDateTime(DateTime("2024-01-01T00:00:00"), tz"UTC"),
    ZonedDateTime(DateTime("2024-01-02T00:00:00"), tz"UTC");
    locations=["LOAD_1", "ZONE_2"],
    data_type=:metered
)

List Available Data Types

load_data_types(market)
# Output: [:metered, :preliminary, :estimated]

---

Future Improvements

1. Implement the new methods for actual market data retrieval.
2. Add integration tests for supported markets (MisoMarket, PjmMarket, etc.).
3. Extend documentation with detailed examples and use cases.

---

Checklist

• Code follows existing style and structure.
• All new methods are tested with appropriate error handling.
• Documentation updated for new features.

---

Please review the changes and provide feedback. Suggestions for additional improvements are welcome!

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 97.08%. Comparing base (ad2c876) to head (7280082).

Additional details and impacted files

@@            Coverage Diff             @@
##             main      #34      +/-   ##
==========================================
+ Coverage   96.74%   97.08%   +0.33%     
==========================================
  Files          10       10              
  Lines         246      274      +28     
==========================================
+ Hits          238      266      +28     
  Misses          8        8              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

---

🚨 Try these New Features:

• Flaky Tests Detection - Detect and resolve failed and flaky tests