openenergyid 0.1.19__py2.py3-none-any.whl → 0.1.21__py2.py3-none-any.whl

openenergyid/__init__.py

@@ -1,6 +1,6 @@
 """Open Energy ID Python SDK."""
 
-__version__ = "0.1.19"
+__version__ = "0.1.21"
 
 from .enums import Granularity
 from .models import TimeDataFrame, TimeSeries

openenergyid/baseload/__init__.py

@@ -0,0 +1,15 @@
+"""Baseload analysis package for power consumption data."""
+
+from .models import PowerReadingSchema, PowerSeriesSchema, BaseloadResultSchema
+from .analysis import BaseloadAnalyzer
+from .exceptions import InsufficientDataError, InvalidDataError
+
+__version__ = "0.1.0"
+__all__ = [
+    "BaseloadAnalyzer",
+    "InsufficientDataError",
+    "InvalidDataError",
+    "PowerReadingSchema",
+    "PowerSeriesSchema",
+    "BaseloadResultSchema",
+]

openenergyid/baseload/analysis.py

@@ -0,0 +1,173 @@
+"""Baseload Power Consumption Analysis Module
+
+This module provides tools for analyzing electrical power consumption patterns to identify
+and quantify baseload - the continuous background power usage in electrical systems.
+It uses sophisticated time-series analysis to detect consistent minimum power draws
+that represent always-on devices and systems.
+"""
+
+import polars as pl
+
+
+class BaseloadAnalyzer:
+    """Analyzes power consumption data to determine baseload characteristics.
+
+    The BaseloadAnalyzer helps identify the minimum continuous power consumption in
+    an electrical system by analyzing regular energy readings. It uses a statistical
+    approach to determine baseload, which represents power used by devices that run
+    continuously (like refrigerators, standby electronics, or network equipment).
+
+    The analyzer works by:
+    1. Converting 15-minute energy readings to instantaneous power values
+    2. Analyzing daily patterns to identify consistent minimum usage
+    3. Aggregating results into configurable time periods
+
+    Parameters
+    ----------
+    quantile : float, default=0.05
+        Defines what portion of lowest daily readings to consider as baseload.
+        The default 0.05 (5%) corresponds to roughly 72 minutes of lowest
+        consumption per day, which helps filter out brief power dips while
+        capturing true baseload patterns.
+
+    timezone : str
+        Timezone for analysis. All timestamps will be converted to this timezone
+        to ensure correct daily boundaries and consistent reporting periods.
+
+    Example Usage
+    ------------
+    >>> analyzer = BaseloadAnalyzer(quantile=0.05)
+    >>> power_data = analyzer.prepare_power_seriespolars(energy_readings)
+    >>> hourly_analysis = analyzer.analyze(power_data, "1h")
+    >>> monthly_analysis = analyzer.analyze(power_data, "1mo")
+    """
+
+    def __init__(self, timezone: str, quantile: float = 0.05):
+        self.quantile = quantile
+        self.timezone = timezone
+
+    def prepare_power_seriespolars(self, energy_lf: pl.LazyFrame) -> pl.LazyFrame:
+        """Converts energy readings into a power consumption time series.
+
+        Transforms 15-minute energy readings (kilowatt-hours) into instantaneous
+        power readings (watts) while handling timezone conversion.
+
+        Parameters
+        ----------
+        energy_lf : pl.LazyFrame
+            Input energy data with columns:
+            - timestamp: Datetime with timezone (e.g. "2023-01-01T00:00:00+01:00")
+            - total: Energy readings in kilowatt-hours (kWh)
+
+        Returns
+        -------
+        pl.LazyFrame
+            Power series with columns:
+            - timestamp: Timezone-adjusted timestamps
+            - power: Power readings in watts
+
+        Notes
+        -----
+        The conversion from kWh/15min to watts uses the formula:
+            watts = kWh * 4000
+        where:
+        - Multiply by 4 to convert from 15-minute to hourly rate
+        - Multiply by 1000 to convert from kilowatts to watts
+        """
+        return (
+            energy_lf.with_columns(
+                [
+                    # Convert timezone
+                    pl.col("timestamp")
+                    .dt.replace_time_zone("UTC")
+                    .dt.convert_time_zone(self.timezone)
+                    .alias("timestamp"),
+                    # Convert to watts and clip negative values
+                    (pl.col("total") * 4000).clip(0).alias("power"),
+                ]
+            )
+            .drop("total")
+            .sort("timestamp")
+        )
+
+    def analyze(self, power_lf: pl.LazyFrame, reporting_granularity: str = "1h") -> pl.LazyFrame:
+        """Analyze power consumption data to calculate baseload and total energy metrics.
+
+        Takes power readings (in watts) with 15-minute intervals and calculates:
+        - Daily baseload power using a percentile threshold
+        - Energy consumption from baseload vs total consumption
+        - Average power metrics
+
+        The analysis happens in three steps:
+        1. Calculate the daily baseload power level using the configured percentile
+        2. Join this daily baseload with the original power readings
+        3. Aggregate the combined data into the requested reporting periods
+
+        Parameters
+        ----------
+        power_lf : pl.LazyFrame
+            Power consumption data with columns:
+            - timestamp: Datetime in configured timezone
+            - power: Power readings in watts
+
+        reporting_granularity : str, default="1h"
+            Time period for aggregating results. Must be a valid Polars interval string
+            like "1h", "1d", "1mo" etc.
+
+        Returns
+        -------
+        pl.LazyFrame
+            Analysis results with metrics per reporting period:
+            - timestamp: Start of reporting period
+            - consumption_due_to_baseload_in_kilowatthour: Baseload energy
+            - total_consumption_in_kilowatthour: Total energy
+            - consumption_not_due_to_baseload_in_kilowatthour: Non-baseload energy
+            - average_daily_baseload_in_watt: Average baseload power level
+            - average_power_in_watt: Average total power
+            - baseload_ratio: Fraction of energy from baseload
+        """
+        # Step 1: Calculate the daily baseload level
+        # Group power readings by day and find the threshold power level that represents baseload
+        daily_baseload = power_lf.group_by_dynamic("timestamp", every="1d").agg(
+            pl.col("power").quantile(self.quantile).alias("daily_baseload")
+        )
+
+        # Step 2 & 3: Join baseload data and aggregate metrics
+        return (
+            # Join the daily baseload level with original power readings
+            # Using asof join since baseload changes daily but readings are every 15min
+            power_lf.join_asof(daily_baseload, on="timestamp")
+            # Group into requested reporting periods
+            .group_by_dynamic("timestamp", every=reporting_granularity)
+            .agg(
+                [
+                    # Energy calculations:
+                    # Each 15min power reading (watts) represents 0.25 hours
+                    # Convert to kWh: watts * 0.25h * (1kW/1000W)
+                    (pl.col("daily_baseload").sum() * 0.25 / 1000).alias(
+                        "consumption_due_to_baseload_in_kilowatthour"
+                    ),
+                    (pl.col("power").sum() * 0.25 / 1000).alias(
+                        "total_consumption_in_kilowatthour"
+                    ),
+                    # Average power levels during the period
+                    pl.col("daily_baseload").mean().alias("average_daily_baseload_in_watt"),
+                    pl.col("power").mean().alias("average_power_in_watt"),
+                ]
+            )
+            # Calculate derived metrics
+            .with_columns(
+                [
+                    # Energy consumed above baseload level
+                    (
+                        pl.col("total_consumption_in_kilowatthour")
+                        - pl.col("consumption_due_to_baseload_in_kilowatthour")
+                    ).alias("consumption_not_due_to_baseload_in_kilowatthour"),
+                    # What fraction of total energy was from baseload
+                    (
+                        pl.col("consumption_due_to_baseload_in_kilowatthour")
+                        / pl.col("total_consumption_in_kilowatthour")
+                    ).alias("baseload_ratio"),
+                ]
+            )
+        )

