v0.13.0

Tooling Library for Notebooks Release Notes

Summary

This release standardizes energy reporting with a new suite of metric definitions, visualization helpers, and a schema-based ColumnMapper for consistent data handling. It also introduces breaking changes to MicrogridConfig to support schema-based loading and adds official support for Python 3.13.

Upgrading

• MicrogridConfig: Switch to schema-based loading of microgrid config files and updates to the config class:
  • Remove unused nested field assets and replace by its contents pv, wind, battery.
  • Make meta and ctype public fields.
  • Require meta.microgrid_id to be set.
• The minimum supported version of matplotlib is now v3.9.2.
• Add src/frequenz/lib/notebooks/reporting/schema_mapping.yaml to your deployment so notebooks can load the canonical column definitions via ColumnMapper.

New Features

• Introduced frequenz.lib.notebooks.reporting.metrics.reporting_metrics with first-class definitions for production excess, battery charging share, grid feed-in, self-consumption, self-consumption share, and inferred consumption; the schema now documents each metric via an implementation tag.
• Added frequenz.lib.notebooks.reporting.utils.helpers.add_energy_flows() (plus supporting helpers) that aggregates raw production/consumption columns and appends the derived flows the reporting notebook needs.
• Published a locale-aware ColumnMapper utility that reads the YAML schema so notebooks can seamlessly move between raw API headers, canonical identifiers, and localized display labels.
• plot_time_series() can auto-pivot long-format inputs, add a desired legend/trace order, and optionally fill selected traces while keeping Plotly colors consistent through a shared palette builder; also defaults to numeric columns only to avoid spurious traces.
• Added reusable long_to_wide() and build_color_map() helpers so notebooks can pivot categorical telemetry and reuse the canonical color scheme without duplicating logic.
• Added create_energy_report_df() to convert raw microgrid exports into timezone-aware, canonical energy-report tables with derived grid/battery KPIs and labeled component columns, letting dashboards bind to a consistent schema without bespoke glue.
• Introduced the reporting_nb_functions toolkit so notebooks can build overview tables, melt component selections, compute energy-mix summaries, and aggregate KPIs (production totals, self-consumption share, grid import peaks) for stakeholder-ready reporting pages.
• Expanded the reporting helper utilities with YAML config loading, German number formatting, timezone conversion, component labeling, energy-report column selection, and robust energy-flow derivations so multiple notebooks can reuse the same preprocessing primitives.
• Published Reporting NB.ipynb example that wires the mapper, helper utilities, and KPI builders together in a ready-to-run reporting notebook.

Bug Fixes

• plot_energy_pie_chart() now accepts the same color_dict overrides as the time-series view, ensuring doughnut slices reuse the canonical colors instead of Plotly’s defaults and keeping legends consistent across charts.

What's Changed

• Reset release notes by @cwasicki in #165
• chore(deps): bump actions/labeler from 5.0.0 to 6.0.1 by @dependabot[bot] in #166
• chore(deps): bump the patch group with 3 updates by @dependabot[bot] in #167
• chore(deps): bump the minor group with 7 updates by @dependabot[bot] in #168
• chore(deps): bump pydoclint from 0.6.11 to 0.7.3 by @dependabot[bot] in #169
• chore(deps): bump pytest-asyncio from 1.1.0 to 1.2.0 by @dependabot[bot] in #172
• chore(deps): update kaleido requirement from <1.1.0,>=0.2.1 to >=0.2.1,<1.2.0 by @dependabot[bot] in #170
• Add support for Python 3.13 by @shsms in #174
• Add prod metrics by @Mohammad-Tayyab-Frequenz in #175
• Switch to schema-based microgrid config loading by @cwasicki in #176
• Update solar notebook to work with updated microgrid config by @cyiallou in #178
• chore(deps-dev): bump pydoclint from 0.7.3 to 0.7.6 by @dependabot[bot] in #185
• chore(deps): bump actions/download-artifact from 5 to 6 by @dependabot[bot] in #179
• chore(deps): bump actions/upload-artifact from 4 to 5 by @dependabot[bot] in #180
• chore(deps-dev): bump nox from 2025.5.1 to 2025.10.16 in the minor group by @dependabot[bot] in #182
• chore(deps): update python-dotenv requirement from <1.2.0,>=0.21.0 to >=0.21.0,<1.3.0 by @dependabot[bot] in #186
• chore(deps): update pyarrow requirement from <22.0.0,>=20.0.0 to >=20.0.0,<23.0.0 by @dependabot[bot] in #184
• chore(deps-dev): bump the patch group with 5 updates by @dependabot[bot] in #181
• fix: missing production and consumption column by @Mohammad-Tayyab-Frequenz in #177
• Update plots reporting by @Mohammad-Tayyab-Frequenz in #189
• feat: add default mapping loader function by @Mohammad-Tayyab-Frequenz in #188
• Add grid import function by @Mohammad-Tayyab-Frequenz in #190
• Add reporting data processing modules by @Mohammad-Tayyab-Frequenz in #191
• fix: update reporting NB by @Mohammad-Tayyab-Frequenz in #192
• docs: update-release-notes by @Mohammad-Tayyab-Frequenz in #193

New Contributors

• @shsms made their first contribution in #174

Full Changelog: v0.12.2...v0.13.0