frequenz-cs-reporting 0.4.4__tar.gz → 0.4.6__tar.gz

{frequenz_cs_reporting-0.4.4 → frequenz_cs_reporting-0.4.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: frequenz-cs-reporting
-Version: 0.4.4
+Version: 0.4.6
 Summary: Streamlit Library for reporting and solar monitoring
 Author-email: Frequenz Energy-as-a-Service GmbH <floss@frequenz.com>
 License-Expression: MIT

frequenz_cs_reporting-0.4.6/RELEASE_NOTES.md

@@ -0,0 +1,18 @@
+# Frequenz CS Reporting Library Release Notes
+
+## Summary
+
+
+## Upgrading
+
+
+## New Features
+
+- Add forecasted grid import cost, grid feed-in revenue, and average day-ahead
+  price KPI cards for MID231.
+- Add a separate battery KPI card section with battery flow metrics.
+
+## Bug Fixes
+
+- Add Battery SOC plot tab only for the applicable cases.
+- Use PSC stack mode for the overview time-series plot.

{frequenz_cs_reporting-0.4.4 → frequenz_cs_reporting-0.4.6}/src/frequenz/cs_reporting/app_pages/reporting.py

@@ -22,7 +22,10 @@ from frequenz.cs_reporting.services.client_factory import (
     get_component_types,
     get_microgrid_config,
 )
-from frequenz.cs_reporting.services.data_service import get_microgrid_data
+from frequenz.cs_reporting.services.data_service import (
+    get_microgrid_data,
+    get_microgrid_soc_data,
+)
 from frequenz.cs_reporting.views.dashboard import build_master_df, render_dashboard
 
 
@@ -206,6 +209,21 @@ def render() -> None:
                 end_date=end_time,
                 resolution=resolution,
             )
+            battery_soc_df = None
+            if "battery" in component_types:
+                try:
+                    fetched_soc_df = get_microgrid_soc_data(
+                        microgrid_id=microgrid_id,
+                        start_date=start_time,
+                        end_date=end_time,
+                        resolution=resolution,
+                    )
+                except Exception as exc:  # pylint: disable=broad-except
+                    st.warning(
+                        f"Batterie-SOC-Daten konnten nicht geladen werden: {exc}"
+                    )
+                else:
+                    battery_soc_df = None if fetched_soc_df.empty else fetched_soc_df
     except Exception as exc:  # pylint: disable=broad-except
         st.error(_format_data_loading_error(exc, microgrid_id))
         st.stop()
@@ -226,12 +244,14 @@ def render() -> None:
         mcfg,
         mapper,
         timezone=timezone,
+        battery_soc_df=battery_soc_df,
     )
     render_dashboard(
         master_df,
         resolution=resolution,
         component_types=component_types,
         mapper=mapper,
+        microgrid_id=microgrid_id,
     )
     _scroll_to_section_if_requested()
 

{frequenz_cs_reporting-0.4.4 → frequenz_cs_reporting-0.4.6}/src/frequenz/cs_reporting/components/tables.py

@@ -19,6 +19,7 @@ _GRID_HEADER_HEIGHT = 40
 _GRID_ROW_HEIGHT = 44
 _GRID_PAGINATION_HEIGHT = 56
 _GRID_BORDER_HEIGHT = 2
+_GRID_TOOLBAR_HEIGHT = 40
 
 
 # pylint: disable=too-many-arguments
@@ -90,39 +91,82 @@ def aggrid_table(
         suppressAutoSize=True,
     )
 
