Document forecast data formats and usage examples

[scruysberghs]

Added detailed explanation of forecast data formats, including list and dictionary formats, their requirements, examples, and when to use each format. Included practical examples for Home Assistant integration.

Might be better to remove some of the old examples...

Summary by Sourcery

Document the supported forecast data formats and provide usage guidance with practical examples for Home Assistant integrations.

Documentation:

• Add a new section explaining list and dictionary forecast data formats with their requirements and advantages
• Include detailed JSON/curl examples and internal handling steps for both formats
• Add practical Home Assistant examples for Nordpool in both list and dictionary formats
• Include a summary table recommending which format to use in various scenarios

[sourcery-ai]

Reviewer's Guide

This PR extends the forecasts.md documentation by appending a comprehensive section comparing list and dictionary forecast data formats, detailing their requirements, usage examples (including Home Assistant curl and shell_command snippets), internal processing steps for the dictionary format, guidance on timing and timezones, and a concise recommendation table for choosing the appropriate format in common scenarios.

Flow diagram for internal processing of dictionary forecast format

flowchart TD
    A["User sends dictionary forecast data with timestamps"] --> B["EMHASS parses ISO8601 timestamps"]
    B --> C["Resample data to match optimization_time_step"]
    C --> D["Align values with forecast horizon using nearest-neighbor interpolation"]
    D --> E["Fill missing values (forward-fill, backward-fill)"]
    E --> F["Convert result to list for optimizer"]

Loading

Flow diagram for mixing list and dictionary formats in a single API call

flowchart TD
    A["User prepares API call"] --> B["pv_power_forecast as list"]
    A --> C["load_cost_forecast as dictionary"]
    B --> D["EMHASS processes list format: checks length, order"]
    C --> E["EMHASS processes dictionary format: parses timestamps, resamples"]
    D --> F["Combine processed forecasts for optimization"]
    E --> F

Loading

File-Level Changes

Change	Details	Files
Add forecast data formats comparison section	Introduce “Understanding forecast data formats: List vs Dictionary” header Describe list format requirements and provide a curl example Outline when to use the list format	docs/forecasts.md
Document dictionary format behavior and usage	Explain dictionary format advantages (resampling, alignment, gap-filling, timezone awareness) Define expected JSON structure with timestamps Provide example curl command using dictionary format	docs/forecasts.md
Outline internal processing steps for dictionary format	List parsing of ISO8601 timestamps Resampling to optimization_time_step Alignment with forecast horizon Gap-fill strategy and final list conversion	docs/forecasts.md
Include practical Home Assistant integration examples	Add shell_command example for dictionary format with Nordpool Add shell_command example for list format showing manual slicing and mapping	docs/forecasts.md
Add guidance on timing, timezone, and mixed formats	Define timezone handling rules and fallback behavior Cover data resolution and current period value requirements Explain how to mix list and dictionary formats in one API call	docs/forecasts.md
Provide a summary recommendation table	Create a table mapping common scenarios to recommended formats and reasons	docs/forecasts.md

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

[purcell-lab]

Great work here, anything that simplifies the payload is greatly welcome.

It might also be good to include a definitive list of which payloads accept the dict format:

• pv_power_forecast
• load_power_forecast
• load_cost_forecast
• prod_price_forecast

What about some of the other time series payload data:

thermal_config

• desired_temperatures
• outdoor_temperature_forecast

How are now/current values handled with dict format?
What happens to the time_stamp_rounding (first, middle, last) function?

Do alpha/ beta values still function?
https://emhass.readthedocs.io/en/latest/forecasts.html#now-current-values-in-forecasts

[davidusb-geek]

If this is finished upgrade the draft status to a normal PR

[scruysberghs]

Just to be clear, I had nothing to do with this code change, I just discovered it by accident and was annoyed enough to have Claude change the documentation (as I now realise I wasted too much time working on yaml templates in HA to generate lists with the recent change to 15min price timesteps). Changes are from a commit by @Gruek way back in May c64f5fe

[sourcery-ai]

Hey there - I've reviewed your changes - here's some feedback:

• Consider removing or consolidating redundant list-format examples to reduce duplication and keep the documentation concise.
• This section is very comprehensive but could benefit from a brief table of contents or clearer subsection headings for easier navigation.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- Consider removing or consolidating redundant list-format examples to reduce duplication and keep the documentation concise.
- This section is very comprehensive but could benefit from a brief table of contents or clearer subsection headings for easier navigation.

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}