Add state analysis module for extracting component state transitions and alerts #131
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
github-actions
bot
added
part:docs
There was a problem hiding this comment.
Pull Request Overview
This PR introduces a new state_analysis module for analyzing microgrid component state transitions using the Reporting API. The module provides functionality to extract component state changes, detect alerts, and convert raw state values into human-readable enum names.
Key changes include:
- A new
StateRecordnamed tuple for structured representation of state transitions - Logic to fetch, process, and filter component state data for alert detection
- Support for warnings and error states with configurable filtering
Reviewed Changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.
| File | Description |
|---|---|
src/frequenz/lib/notebooks/reporting/_state_records.py |
Defines the StateRecord named tuple data structure |
src/frequenz/lib/notebooks/reporting/state_analysis.py |
Core implementation with state extraction, filtering, and API client integration |
tests/test_state_analysis.py |
Comprehensive test suite covering state extraction and filtering scenarios |
RELEASE_NOTES.md |
Documents the new state analysis functionality |
| @@ -0,0 +1,34 @@ | |||
| # License: MIT | |||
| # Copyright © 2024 Frequenz Energy-as-a-Service GmbH | |||
There was a problem hiding this comment.
The copyright year should be 2025 to match the current year mentioned in the PR description and other files in the codebase.
Suggested change
| # Copyright © 2024 Frequenz Energy-as-a-Service GmbH | |
| # Copyright © 2025 Frequenz Energy-as-a-Service GmbH |
| @@ -0,0 +1,302 @@ | |||
| # License: MIT | |||
| # Copyright © 2024 Frequenz Energy-as-a-Service GmbH | |||
There was a problem hiding this comment.
The copyright year should be 2025 to match the current year mentioned in the PR description and other files in the codebase.
Suggested change
| # Copyright © 2024 Frequenz Energy-as-a-Service GmbH | |
| # Copyright © 2025 Frequenz Energy-as-a-Service GmbH |
| - Added consistent logger setup across all modules for structured logging and improved observability. Example notebooks updated to demonstrate logger usage. | ||
| - The signature for passing config files MicrogridConfig.load_config() has been changed to accept a path a list of paths and a directory containing the config files. | ||
| - `MicrogridData` class needs to be initialized with a `MicrogridConfig` object instead of a path to config file(s). | ||
| - Added a new `state_analysis` module for detecting and analysing component state transitions and alerts from reporting data. |
There was a problem hiding this comment.
[nitpick] The word 'analysing' should be spelled 'analyzing' to match American English spelling conventions used elsewhere in the codebase.
Suggested change
| - Added a new `state_analysis` module for detecting and analysing component state transitions and alerts from reporting data. | |
| - Added a new `state_analysis` module for detecting and analyzing component state transitions and alerts from reporting data. |
There was a problem hiding this comment.
I usually lean towards British english, thank you.
|
cyiallou
force-pushed
the
feat/add-component-state
branch
from
8a8f3a7 to
8905696
Compare
cwasicki
previously approved these changes
Jul 22, 2025
…and alerts This introduces a new `state_analysis` module for analysing microgrid component state transitions using the Reporting API. It includes: - A `StateRecord` named tuple for structured representation of state changes. - Logic to fetch, extract, and group state/warning/error transitions. - Filtering support for alert detection based on `ComponentStateCode` values. - A private `_resolve_enum_name()` helper for translating raw integer states to descriptive enum names. - Added `# type: ignore[arg-type]` temporarily to ignore `mypy` errors raised for the deprecated `from_proto` method. This will be replaced in the neear future when the reporting and weather clients are updated to the latest `client-common` and `common-api` versions - currently, it will raise all sorts of errors when one tries to use `enum_from_proto` from `client-common` `v0.3.3`. - Tests. Signed-off-by: cyiallou - Costas <[email protected]>
Previously, error and warning metric samples were tracked independently of the component's primary `state` metric. This led to incorrect or unbounded durations when the component transitioned into or out of `ERROR` state. This patch changes the extraction logic to emit error and warning `StateRecords` only while the component is in `ERROR` state, ensuring accurate segmentation. Key changes: - `_extract_state_records()` now groups samples by (microgrid_id, component_id) and collects state, error, and optional warning metrics together. - `_process_sample_group()` was rewritten to iterate over state samples and conditionally emit error and warning transitions aligned with the `ERROR` window. - Introduced an `emit()` helper to simplify record generation. Fixes: - ERROR segments with repeated values never closed - ERROR durations overshot actual ERROR state window Test suite has been updated to reflect the stricter state coordination. Signed-off-by: cyiallou - Costas <[email protected]>
cyiallou
force-pushed
the
feat/add-component-state
branch
from
8905696 to
1236092
Compare
|
rebased to latest main to resolve conflict in release notes. Requires reapproval |
cwasicki
approved these changes
Jul 22, 2025
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR introduces a new
state_analysismodule for analysing microgrid component state transitions using the Reporting API. It includes:StateRecordnamed tuple for structured representation of state changes.ComponentStateCodevalues._resolve_enum_name()helper for translating raw integer states to descriptive enum names.# type: ignore[arg-type]temporarily to ignoremypyerrors raised for the deprecatedfrom_protomethod. This will be replaced in the neear future when the reporting and weather clients are updated to the latestclient-commonandcommon-apiversions - currently, it will raise all sorts of errors when one tries to useenum_from_protofromclient-commonv0.3.3.