-    # Fit columns on first load
     grid_options = gb.build()
     grid_options["onGridReady"] = JsCode(f"""
         function(params) {{
-            const gridKey = {json.dumps(key_prefix)};
-            const messageType = "cs-reporting-reset-aggrid-filters";
-            window.__csReportingAgGridResetHandlers =
-                window.__csReportingAgGridResetHandlers || {{}};
-
-            const previousHandler =
-                window.__csReportingAgGridResetHandlers[gridKey];
-            if (previousHandler) {{
-                window.removeEventListener("message", previousHandler);
+            const buttonId = {json.dumps(f"{key_prefix}_reset_table_filters")};
+            const toolbarHeight = {_GRID_TOOLBAR_HEIGHT};
+            const existingButton = document.getElementById(buttonId);
+            if (existingButton) {{
+                return;
             }}
 
-            const resetFilters = function() {{
+            const gridRoot = document.querySelector(".ag-root-wrapper");
+            const gridParent = gridRoot ? gridRoot.parentElement : null;
+            if (!gridRoot || !gridParent) {{
+                return;
+            }}
+
+            const currentGridHeight = gridRoot.getBoundingClientRect().height;
+            if (currentGridHeight > toolbarHeight) {{
+                gridRoot.style.height = `${{currentGridHeight - toolbarHeight}}px`;
+            }}
+
+            const toolbar = document.createElement("div");
+            Object.assign(toolbar.style, {{
+                alignItems: "center",
+                backgroundColor: "transparent",
+                boxSizing: "border-box",
+                display: "flex",
+                height: `${{toolbarHeight}}px`,
+                justifyContent: "flex-start",
+                padding: "4px 0 6px 0",
+            }});
+
+            const button = document.createElement("button");
+            button.id = buttonId;
+            button.type = "button";
+            button.textContent = "Filter zurücksetzen";
+            button.title = "Filter der Tabelle zurücksetzen";
+            button.setAttribute("aria-label", "Filter der Tabelle zurücksetzen");
+
+            Object.assign(button.style, {{
+                backgroundColor: "#fff4bf",
+                border: "1px solid #e4c34a",
+                color: "#4f3f00",
+                borderRadius: "6px",
+                cursor: "pointer",
+                fontFamily: "inherit",
+                fontSize: "12px",
+                fontWeight: "600",
+                lineHeight: "1.1",
+                minHeight: "26px",
+                padding: "4px 8px",
+                whiteSpace: "nowrap",
+            }});
+
+            button.addEventListener("mouseenter", function() {{
+                button.style.backgroundColor = "#ffe88a";
+                button.style.borderColor = "#c7a629";
+                button.style.color = "#3f3200";
+            }});
+            button.addEventListener("mouseleave", function() {{
+                button.style.backgroundColor = "#fff4bf";
+                button.style.borderColor = "#e4c34a";
+                button.style.color = "#4f3f00";
+            }});
+
+            button.addEventListener("click", function(event) {{
+                event.preventDefault();
+                event.stopPropagation();
+
                 params.api.setFilterModel(null);
                 params.api.onFilterChanged();
                 params.api.paginationGoToFirstPage();
-            }};
-
-            const handler = function(event) {{
-                if (
-                    event.data &&
-                    event.data.type === messageType &&
-                    event.data.gridKey === gridKey
-                ) {{
-                    resetFilters();
-                }}
-            }};
-
-            window.__csReportingAgGridResetHandlers[gridKey] = handler;
-            window.addEventListener("message", handler);
+            }});
+
+            toolbar.appendChild(button);
+            gridParent.insertBefore(toolbar, gridRoot);
         }}
     """)
 