openenergyid/baseload/exceptions.py

@@ -0,0 +1,9 @@
+"""Custom exceptions for baseload analysis."""
+
+
+class InsufficientDataError(Exception):
+    """Raised when input data doesn't meet minimum requirements."""
+
+
+class InvalidDataError(Exception):
+    """Raised when input data is invalid or corrupt."""

openenergyid/baseload/models.py

@@ -0,0 +1,31 @@
+import pandera.polars as pa
+from pandera.engines.polars_engine import DateTime
+
+
+class PowerReadingSchema(pa.DataFrameModel):
+    """Validates input energy readings"""
+
+    timestamp: DateTime = pa.Field()
+    total: float = pa.Field(ge=0)
+
+    class Config:
+        coerce = True
+
+
+class PowerSeriesSchema(pa.DataFrameModel):
+    """Validates converted power series"""
+
+    timestamp: DateTime = pa.Field()
+    power: float = pa.Field(ge=0)
+
+
+class BaseloadResultSchema(pa.DataFrameModel):
+    """Validates analysis results"""
+
+    timestamp: DateTime = pa.Field()
+    consumption_due_to_baseload_in_kilowatthour: float = pa.Field(ge=0)
+    total_consumption_in_kilowatthour: float = pa.Field(ge=0)
+    average_daily_baseload_in_watt: float = pa.Field(ge=0)
+    average_power_in_watt: float = pa.Field(ge=0)
+    consumption_not_due_to_baseload_in_kilowatthour: float
+    baseload_ratio: float = pa.Field(ge=0, le=2)

openenergyid/dyntar/__init__.py

@@ -1,9 +1,10 @@
 """Dynamic Tariff Analysis module."""
 
-from .main import calculate_dyntar_columns
+from .main import calculate_dyntar_columns, summarize_result
 from .models import (
     DynamicTariffAnalysisInput,
     DynamicTariffAnalysisOutput,
+    DynamicTariffAnalysisOutputSummary,
     OutputColumns,
     RequiredColumns,
 )
@@ -12,6 +13,8 @@ __all__ = [
     "calculate_dyntar_columns",
     "DynamicTariffAnalysisInput",
     "DynamicTariffAnalysisOutput",
+    "DynamicTariffAnalysisOutputSummary",
     "OutputColumns",
     "RequiredColumns",
+    "summarize_result",
 ]

openenergyid/dyntar/const.py

@@ -1,5 +1,7 @@
 """Constants for the dyntar analysis."""
 
+from enum import Enum
+
 ELECTRICITY_DELIVERED_SMR3 = "electricity_delivered_smr3"
 ELECTRICITY_EXPORTED_SMR3 = "electricity_exported_smr3"
 ELECTRICITY_DELIVERED_SMR2 = "electricity_delivered_smr2"
