Merge pull request #274 from Mohammad-Tayyab-Frequenz/add-production-self-share

Add production self share

Author: Mohammad-Tayyab-Frequenz

RELEASE_NOTES.md

@@ -11,8 +11,7 @@
 ## New Features
 
 <!-- Here goes the main new features and examples or instructions on how to use them -->
-- `build_color_map` now sources default colors from the in-code color dictionary rather than a YAML file.
+- Added production self-usage metrics to reporting flows and aggregations (`production_self_usage`, `production_self_share`).
 
 ## Bug Fixes
 
-- Added `normalize_date_for_report` to return current time for today, midnight for past dates, and reject future dates.

src/frequenz/lib/notebooks/reporting/metrics/reporting_metrics.py

@@ -183,7 +183,7 @@ def production_self_consumption(
     return result
 
 
-def production_self_share(
+def production_self_usage(
     production: pd.Series, consumption: pd.Series, production_is_positive: bool = False
 ) -> pd.Series:
     """Calculate the self-consumption share of total consumption.
@@ -210,6 +210,40 @@ def production_self_share(
     return share
 
 
+def production_self_share(
+    production: pd.Series, consumption: pd.Series, production_is_positive: bool = False
+) -> pd.Series:
+    """Compute the self-consumption share relative to total production.
+
+    Calculates the fraction of total production that is directly self-consumed.
+    The denominator is the positive production portion (after applying the
+    sign convention), and values are masked to ``NaN`` where production is
+    zero or negative to avoid invalid divisions.
+
+    Args:
+        production:
+            Series of production power values (e.g., kW).
+        consumption:
+            Series of consumption power values (same unit as ``production``).
+        production_is_positive:
+            Whether production values are already positive. If ``False``,
+            the production series is inverted before clipping to its
+            positive (productive) portion.
+
+    Returns:
+        Series of self-consumption share values (typically between 0 and 1).
+        Returns ``NaN`` for timestamps where total production is zero or negative.
+    """
+    production_self_use = production_self_consumption(
+        production, consumption, production_is_positive=production_is_positive
+    )
+    denom = asset_production(
+        production, production_is_positive=production_is_positive
+    ).astype("float64")
+    denom = denom.mask(denom <= 0)  # NaN when production <= 0
+    return production_self_use.astype("float64") / denom
+
+
 def consumption(
     grid: pd.Series,
     production: pd.Series | None = None,

src/frequenz/lib/notebooks/reporting/schema_mapping.yaml

@@ -94,15 +94,25 @@ columns:
       de: "Menge der Energie, die direkt vor Ort verbraucht wird."
     implementation: "reporting_metrics.py::prod_self_consumption"
 
-  prod_self_share:
-    raw: "prod_self_share"
+  production_self_share:
+    raw: "production_self_share"
+    display:
+      en: "Self-Production Share"
+      de: "Autarkiegrad"
+    description:
+      en: "Share of self-used production to total production."
+      de: "Anteil der Eigenproduktion am Gesamtverbrauch."
+    implementation: "reporting_metrics.py::production_self_share"
+
+  production_self_usage:
+    raw: "production_self_usage"
     display:
       en: "Self-Consumption Share"
       de: "Eigenverbrauchsanteil"
     description:
-      en: "Share of total consumption covered by production."
-      de: "Anteil des Gesamtverbrauchs, der durch Produktion gedeckt wird."
-    implementation: "reporting_metrics.py::prod_self_share"
+      en: "Share of self-used production to total consumption."
+      de: "Anteil der selbstgenutzten Produktion am Gesamtverbrauch."
+    implementation: "reporting_metrics.py::production_self_usage"
 
 
 # Generated and used within the notebook for reporting metrics

src/frequenz/lib/notebooks/reporting/utils/helpers.py

@@ -56,6 +56,7 @@
     production_excess_in_bat,
     production_self_consumption,
     production_self_share,
+    production_self_usage,
 )
 from frequenz.lib.notebooks.reporting.utils.colors import COLOR_DICT
 
@@ -315,6 +316,7 @@ def get_energy_report_columns(
         "production_self_use",
         "grid_feed_in",
         "production_self_share",
+        "production_self_usage",
     ]
 
     # Columns available ONLY when battery exists
@@ -375,7 +377,10 @@ def add_energy_flows(
             - "production_excess_in_bat": Portion of excess stored in the battery.
             - "grid_feed_in": Portion of excess fed into the grid.
             - "production_self_use": Self-consumed portion of production.
-            - "production_self_share": Share of consumption covered by self-production.
+            - "production_self_share": Share of production that is self-consumed
+              (self-consumed / total production).
+            - "production_self_usage": Share of consumption covered by
+              self-production (self-consumed / total consumption).
     """
     df_flows = df.copy()
 
@@ -475,9 +480,15 @@ def add_energy_flows(
             df_flows["consumption_total"],
             production_is_positive=True,
         )
+        df_flows["production_self_usage"] = production_self_usage(
+            df_flows["production_total"],
+            df_flows["consumption_total"],
+            production_is_positive=True,
+        )
     else:
         df_flows["production_self_use"] = 0.0
         df_flows["production_self_share"] = 0.0
+        df_flows["production_self_usage"] = 0.0
 
     # Add grid consumption column - grid is later renamed as grid_consumption
     if "grid" not in df_flows.columns:

src/frequenz/lib/notebooks/reporting/utils/reporting_nb_functions.py

@@ -519,6 +519,10 @@ def aggregate_metrics(  # pylint: disable=too-many-locals
             Total site consumption (kWh)
             - ``prod_self_consumption_share``
             Fraction of site consumption covered by self-production (0-1)
+            - ``production_self_share``
+            Fraction of total production that is self-consumed (0-1)
+            - ``production_self_usage``
+            Fraction of site consumption covered by self-production (0-1)
             - ``peak``
             Maximum grid import power (kW)
             - ``peak_date``
@@ -581,6 +585,12 @@ def aggregate_metrics(  # pylint: disable=too-many-locals
         else 0
     )
 
+    results["prod_self_production_share"] = (
+        prod_self_consumption_sum / total_production_sum
+        if total_production_sum > 0
+        else 0
+    )
+
     # Get the grid_consumption series for peak calculation (kW)
     grid_consumption_series = energy_report_df.get("grid_consumption", zeros)
 

tests/test_reporting_metrics.py

@@ -77,16 +77,47 @@ def test_production_self_consumption_warns_on_negative_values() -> None:
     assert_series_equal(result, expected)
 
 
-def test_production_self_share_masks_zero_or_negative_consumption() -> None:
-    """Self-consumption share returns NaN where consumption is not positive."""
-    production = pd.Series([-4.0, -2.0], index=pd.RangeIndex(2))
-    consumption = pd.Series([3.0, 0.0], index=production.index)
+def test_production_self_share_masks_zero_or_negative_production() -> None:
+    """Self-consumption share returns NaN where production is not positive."""
+    production = pd.Series([-4.0, 0.0], index=pd.RangeIndex(2))
+    consumption = pd.Series([3.0, 3.0], index=production.index)
 
     result = metrics.production_self_share(production, consumption)
-    expected = pd.Series([1.0, float("nan")], index=production.index)
+    expected = pd.Series([0.75, float("nan")], index=production.index)
+    assert_series_equal(result, expected)
+
+
+def test_production_self_usage_masks_zero_or_negative_consumption() -> None:
+    """Self-usage returns NaN where consumption is not positive."""
+    production = pd.Series([-4.0, -2.0], index=pd.RangeIndex(2))
+    consumption = pd.Series([0.0, -1.0], index=production.index)
+
+    with pytest.warns(UserWarning):
+        result = metrics.production_self_usage(production, consumption)
+    expected = pd.Series([float("nan"), float("nan")], index=production.index)
     assert_series_equal(result, expected)
 
 
+def test_production_self_usage_computes_expected_values() -> None:
+    """Self-usage computes expected ratios with PSC inputs."""
+    production = pd.Series([-10.0, -5.0], index=pd.RangeIndex(2))
+    consumption = pd.Series([8.0, 2.0], index=production.index)
+
+    usage = metrics.production_self_usage(production, consumption)
+    expected = pd.Series([1.0, 1.0], index=production.index)
+    assert_series_equal(usage, expected)
+
+
+def test_production_self_share_computes_expected_values() -> None:
+    """Self-share computes expected ratios with PSC inputs."""
+    production = pd.Series([-10.0, -5.0], index=pd.RangeIndex(2))
+    consumption = pd.Series([8.0, 2.0], index=production.index)
+
+    share = metrics.production_self_share(production, consumption)
+    expected = pd.Series([0.8, 0.4], index=production.index)
+    assert_series_equal(share, expected)
+
+
 def test_consumption_infers_total_and_sets_series_name() -> None:
     """Grid, production, and battery power are combined to infer consumption."""
     grid = pd.Series([5, 4], index=pd.RangeIndex(2))