@@ -160,7 +204,7 @@ def aggrid_table(
         _ = AgGrid(
             df,
             gridOptions=grid_options,
-            height=height,
+            height=height + _GRID_TOOLBAR_HEIGHT,
             theme=theme,
             allow_unsafe_jscode=True,
             update_mode=GridUpdateMode.NO_UPDATE,

{frequenz_cs_reporting-0.4.4 → frequenz_cs_reporting-0.4.6}/src/frequenz/cs_reporting/services/data_service.py

@@ -99,6 +99,43 @@ async def fetch_microgrid_data(
     return df.copy()
 
 
+async def fetch_microgrid_soc_data(
+    microgrid_id: int,
+    start_date: datetime,
+    end_date: datetime,
+    resolution: timedelta,
+    timeout: float = 30.0,
+) -> pd.DataFrame:
+    """Fetch battery SOC for a microgrid in ``[start_date, end_date)``.
+
+    Args:
+        microgrid_id: Identifier for the target microgrid.
+        start_date: Inclusive start date of the query range.
+        end_date: Exclusive end date of the query range.
+        resolution: Resampling period for the returned data.
+        timeout: Request timeout in seconds.
+
+    Returns:
+        Dataframe of battery SOC values. Empty when no SOC data is available.
+    """
+    start_iso, end_iso = validate_range(start_date, end_date)
+    client = get_microgrid_client(microgrid_id)
+
+    coro = client.soc(
+        microgrid_id=microgrid_id,
+        start=start_iso,
+        end=end_iso,
+        resampling_period=resolution,
+        keep_components=False,
+    )
+    with _quiet_expected_component_data_warnings():
+        df = await asyncio.wait_for(coro, timeout)
+
+    if df is None or (hasattr(df, "empty") and df.empty):
+        return pd.DataFrame()
+    return df.copy()
+
+
 # Cached sync wrapper for Streamlit pages
 @st.cache_data(ttl=300, show_spinner=False)
 def get_microgrid_data(
@@ -139,3 +176,41 @@ def get_microgrid_data(
         "get_microgrid_data() called from within an active event loop. "
         "Use `await fetch_microgrid_data(...)` in async contexts."
     )
+
+
+@st.cache_data(ttl=300, show_spinner=False)
+def get_microgrid_soc_data(
+    microgrid_id: int,
+    start_date: datetime,
+    end_date: datetime,
+    resolution: timedelta,
+    timeout: float = 30.0,
+) -> pd.DataFrame:
+    """Sync wrapper for battery SOC data with caching.
+
+    Args:
+        microgrid_id: Identifier for the target microgrid.
+        start_date: Inclusive start date of the query range.
+        end_date: Exclusive end date of the query range.
+        resolution: Resampling period for the returned data.
+        timeout: Request timeout in seconds.
+
+    Returns:
+        Dataframe of battery SOC values. Empty when no SOC data is available.
+
+    Raises:
+        RuntimeError: If invoked from within an active event loop instead of
+            using the async ``fetch_microgrid_soc_data``.
+    """
+    try:
+        asyncio.get_running_loop()
+    except RuntimeError:
+        return asyncio.run(
+            fetch_microgrid_soc_data(
+                microgrid_id, start_date, end_date, resolution, timeout=timeout
+            )
+        )
+    raise RuntimeError(
+        "get_microgrid_soc_data() called from within an active event loop. "
+        "Use `await fetch_microgrid_soc_data(...)` in async contexts."
+    )

{frequenz_cs_reporting-0.4.4 → frequenz_cs_reporting-0.4.6}/src/frequenz/cs_reporting/styles/kpi.css

@@ -24,6 +24,62 @@
     color: #4a5568;
     margin: 0;
 }
+.kpi-section-warning {
+    position: relative;
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: 24px;
+    height: 24px;
+    margin-left: 2px;
+    border: 1px solid #facc15;
+    border-radius: 6px;
+    background: #fef9c3;
+    color: #854d0e;
+    cursor: help;
+    flex: 0 0 auto;
+}
+.kpi-section-warning:hover,
+.kpi-section-warning:focus {
+    background: #fde68a;
+    outline: 2px solid rgba(250, 204, 21, 0.35);
+    outline-offset: 1px;
+}
+.kpi-section-warning__icon {
+    color: #ca8a04;
+    font-size: 0.82rem;
+    line-height: 1;
+}
+.kpi-section-warning__tooltip {
+    position: absolute;
+    top: calc(100% + 8px);
+    left: 0;
+    z-index: 10;
+    width: max-content;
+    max-width: 240px;
+    padding: 8px 10px;
+    border: 1px solid #facc15;
+    border-radius: 6px;
+    background: #422006;
+    box-shadow: 0 8px 22px rgba(15,41,74,0.18);
+    color: #fef9c3;
+    font-size: 0.72rem;
+    font-weight: 600;
+    line-height: 1.3;
+    text-align: left;
+    text-transform: none;
+    letter-spacing: 0;
+    white-space: normal;
+    opacity: 0;
+    pointer-events: none;
+    transform: translateY(-3px);
+    transition: opacity 0.15s ease, transform 0.15s ease;
+}
+.kpi-section-warning:hover .kpi-section-warning__tooltip,
+.kpi-section-warning:focus .kpi-section-warning__tooltip {
+    opacity: 1;
+    transform: translateY(0);
+}
 
 /* ── Individual KPI card ── */
 .kpi-card {

{frequenz_cs_reporting-0.4.4 → frequenz_cs_reporting-0.4.6}/src/frequenz/cs_reporting/views/dashboard.py

@@ -56,6 +56,25 @@ def _section_divider(label: str = "", badge: str = "") -> None:
         )
 
 
+def _numeric_metric(metrics: dict[str, float | str | None], key: str) -> float | None:
+    """Return a metric value as a float when it is numeric."""
+    value = metrics.get(key)
+    if isinstance(value, (int, float)):
+        return float(value)
+    return None
+
+
+def _average_price_ct_per_kwh(
+    metrics: dict[str, float | str | None], value_key: str, energy_key: str
+) -> float | None:
+    """Calculate an average price in ct/kWh from euro and kWh metric values."""
+    value = _numeric_metric(metrics, value_key)
+    energy = _numeric_metric(metrics, energy_key)
+    if value is None or energy is None or energy == 0.0:
+        return None
+    return (value * 100) / energy
+
+
 @st.cache_data(show_spinner="Preparing analysis tables…")
 def _build_tables(
     master_df: pd.DataFrame,
@@ -91,7 +110,13 @@ def _build_tables(
         is automatically invalidated when any input parameters change.
     """
     power_table = compute_energy_summary(master_df, resolution)
-    metrics = aggregate_metrics(master_df, resolution)
+    metrics = aggregate_metrics(master_df, resolution, price_column="day_ahead_price")
+    metrics["average_da_price_grid_import"] = _average_price_ct_per_kwh(
+        metrics, "grid_import_cost_sum", "grid_consumption_sum"
+    )
+    metrics["average_da_price_grid_feed_in"] = _average_price_ct_per_kwh(
+        metrics, "grid_feed_in_revenue_sum", "grid_feed_in_sum"
+    )
 
     # Build component analyses using configuration
     analyses = {
@@ -105,12 +130,6 @@ def _build_tables(
     }
 
     overview_df = build_overview_df(master_df, component_types)
-    if "day_ahead_price" in master_df.columns and "timestamp" in overview_df.columns:
-        overview_df = overview_df.merge(
-            master_df[["timestamp", "day_ahead_price"]],
-            on="timestamp",
-            how="left",
-        )
 
     return {
         "power_table": power_table,
@@ -124,12 +143,14 @@ def _build_tables(
     }
 
 
+# pylint: disable=too-many-arguments, too-many-positional-arguments
 def build_master_df(
     raw_df: pd.DataFrame,
     component_types: Iterable[str],
     mcfg: Any,
     mapper: ColumnMapper,
     timezone: str = "Europe/Berlin",
+    battery_soc_df: pd.DataFrame | None = None,
 ) -> pd.DataFrame:
     """Transform raw microgrid data into master analysis dataframe.
 
@@ -146,6 +167,7 @@ def build_master_df(
             site-specific settings.
         mapper: Column name mapper for converting internal names to display names.
         timezone: Timezone name to use for the report timestamps.
+        battery_soc_df: Optional battery SOC dataframe to merge into the report.
 
     Returns:
         Master dataframe with processed and aggregated component data, ready for
@@ -171,6 +193,7 @@ def build_master_df(
         tz_name=timezone,
         assume_tz="UTC",
         component_display_names=component_display_names,
+        battery_soc_df=battery_soc_df,
     )
     try:
         master_df = merge_day_ahead_prices(
@@ -187,6 +210,7 @@ def render_dashboard(
     resolution: timedelta,
     component_types: Iterable[str],
     mapper: ColumnMapper,
+    microgrid_id: int,
 ) -> None:
     """Render the complete microgrid reporting dashboard.
 
@@ -202,6 +226,7 @@ def render_dashboard(
         component_types: List of component types present in the microgrid for
             dynamic tab generation.
         mapper: Column name mapper for display name standardization.
+        microgrid_id: Identifier of the selected microgrid.
 
     Returns:
         Renders Streamlit components directly to the app interface.
@@ -214,11 +239,11 @@ def render_dashboard(
 
     # --- Overview section---
     _section_divider("Übersicht", "KPIs")
-    sections.render_summary_boxes(tables["metrics"], component_types)
+    sections.render_summary_boxes(tables["metrics"], component_types, microgrid_id)
 
     # --- Plots section---
     _section_divider("Diagramme & Zeitreihen")
-    sections.render_plots_tabs(tables, mapper)
+    sections.render_plots_tabs(tables, mapper, component_types)
 
     # --- Tables section---
     st.markdown('<div id="data-export-section"></div>', unsafe_allow_html=True)

{frequenz_cs_reporting-0.4.4 → frequenz_cs_reporting-0.4.6}/src/frequenz/cs_reporting/views/metric_renderers.py

@@ -26,6 +26,7 @@ _SECTION_ACCENTS: dict[str, str] = {
     "Netzkennzahlen": "#3b82f6",  # blue  – grid
     "(Eigen-)Erzeugungskennzahlen": "#10b981",  # green – generation
     "Verbrauchskennzahlen": "#f59e0b",  # amber – consumption
+    "Batteriekennzahlen": "#14b8a6",  # teal – battery
     "Bilanzkennzahlen": "#8b5cf6",  # purple – balance ratios
 }
 
@@ -33,6 +34,7 @@ _SECTION_ICONS: dict[str, str] = {
     "Netzkennzahlen": "⚡",
     "(Eigen-)Erzeugungskennzahlen": "☀",
     "Verbrauchskennzahlen": "📊",
+    "Batteriekennzahlen": "🔋",
     "Bilanzkennzahlen": "⚖",
 }
 
@@ -47,13 +49,44 @@ def _peak_label(metrics: dict[str, object]) -> str:
     return f"Lastspitze (kW) — {metrics.get('peak_date')}"
 
 
+_INVOICING_WARNING = (
+    "Die dargestellten Preise und Daten basieren auf einer Prognose eigener "
+    "gemessener Werte und entsprechen nicht den offiziellen Daten des "
+    "Verteilernetzbetreibers. Für Abrechnungen sind ausschließlich die "
+    "Netzbetreiber-Daten maßgeblich, daher sind Abweichungen zu Rechnungswerten "
+    "möglich."
+)
+
+
 SECTION_SPECS: list[dict[str, Any]] = [
     {
         "title": "Netzkennzahlen",
+        "warning": _INVOICING_WARNING,
         "boxes": [
             {"label": "Netzbezug (kWh)", "key": "grid_consumption_sum"},
             {"label": "Netzeinspeisung (kWh)", "key": "grid_feed_in_sum"},
             {"label_fn": _peak_label, "key": "peak"},
+            {
+                "label": "Prognostizierte Netzbezugskosten (€)",
+                "key": "grid_import_cost_sum",
+                "microgrid_ids": {231},
+            },
+            {
+                "label": "Prognostizierte Einspeiseerloese (€)",
+                "key": "grid_feed_in_revenue_sum",
+                "microgrid_ids": {231},
+            },
+            {"label": "", "key": None, "microgrid_ids": {231}},
+            {
+                "label": "Prognostizierter Preis (ct/kWh)",
+                "key": "average_da_price_grid_import",
+                "microgrid_ids": {231},
+            },
+            {
+                "label": "Prognostizierter Preis (ct/kWh)",
+                "key": "average_da_price_grid_feed_in",
+                "microgrid_ids": {231},
+            },
         ],
     },
     {
@@ -85,6 +118,33 @@ SECTION_SPECS: list[dict[str, Any]] = [
             {"label": "Eigenverbrauch (kWh)", "key": "prod_self_consumption_sum"},
         ],
     },
+    {
+        "title": "Batteriekennzahlen",
+        "per_row": 3,
+        "boxes": [
+            {
+                "label": "Erzeugung zu Batterie (kWh)",
+                "key": "production_to_battery_sum",
+                "component_type": "battery",
+            },
+            {
+                "label": "Netz zu Batterie (kWh)",
+                "key": "grid_to_battery_sum",
+                "component_type": "battery",
+            },
+            {"label": "", "key": None},
+            {
+                "label": "Batterie zu Netz (kWh)",
+                "key": "battery_to_grid_sum",
+                "component_type": "battery",
+            },
+            {
+                "label": "Batterie zu Verbrauch (kWh)",
+                "key": "battery_to_consumption_sum",
+                "component_type": "battery",
+            },
+        ],
+    },
     {
         "title": "Bilanzkennzahlen",
         "per_row": 3,
@@ -197,9 +257,11 @@ def _build_consumption_breakdown(metrics: dict[str, Any]) -> dict[str, float | N
     return {k: (float(v) if v is not None else 0.0) for k, v in values.items()}
 
 
+# pylint: disable=too-many-locals
 def render_summary_boxes(
     metrics: dict[str, Any],
     component_types: Iterable[str] | None = None,
+    microgrid_id: int | None = None,
 ) -> None:
     """Render overview metrics grouped into styled subsections.
 
@@ -207,6 +269,8 @@ def render_summary_boxes(
         metrics: Metrics dictionary containing aggregated KPI values.
         component_types: Optional iterable of component type identifiers present
             in the microgrid (e.g., ``{"pv", "chp"}``).
+        microgrid_id: Optional microgrid identifier used for microgrid-specific
+            KPI cards.
 
     Returns:
         Streamlit components are rendered directly.
@@ -230,29 +294,49 @@ def render_summary_boxes(
     )
 
     for section in SECTION_SPECS:
+        box_specs = section["boxes"]
+        if component_type_set:
+            box_specs = [
+                spec
+                for spec in box_specs
+                if spec.get("component_type") is None
+                or spec.get("component_type") in component_type_set
+            ]
+        box_specs = [
+            spec
+            for spec in box_specs
+            if spec.get("microgrid_ids") is None
+            or microgrid_id in spec.get("microgrid_ids", set())
+        ]
+        if not box_specs:
+            continue
+
         title = section["title"]
         accent = _SECTION_ACCENTS.get(title, "#3b82f6")
         icon = _SECTION_ICONS.get(title, "●")
         icon_bg = accent + "22"  # ~13% opacity hex approximation
+        warning = section.get("warning")
+        warning_html = (
+            f'<span class="kpi-section-warning" role="button" tabindex="0" '
+            f'aria-label="{warning}">'
+            '<span class="kpi-section-warning__icon">⚠</span>'
+            f'<span class="kpi-section-warning__tooltip">{warning}</span>'
+            "</span>"
+            if warning
+            else ""
+        )
 
         st.markdown(
             f"""
             <div class="kpi-section-header">
                 <div class="kpi-section-icon" style="background:{icon_bg};">{icon}</div>
                 <p class="kpi-section-title">{title}</p>
+                {warning_html}
             </div>
             """,
             unsafe_allow_html=True,
         )
 
-        box_specs = section["boxes"]
-        if component_type_set:
-            box_specs = [
-                spec
-                for spec in box_specs
-                if spec.get("component_type") is None
-                or spec.get("component_type") in component_type_set
-            ]
         boxes = _materialize_boxes(box_specs, metrics)
         per_row = section.get("per_row", 3)
         render_box_grid(boxes, per_row=per_row, accent=accent)