@@ -20,3 +22,10 @@ HEATMAP_TOTAL = "heatmap_total"
 HEATMAP_DELIVERED_DESCRIPTION = "heatmap_delivered_description"
 HEATMAP_EXPORTED_DESCRIPTION = "heatmap_exported_description"
 HEATMAP_TOTAL_DESCRIPTION = "heatmap_total_description"
+
+
+class Register(Enum):
+    """Register for dynamic tariff analysis."""
+
+    DELIVERY = "delivery"
+    EXPORT = "export"

openenergyid/dyntar/main.py

@@ -1,6 +1,6 @@
 """Main module of the DynTar package."""
 
-import numpy as np
+from typing import cast
 import pandas as pd
 
 from openenergyid.const import (
@@ -29,6 +29,7 @@ from .const import (
     HEATMAP_DELIVERED_DESCRIPTION,
     HEATMAP_EXPORTED_DESCRIPTION,
     HEATMAP_TOTAL_DESCRIPTION,
+    Register,
 )
 
 
@@ -40,15 +41,28 @@ def weigh_by_monthly_profile(df: pd.DataFrame, series_name, profile_name) -> pd.
     )
 
 
-def extend_dataframe_with_smr2(df: pd.DataFrame, inplace: bool = False) -> pd.DataFrame | None:
+def extend_dataframe_with_smr2(
+    df: pd.DataFrame,
+    inplace: bool = False,
+    registers: list[Register] | None = None,
+) -> pd.DataFrame | None:
     """Extend a DataFrame with the SMR2 columns."""
     if not inplace:
         result_df = df.copy()
     else:
         result_df = df
 
-    result_df[ELECTRICITY_DELIVERED_SMR2] = weigh_by_monthly_profile(df, ELECTRICITY_DELIVERED, RLP)
-    result_df[ELECTRICITY_EXPORTED_SMR2] = weigh_by_monthly_profile(df, ELECTRICITY_EXPORTED, SPP)
+    if registers is None:
+        registers = [Register.DELIVERY, Register.EXPORT]
+
+    if Register.DELIVERY in registers:
+        result_df[ELECTRICITY_DELIVERED_SMR2] = weigh_by_monthly_profile(
+            df, ELECTRICITY_DELIVERED, RLP
+        )
+    if Register.EXPORT in registers:
+        result_df[ELECTRICITY_EXPORTED_SMR2] = weigh_by_monthly_profile(
+            df, ELECTRICITY_EXPORTED, SPP
+        )
 
     result_df.rename(
         columns={
@@ -56,6 +70,7 @@ def extend_dataframe_with_smr2(df: pd.DataFrame, inplace: bool = False) -> pd.Da
             ELECTRICITY_EXPORTED: ELECTRICITY_EXPORTED_SMR3,
         },
         inplace=True,
+        errors="ignore",
     )
 
     if not inplace:
@@ -63,26 +78,33 @@ def extend_dataframe_with_smr2(df: pd.DataFrame, inplace: bool = False) -> pd.Da
     return None
 
 
-def extend_dataframe_with_costs(df: pd.DataFrame, inplace: bool = False) -> pd.DataFrame | None:
+def extend_dataframe_with_costs(
+    df: pd.DataFrame, inplace: bool = False, registers: list[Register] | None = None
+) -> pd.DataFrame | None:
     """Extend a DataFrame with the cost columns."""
     if not inplace:
         result_df = df.copy()
     else:
         result_df = df
 
-    result_df[COST_ELECTRICITY_DELIVERED_SMR2] = (
-        df[ELECTRICITY_DELIVERED_SMR2] * df[PRICE_ELECTRICITY_DELIVERED]
-    )
-    result_df[COST_ELECTRICITY_EXPORTED_SMR2] = (
-        df[ELECTRICITY_EXPORTED_SMR2] * df[PRICE_ELECTRICITY_EXPORTED] * -1
-    )
+    if registers is None:
+        registers = [Register.DELIVERY, Register.EXPORT]
 
-    result_df[COST_ELECTRICITY_DELIVERED_SMR3] = (
-        df[ELECTRICITY_DELIVERED_SMR3] * df[PRICE_ELECTRICITY_DELIVERED]
-    )
-    result_df[COST_ELECTRICITY_EXPORTED_SMR3] = (
-        df[ELECTRICITY_EXPORTED_SMR3] * df[PRICE_ELECTRICITY_EXPORTED] * -1
-    )
+    if Register.DELIVERY in registers:
+        result_df[COST_ELECTRICITY_DELIVERED_SMR2] = (
+            df[ELECTRICITY_DELIVERED_SMR2] * df[PRICE_ELECTRICITY_DELIVERED]
+        )
+        result_df[COST_ELECTRICITY_DELIVERED_SMR3] = (
+            df[ELECTRICITY_DELIVERED_SMR3] * df[PRICE_ELECTRICITY_DELIVERED]
+        )
+
+    if Register.EXPORT in registers:
+        result_df[COST_ELECTRICITY_EXPORTED_SMR2] = (
+            df[ELECTRICITY_EXPORTED_SMR2] * df[PRICE_ELECTRICITY_EXPORTED] * -1
+        )
+        result_df[COST_ELECTRICITY_EXPORTED_SMR3] = (
+            df[ELECTRICITY_EXPORTED_SMR3] * df[PRICE_ELECTRICITY_EXPORTED] * -1
+        )
 
     if not inplace:
         return result_df
@@ -90,63 +112,70 @@ def extend_dataframe_with_costs(df: pd.DataFrame, inplace: bool = False) -> pd.D
 
 
 def extend_dataframe_with_weighted_prices(
-    df: pd.DataFrame, inplace: bool = False
+    df: pd.DataFrame, inplace: bool = False, registers: list[Register] | None = None
 ) -> pd.DataFrame | None:
     """Extend a DataFrame with the weighted price columns."""
     if not inplace:
         df = df.copy()
 
-    rlp_weighted_price_delivered = (df[PRICE_ELECTRICITY_DELIVERED] * df[RLP]).resample(
-        "MS"
-    ).sum() / df[RLP].resample("MS").sum()
-    df[RLP_WEIGHTED_PRICE_DELIVERED] = rlp_weighted_price_delivered.reindex_like(
-        df[RLP], method="ffill"
-    )
-    spp_weighted_price_exported = (df[PRICE_ELECTRICITY_EXPORTED] * df[SPP]).resample(
-        "MS"
-    ).sum() / df[SPP].resample("MS").sum()
-    df[SPP_WEIGHTED_PRICE_EXPORTED] = spp_weighted_price_exported.reindex_like(
-        df[SPP], method="ffill"
-    )
+    if registers is None:
+        registers = [Register.DELIVERY, Register.EXPORT]
+
+    if Register.DELIVERY in registers:
+        rlp_weighted_price_delivered = (df[PRICE_ELECTRICITY_DELIVERED] * df[RLP]).resample(
+            "MS"
+        ).sum() / df[RLP].resample("MS").sum()
+        df[RLP_WEIGHTED_PRICE_DELIVERED] = rlp_weighted_price_delivered.reindex_like(
+            df[RLP], method="ffill"
+        )
+
+    if Register.EXPORT in registers:
+        spp_weighted_price_exported = (df[PRICE_ELECTRICITY_EXPORTED] * df[SPP]).resample(
+            "MS"
+        ).sum() / df[SPP].resample("MS").sum()
+        df[SPP_WEIGHTED_PRICE_EXPORTED] = spp_weighted_price_exported.reindex_like(
+            df[SPP], method="ffill"
+        )
 
     if not inplace:
         return df
     return None
 
 
-def extend_dataframe_with_heatmap(df: pd.DataFrame, inplace: bool = False) -> pd.DataFrame | None:
+def extend_dataframe_with_heatmap(
+    df: pd.DataFrame, inplace: bool = False, registers: list[Register] | None = None
+) -> pd.DataFrame | None:
     """Extend a DataFrame with the heatmap columns."""
     if not inplace:
         df = df.copy()
 
-    normalized_energy_delta_delivered = (
-        df[ELECTRICITY_DELIVERED_SMR2] - df[ELECTRICITY_DELIVERED_SMR3]
-    ) / df[ELECTRICITY_DELIVERED_SMR2]
-    normalized_price_delta_delivered = (
-        df[RLP_WEIGHTED_PRICE_DELIVERED] - df[PRICE_ELECTRICITY_DELIVERED]
-    ) / df[RLP_WEIGHTED_PRICE_DELIVERED]
-    heatmap_score_delivered = normalized_energy_delta_delivered * normalized_price_delta_delivered
-
-    normalized_energy_delta_exported = (
-        df[ELECTRICITY_EXPORTED_SMR2] - df[ELECTRICITY_EXPORTED_SMR3]
-    ) / df[ELECTRICITY_EXPORTED_SMR2]
-    normalized_energy_delta_exported = normalized_energy_delta_exported.replace(
-        [np.inf, -np.inf], np.nan
-    )
-    normalized_price_delta_exported = (
-        df[SPP_WEIGHTED_PRICE_EXPORTED] - df[PRICE_ELECTRICITY_EXPORTED]
-    ) / df[SPP_WEIGHTED_PRICE_EXPORTED]
-    heatmap_score_exported = normalized_energy_delta_exported * normalized_price_delta_exported
-
-    heatmap_score_delivered.fillna(0, inplace=True)
-    heatmap_score_exported.fillna(0, inplace=True)
-
-    # Invert scores so that positive values indicate a positive impact
-    heatmap_score_delivered = -heatmap_score_delivered
-    heatmap_score_combined = heatmap_score_delivered + heatmap_score_exported
-
-    df[HEATMAP_DELIVERED] = heatmap_score_delivered
-    df[HEATMAP_EXPORTED] = heatmap_score_exported
+    if registers is None:
+        registers = [Register.DELIVERY, Register.EXPORT]
+
+    if Register.DELIVERY in registers:
+        energy_delta_delivered = df[ELECTRICITY_DELIVERED_SMR2] - df[ELECTRICITY_DELIVERED_SMR3]
+        price_delta_delivered = df[RLP_WEIGHTED_PRICE_DELIVERED] - df[PRICE_ELECTRICITY_DELIVERED]
+        heatmap_score_delivered = energy_delta_delivered * price_delta_delivered
+        heatmap_score_delivered.fillna(0, inplace=True)
+        # Invert score so that positive values indicate a positive impact
+        heatmap_score_delivered = -heatmap_score_delivered
+        df[HEATMAP_DELIVERED] = heatmap_score_delivered
+
+    if Register.EXPORT in registers:
+        energy_delta_exported = df[ELECTRICITY_EXPORTED_SMR2] - df[ELECTRICITY_EXPORTED_SMR3]
+        price_delta_exported = df[SPP_WEIGHTED_PRICE_EXPORTED] - df[PRICE_ELECTRICITY_EXPORTED]
+        heatmap_score_exported = energy_delta_exported * price_delta_exported
+        heatmap_score_exported.fillna(0, inplace=True)
+        df[HEATMAP_EXPORTED] = heatmap_score_exported
+
+    if Register.DELIVERY in registers and Register.EXPORT in registers:
+        heatmap_score_delivered = cast(pd.Series, df[HEATMAP_DELIVERED])
+        heatmap_score_exported = cast(pd.Series, df[HEATMAP_EXPORTED])
+        heatmap_score_combined = heatmap_score_delivered + heatmap_score_exported
+    elif Register.DELIVERY in registers:
+        heatmap_score_combined = heatmap_score_delivered
+    else:
+        heatmap_score_combined = heatmap_score_exported
     df[HEATMAP_TOTAL] = heatmap_score_combined
 
     if not inplace:
@@ -194,56 +223,90 @@ def map_total_description(
 
 
 def extend_dataframe_with_heatmap_description(
-    df: pd.DataFrame, inplace: bool = False
+    df: pd.DataFrame, inplace: bool = False, registers: list[Register] | None = None
 ) -> pd.DataFrame | None:
     """Extend a DataFrame with the heatmap description columns."""
     if not inplace:
         df = df.copy()
 
-    df[HEATMAP_DELIVERED_DESCRIPTION] = list(
-        map(
-            map_delivery_description,
-            df[PRICE_ELECTRICITY_DELIVERED],
-            df[RLP_WEIGHTED_PRICE_DELIVERED],
-            df[ELECTRICITY_DELIVERED_SMR3],
-            df[ELECTRICITY_DELIVERED_SMR2],
+    if registers is None:
+        registers = [Register.DELIVERY, Register.EXPORT]
+
+    if Register.DELIVERY in registers:
+        df[HEATMAP_DELIVERED_DESCRIPTION] = list(
+            map(
+                map_delivery_description,
+                df[PRICE_ELECTRICITY_DELIVERED],
+                df[RLP_WEIGHTED_PRICE_DELIVERED],
+                df[ELECTRICITY_DELIVERED_SMR3],
+                df[ELECTRICITY_DELIVERED_SMR2],
+            )
         )
-    )
-    df[HEATMAP_EXPORTED_DESCRIPTION] = list(
-        map(
-            map_export_description,
-            df[PRICE_ELECTRICITY_EXPORTED],
-            df[SPP_WEIGHTED_PRICE_EXPORTED],
-            df[ELECTRICITY_EXPORTED_SMR3],
-            df[ELECTRICITY_EXPORTED_SMR2],
+
+    if Register.EXPORT in registers:
+        df[HEATMAP_EXPORTED_DESCRIPTION] = list(
+            map(
+                map_export_description,
+                df[PRICE_ELECTRICITY_EXPORTED],
+                df[SPP_WEIGHTED_PRICE_EXPORTED],
+                df[ELECTRICITY_EXPORTED_SMR3],
+                df[ELECTRICITY_EXPORTED_SMR2],
+            )
         )
-    )
 
-    df[HEATMAP_TOTAL_DESCRIPTION] = list(
-        map(
-            map_total_description,
-            df[HEATMAP_DELIVERED].abs(),
-            df[HEATMAP_EXPORTED].abs(),
-            df[HEATMAP_DELIVERED_DESCRIPTION],
-            df[HEATMAP_EXPORTED_DESCRIPTION],
+    if Register.DELIVERY in registers and Register.EXPORT in registers:
+        df[HEATMAP_TOTAL_DESCRIPTION] = list(
+            map(
+                map_total_description,
+                df[HEATMAP_DELIVERED].abs(),
+                df[HEATMAP_EXPORTED].abs(),
+                df[HEATMAP_DELIVERED_DESCRIPTION],
+                df[HEATMAP_EXPORTED_DESCRIPTION],
+            )
         )
-    )
+    elif Register.DELIVERY in registers:
+        df[HEATMAP_TOTAL_DESCRIPTION] = df[HEATMAP_DELIVERED_DESCRIPTION]
+    else:
+        df[HEATMAP_TOTAL_DESCRIPTION] = df[HEATMAP_EXPORTED_DESCRIPTION]
 
     if not inplace:
         return df
 
 
-def calculate_dyntar_columns(df: pd.DataFrame, inplace: bool = False) -> pd.DataFrame | None:
+def calculate_dyntar_columns(
+    df: pd.DataFrame,
+    inplace: bool = False,
+    registers: list[Register] | None = None,
+) -> pd.DataFrame | None:
     """Calculate all columns required for the dynamic tariff analysis."""
     if not inplace:
         df = df.copy()
 
-    extend_dataframe_with_smr2(df, inplace=True)
-    extend_dataframe_with_costs(df, inplace=True)
-    extend_dataframe_with_weighted_prices(df, inplace=True)
-    extend_dataframe_with_heatmap(df, inplace=True)
-    extend_dataframe_with_heatmap_description(df, inplace=True)
+    if registers is None:
+        registers = [Register.DELIVERY, Register.EXPORT]
+
+    extend_dataframe_with_smr2(df, inplace=True, registers=registers)
+    extend_dataframe_with_costs(df, inplace=True, registers=registers)
+    extend_dataframe_with_weighted_prices(df, inplace=True, registers=registers)
+    extend_dataframe_with_heatmap(df, inplace=True, registers=registers)
+    extend_dataframe_with_heatmap_description(df, inplace=True, registers=registers)
 
     if not inplace:
         return df
     return None
+
+
+def summarize_result(df: pd.DataFrame) -> pd.Series:
+    """Summarize the dynamic tariff analysis result."""
+    summary = df.filter(like="cost").sum()
+
+    abs_smr2 = summary.filter(like="smr2").abs().sum()
+
+    summary["cost_electricity_total_smr2"] = summary.filter(like="smr2").sum()
+    summary["cost_electricity_total_smr3"] = summary.filter(like="smr3").sum()
+
+    summary["ratio"] = (
+        summary["cost_electricity_total_smr3"] - summary["cost_electricity_total_smr2"]
+    ) / abs_smr2
+
+    return summary

openenergyid/dyntar/models.py

@@ -1,9 +1,10 @@
 """Models for dynamic tariff analysis."""
 
 from typing import Literal
-from pydantic import Field, conlist, confloat
+from pydantic import Field, conlist, confloat, BaseModel
 
 from openenergyid.models import TimeDataFrame
+from .const import Register
 
 
 RequiredColumns = Literal[
@@ -43,18 +44,53 @@ class DynamicTariffAnalysisInput(TimeDataFrame):
     """Input frame for dynamic tariff analysis."""
 
     columns: list[RequiredColumns] = Field(
-        min_length=len(RequiredColumns.__args__),
+        min_length=3,
         max_length=len(RequiredColumns.__args__),
         examples=[RequiredColumns.__args__],
     )
     data: list[
         conlist(
             item_type=confloat(allow_inf_nan=True),
-            min_length=len(RequiredColumns.__args__),
+            min_length=3,
             max_length=len(RequiredColumns.__args__),
         )  # type: ignore
     ] = Field(examples=[[0.0] * len(RequiredColumns.__args__)])
 
+    @property
+    def registers(self) -> list[Register]:
+        """Check which registers are present in the input data."""
+        registers = []
+        columns = list(self.columns)
+        # if "electricity_delivered", "price_electricity_delivered" and "RLP" are present
+        if all(
+            column in columns
+            for column in [
+                "electricity_delivered",
+                "price_electricity_delivered",
+                "RLP",
+            ]
+        ):
+            registers.append(Register.DELIVERY)
+        # if "electricity_exported", "price_electricity_exported" and "SPP" are present
+        if all(
+            column in columns
+            for column in ["electricity_exported", "price_electricity_exported", "SPP"]
+        ):
+            registers.append(Register.EXPORT)
+        return registers
+
+
+class DynamicTariffAnalysisOutputSummary(BaseModel):
+    """Summary of the dynamic tariff analysis output."""
+
+    cost_electricity_delivered_smr2: float | None = None
+    cost_electricity_delivered_smr3: float | None = None
+    cost_electricity_exported_smr2: float | None = None
+    cost_electricity_exported_smr3: float | None = None
+    cost_electricity_total_smr2: float | None = None
+    cost_electricity_total_smr3: float | None = None
+    ratio: float | None = None
+
 
 class DynamicTariffAnalysisOutput(TimeDataFrame):
     """Output frame for dynamic tariff analysis."""
@@ -71,3 +107,4 @@ class DynamicTariffAnalysisOutput(TimeDataFrame):
             max_length=len(OutputColumns.__args__),
         )  # type: ignore
     ] = Field(examples=[[0.0] * len(OutputColumns.__args__)])
+    summary: DynamicTariffAnalysisOutputSummary | None = None

openenergyid/models.py

@@ -7,6 +7,7 @@ from typing import Self
 
 import pandas as pd
 from pydantic import BaseModel
+import polars as pl
 
 
 class TimeSeriesBase(BaseModel):
@@ -75,10 +76,14 @@ class TimeSeries(TimeSeriesBase):
             Create a TimeSeries object from a Pandas Series.
         to_pandas(self, timezone: str = "UTC") -> pd.Series:
             Convert the TimeSeries object to a Pandas Series.
+        from_polars(cls, data: pl.DataFrame | pl.LazyFrame) -> Self:
+            Create a TimeSeries object from Polars data.
+        to_polars(self, timezone: str = "UTC") -> pl.LazyFrame:
+            Convert the TimeSeries object to a Polars LazyFrame.
     """
 
     name: str | None = None
-    data: list[float]
+    data: list[float | None]
 
     @classmethod
     def from_pandas(cls, data: pd.Series) -> Self:
@@ -91,19 +96,50 @@ class TimeSeries(TimeSeriesBase):
         series.index = pd.to_datetime(series.index, utc=True)
         return series.tz_convert(timezone)
 
+    @classmethod
+    def from_polars(cls, data: pl.DataFrame | pl.LazyFrame) -> Self:
+        """Create from Polars data."""
+        # Always work with DataFrame
+        df = data.collect() if isinstance(data, pl.LazyFrame) else data
+
+        if len(df.columns) != 2:
+            raise ValueError("Must contain exactly two columns: timestamp and value")
+
+        value_col = [col for col in df.columns if col != "timestamp"][0]
+        return cls(
+            name=value_col,
+            data=df[value_col].cast(pl.Float64).to_list(),  # Ensure float type
+            index=df["timestamp"].cast(pl.Datetime).dt.convert_time_zone("UTC").to_list(),
+        )
+
+    def to_polars(self, timezone: str = "UTC") -> pl.LazyFrame:
+        """Convert to Polars LazyFrame."""
+        # Always return LazyFrame as specified in return type
+        df = pl.DataFrame(
+            {
+                "timestamp": pl.Series(self.index, dtype=pl.Datetime).dt.convert_time_zone(
+                    timezone
+                ),
+                "total" if self.name is None else self.name: pl.Series(self.data, dtype=pl.Float64),
+            }
+        )
+        return df.lazy()
+
 
 class TimeDataFrame(TimeSeriesBase):
     """Time series data with multiple columns."""
 
     columns: list[str]
-    data: list[list[float]]
+    data: list[list[float | None]]
 
     @classmethod
     def from_pandas(cls, data: pd.DataFrame) -> Self:
         """Create from a Pandas DataFrame."""
-        return cls(
-            columns=data.columns.tolist(), data=data.values.tolist(), index=data.index.tolist()
-        )
+        # Cast values to float | None
+        values = [
+            [float(x) if pd.notnull(x) else None for x in row] for row in data.values.tolist()
+        ]
+        return cls(columns=data.columns.tolist(), data=values, index=data.index.tolist())
 
     def to_pandas(self, timezone: str = "UTC") -> pd.DataFrame:
         """Convert to a Pandas DataFrame."""
@@ -114,15 +150,15 @@ class TimeDataFrame(TimeSeriesBase):
     @classmethod
     def from_timeseries(cls, data: list[TimeSeries]) -> Self:
         """Create from a list of TimeSeries objects."""
-        return cls.model_construct(
-            columns=[series.name for series in data],
-            data=[series.data for series in data],
+        return cls(
+            columns=[series.name or "" for series in data],  # Handle None names
+            data=[series.data for series in data],  # Pass list of value lists
             index=data[0].index,
         )
 
     def to_timeseries(self) -> list[TimeSeries]:
         """Convert to a list of TimeSeries objects."""
         return [
-            TimeSeries(name=column, data=column_data, index=self.index)
-            for column, column_data in zip(self.columns, self.data)
+            TimeSeries(name=col, data=[row[i] for row in self.data], index=self.index)
+            for i, col in enumerate(self.columns)
         ]

openenergyid/mvlr/main.py

@@ -9,6 +9,7 @@ def find_best_mvlr(
     data: MultiVariableRegressionInput,
 ) -> MultiVariableRegressionResult:
     """Cycle through multiple granularities and return the best model."""
+    best_rsquared = 0
     for granularity in data.granularities:
         frame = data.data_frame()
         frame = resample_input_data(data=frame, granularity=granularity)
@@ -17,7 +18,7 @@ def find_best_mvlr(
             y=data.dependent_variable,
             granularity=granularity,
             allow_negative_predictions=data.allow_negative_predictions,
-            single_use_exog_prefixes=data.single_use_exog_prefixes,
+            single_use_exog_prefixes=data.single_use_exog_prefixes or [],
             exogs__disallow_negative_coefficient=data.get_disallowed_negative_coefficients(),
         )
         mvlr.do_analysis()
@@ -27,4 +28,7 @@ def find_best_mvlr(
             max_pvalues=data.validation_parameters.pvalues,
         ):
             return MultiVariableRegressionResult.from_mvlr(mvlr)
-    raise ValueError("No valid model found.")
+        best_rsquared = max(best_rsquared, mvlr.fit.rsquared_adj)
+    raise ValueError(
+        f"No valid model found. Best R²: {best_rsquared:.3f} (need ≥{data.validation_parameters.rsquared})"
+    )

{openenergyid-0.1.19.dist-info → openenergyid-0.1.21.dist-info}/METADATA

@@ -1,6 +1,6 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: openenergyid
-Version: 0.1.19
+Version: 0.1.21
 Summary: Open Source Python library for energy analytics and simulations
 Project-URL: Homepage, https://energyid.eu
 Project-URL: Repository, https://github.com/EnergieID/OpenEnergyID
@@ -47,4 +47,4 @@ Description-Content-Type: text/markdown
 
 Open Source Python library for energy data analytics and simulations
 
-[*more info for developers*](DEVELOPERS.md)
+[*more info for developers*](DEVELOPERS.md)

{openenergyid-0.1.19.dist-info → openenergyid-0.1.21.dist-info}/RECORD

@@ -1,14 +1,18 @@
-openenergyid/__init__.py,sha256=Rw7W-OZewpvJwVPQ0xjjsiXdeT-QpbmEmBER7arAMYo,193
+openenergyid/__init__.py,sha256=LOByZ5xMdSMme37T7DEKZJ_57qDoXhUNzP7uotgNx7w,193
 openenergyid/const.py,sha256=D-xUnUyVuLmphClkePgxpFP6z0RDhw_6m7rX0BHBgrw,823
 openenergyid/enums.py,sha256=jdw4CB1gkisx0re_SesrTEyh_T-UxYp6uieE7iYlHdA,357
-openenergyid/models.py,sha256=CO6VdthCOQ9hNXqVSan_4IOBpiQvOix-ea3U6TR7Vgc,4343
+openenergyid/models.py,sha256=IA6me6dsXH4mjBzewzHcs7U4jev07JX3pCadEcugeEI,5953
+openenergyid/baseload/__init__.py,sha256=LXgnCnoSB1fyknMvkAv8nbtYczqW8Od_N2v_bp-LYVw,437
+openenergyid/baseload/analysis.py,sha256=GAma3G3jE5ZZwxV3fL3lBlw3DDncXyAKgpB9XfNMibI,7520
+openenergyid/baseload/exceptions.py,sha256=uPPQlFmOikp3wuwdVxj3Mx-45TzPkLF86rKMFjT5qB4,250
+openenergyid/baseload/models.py,sha256=W_WCcdLdkbySH7o5adLE7_txXLZsAVTjJkwzjepwN1Y,917
 openenergyid/capacity/__init__.py,sha256=1En96HlPV8kd1hOJO9RjRbXNInp5ZSkmjsjp0jfZlcQ,221
 openenergyid/capacity/main.py,sha256=G6_EtXs1k_W-fxS33pFrCNKajuH81skdI32zp5RX9bI,3674
 openenergyid/capacity/models.py,sha256=qi0IFyF_QOVleSzN8g0U2Fzqcc9ZDfNKt8oteFLY6Q0,832
-openenergyid/dyntar/__init__.py,sha256=iQXQXrEQOiVNeeF6LRmUf3oOhKlGjMNF7o4T04IWTGA,371
-openenergyid/dyntar/const.py,sha256=17qL0-S0SImsqrDEDrGS2GLyJYcJRw6GmmcTiML7tR0,956
-openenergyid/dyntar/main.py,sha256=yRPamC5dHwpiDj07RM2iVKk3gZk8a81zKSjOsjewACo,8247
-openenergyid/dyntar/models.py,sha256=FZq7HI1F-3nVeHwPkuB38-8u32JzdvsZaCzrhirFD2g,2094
+openenergyid/dyntar/__init__.py,sha256=lUrk7ktS7yAqiafRHFoBE0RvFSI9mzDoO37diwLHuBg,495
+openenergyid/dyntar/const.py,sha256=eJJV9VfpHlS9vWV47DWQkS3ICIXWhDmG4cU-ofbZJ3Q,1100
+openenergyid/dyntar/main.py,sha256=i8EkayRicnMhG66cyrxGwUumFx3UGe7KDSImfFqmK04,10638
+openenergyid/dyntar/models.py,sha256=lI4IjdAFallhsCqbw-EbBPbmk0g2MACgZnmMtTX7Pq0,3452
 openenergyid/energysharing/__init__.py,sha256=A4JfrUYf-hBCzhUm0qL1GGlNMvpO8OwXJo80dJxFIvw,274
 openenergyid/energysharing/const.py,sha256=X2zEPtTlsmZ66w6RmLS_h8NmdzObAEi5N6-0yrLN5V4,219
 openenergyid/energysharing/data_formatting.py,sha256=Kwuhyn6ao_8Brdm9frlA6VzYOqimNYZsRbYwNXnE7yc,2583
@@ -16,10 +20,10 @@ openenergyid/energysharing/main.py,sha256=QKrtDyAlmKj0qtlqlUMjTJujQeKBK9U1_W80-R
 openenergyid/energysharing/models.py,sha256=-FedTqWqoi7AYrbI4S_pX0bMScrbZxncQ21CXFz2cXM,2526
 openenergyid/mvlr/__init__.py,sha256=Glrc218oqa8tq_Y2G9LXaSoN4Yba-vsjXUi9r9iPzaY,471
 openenergyid/mvlr/helpers.py,sha256=Uzbfrj3IpH26wA206KOl0hNucKE-n9guJNC_EROBVKA,983
-openenergyid/mvlr/main.py,sha256=cn7jZ98cHn2eh-0zG9q8Pad0Ft_FuI-u3a-eeHeF8jA,1304
+openenergyid/mvlr/main.py,sha256=Daj9UjcX70WETRrKu3QY-1LfMRkKP8Wvu4Ted-Smwzs,1491
 openenergyid/mvlr/models.py,sha256=XvkViOLlYqi0ffgF3AD4Jvk3yL05gsoKdKgBAsGJ7L4,8581
 openenergyid/mvlr/mvlr.py,sha256=F7WvWnZQtqUmK1vsguemsn9n8pDDk3tQ1weOlv-bo0c,18626
-openenergyid-0.1.19.dist-info/METADATA,sha256=q8cD0GQr7JDOoStIRDI8r5z-9gvgt4dkuh98vBDWJBw,2477
-openenergyid-0.1.19.dist-info/WHEEL,sha256=fl6v0VwpzfGBVsGtkAkhILUlJxROXbA3HvRL6Fe3140,105
-openenergyid-0.1.19.dist-info/licenses/LICENSE,sha256=NgRdcNHwyXVCXZ8sJwoTp0DCowThJ9LWWl4xhbV1IUY,1074
-openenergyid-0.1.19.dist-info/RECORD,,
+openenergyid-0.1.21.dist-info/METADATA,sha256=V1ysO8oMVbxB2ZTEOdHgXcG8P7erlagleMPPpe_efjc,2478
+openenergyid-0.1.21.dist-info/WHEEL,sha256=tkmg4JIqwd9H8mL30xA7crRmoStyCtGp0VWshokd1Jc,105
+openenergyid-0.1.21.dist-info/licenses/LICENSE,sha256=NgRdcNHwyXVCXZ8sJwoTp0DCowThJ9LWWl4xhbV1IUY,1074
+openenergyid-0.1.21.dist-info/RECORD,,

{openenergyid-0.1.19.dist-info → openenergyid-0.1.21.dist-info}/WHEEL

@@ -1,5 +1,5 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.25.0
+Generator: hatchling 1.27.0
 Root-Is-Purelib: true
 Tag: py2-none-any
 Tag: py3-none-any