openenergyid 0.1.31__py3-none-any.whl

openenergyid/dyntar/main.py

@@ -0,0 +1,313 @@
+"""Main module of the DynTar package."""
+
+from typing import cast
+
+import pandas as pd
+
+from openenergyid.const import (
+    ELECTRICITY_DELIVERED,
+    ELECTRICITY_EXPORTED,
+    PRICE_ELECTRICITY_DELIVERED,
+    PRICE_ELECTRICITY_EXPORTED,
+    RLP,
+    SPP,
+)
+
+from .const import (
+    COST_ELECTRICITY_DELIVERED_SMR2,
+    COST_ELECTRICITY_DELIVERED_SMR3,
+    COST_ELECTRICITY_EXPORTED_SMR2,
+    COST_ELECTRICITY_EXPORTED_SMR3,
+    ELECTRICITY_DELIVERED_SMR2,
+    ELECTRICITY_DELIVERED_SMR3,
+    ELECTRICITY_EXPORTED_SMR2,
+    ELECTRICITY_EXPORTED_SMR3,
+    HEATMAP_DELIVERED,
+    HEATMAP_DELIVERED_DESCRIPTION,
+    HEATMAP_EXPORTED,
+    HEATMAP_EXPORTED_DESCRIPTION,
+    HEATMAP_TOTAL,
+    HEATMAP_TOTAL_DESCRIPTION,
+    RLP_WEIGHTED_PRICE_DELIVERED,
+    SPP_WEIGHTED_PRICE_EXPORTED,
+    Register,
+)
+
+
+def weigh_by_monthly_profile(df: pd.DataFrame, series_name, profile_name) -> pd.Series:
+    """Weigh a time series by a monthly profile."""
+    grouped = df.groupby(pd.Grouper(freq="MS"))
+    return grouped[series_name].transform("sum") * grouped[profile_name].transform(
+        lambda x: x / x.sum()
+    )
+
+
+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
+
+    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={
+            ELECTRICITY_DELIVERED: ELECTRICITY_DELIVERED_SMR3,
+            ELECTRICITY_EXPORTED: ELECTRICITY_EXPORTED_SMR3,
+        },
+        inplace=True,
+        errors="ignore",
+    )
+
+    if not inplace:
+        return result_df
+    return 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
+
+    if registers is None:
+        registers = [Register.DELIVERY, Register.EXPORT]
+
+    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
+    return None
+
+
+def extend_dataframe_with_weighted_prices(
+    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()
+
+    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, registers: list[Register] | None = None
+) -> pd.DataFrame | None:
+    """Extend a DataFrame with the heatmap columns."""
+    if not inplace:
+        df = df.copy()
+
+    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:
+        return df
+    return None
+
+
+def map_delivery_description(
+    price_delivered, price_rlp, electricity_delivered_smr3, electricity_delivered_smr2
+):
+    """Map the delivery description."""
+    if price_delivered > price_rlp and electricity_delivered_smr3 > electricity_delivered_smr2:
+        return 1
+    if price_delivered > price_rlp and electricity_delivered_smr3 < electricity_delivered_smr2:
+        return 2
+    if price_delivered < price_rlp and electricity_delivered_smr3 > electricity_delivered_smr2:
+        return 3
+    if price_delivered < price_rlp and electricity_delivered_smr3 < electricity_delivered_smr2:
+        return 4
+    return 0
+
+
+def map_export_description(
+    price_exported, price_spp, electricity_exported_smr3, electricity_exported_smr2
+):
+    """Map the export description."""
+    if price_exported > price_spp and electricity_exported_smr3 > electricity_exported_smr2:
+        return 5
+    if price_exported > price_spp and electricity_exported_smr3 < electricity_exported_smr2:
+        return 6
+    if price_exported < price_spp and electricity_exported_smr3 > electricity_exported_smr2:
+        return 7
+    if price_exported < price_spp and electricity_exported_smr3 < electricity_exported_smr2:
+        return 8
+    return 0
+
+
+def map_total_description(
+    abs_heatmap_delivered, abs_heatmap_exported, delivered_description, exported_description
+):
+    """Map the total description."""
+    if abs_heatmap_delivered > abs_heatmap_exported:
+        return delivered_description
+    return exported_description
+
+
+def extend_dataframe_with_heatmap_description(
+    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()
+
+    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],
+            )
+        )
+
+    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],
+            )
+        )
+
+    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,
+    registers: list[Register] | None = None,
+) -> pd.DataFrame | None:
+    """Calculate all columns required for the dynamic tariff analysis."""
+    if not inplace:
+        df = df.copy()
+
+    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

@@ -0,0 +1,101 @@
+"""Models for dynamic tariff analysis."""
+
+from typing import Literal
+
+from pydantic import BaseModel, Field, confloat, conlist
+
+from openenergyid.models import TimeDataFrame
+
+from .const import Register
+
+RequiredColumns = Literal[
+    "electricity_delivered",
+    "electricity_exported",
+    "price_electricity_delivered",
+    "price_electricity_exported",
+    "RLP",
+    "SPP",
+]
+
+OutputColumns = Literal[
+    "electricity_delivered_smr3",
+    "electricity_exported_smr3",
+    "price_electricity_delivered",
+    "price_electricity_exported",
+    "RLP",
+    "SPP",
+    "electricity_delivered_smr2",
+    "electricity_exported_smr2",
+    "cost_electricity_delivered_smr2",
+    "cost_electricity_exported_smr2",
+    "cost_electricity_delivered_smr3",
+    "cost_electricity_exported_smr3",
+    "rlp_weighted_price_delivered",
+    "spp_weighted_price_exported",
+    "heatmap_delivered",
+    "heatmap_exported",
+    "heatmap_total",
+    "heatmap_delivered_description",
+    "heatmap_exported_description",
+    "heatmap_total_description",
+]
+
+
+class DynamicTariffAnalysisInput(TimeDataFrame):
+    """Input frame for dynamic tariff analysis."""
+
+    columns: list[RequiredColumns] = Field(
+        min_length=3,
+        max_length=len(RequiredColumns.__args__),
+        examples=[RequiredColumns.__args__],
+    )
+    data: list[
+        conlist(
+            item_type=confloat(allow_inf_nan=True),
+            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."""
+
+    columns: list[str]
+    data: list[list[float | None]]
+    summary: DynamicTariffAnalysisOutputSummary | None = None

openenergyid/elia/__init__.py

@@ -0,0 +1,4 @@
+from .api import get_dataset, parse_response
+from .const import Region
+
+__all__ = ["get_dataset", "parse_response", "Region"]

openenergyid/elia/api.py

@@ -0,0 +1,91 @@
+"""
+This module contains the functions to interact with the Elia API.
+"""
+
+import datetime as dt
+
+import aiohttp
+import pandas as pd
+
+from .const import Region
+
+DATE_FORMAT = "%Y-%m-%d"
+
+
+async def get_dataset(
+    dataset: str,
+    start: dt.date,
+    end: dt.date,
+    region: Region,
+    select: set[str],
+    session: aiohttp.ClientSession,
+    timezone: str = "Europe/Brussels",
+) -> dict:
+    """
+    Fetches a dataset from the Elia open data API within a specified date range and region.
+
+    Args:
+        dataset (str): The name of the dataset to fetch.
+        start (dt.date): The start date for the data range.
+        end (dt.date): The end date for the data range.
+        region (Region): The region for which to fetch the data.
+        select (set[str]): A set of fields to select in the dataset.
+        session (aiohttp.ClientSession): The aiohttp session to use for making the request.
+        timezone (str, optional): The timezone to use for the data. Defaults to "Europe/Brussels".
+
+    Returns:
+        dict: The dataset fetched from the API.
+
+    Raises:
+        aiohttp.ClientError: If there is an error making the request.
+    """
+    url = f"https://opendata.elia.be/api/explore/v2.1/catalog/datasets/{dataset}/exports/json"
+
+    if "datetime" not in select:
+        select.add("datetime")
+    select_str = ",".join(select)
+
+    params = {
+        "where": (
+            f"datetime IN [date'{start.strftime(DATE_FORMAT)}'..date'{end.strftime(DATE_FORMAT)}'] "
+            f"AND region='{region.value}'"
+        ),
+        "timezone": timezone,
+        "select": select_str,
+    }
+
+    async with session.get(url, params=params) as response:
+        data = await response.json()
+
+    return data
+
+
+def parse_response(
+    data: dict, index: str, columns: list[str], timezone: str = "Europe/Brussels"
+) -> pd.DataFrame:
+    """
+    Parses a response dictionary into a pandas DataFrame.
+
+    Args:
+        data (dict): The input data where each key is a column name
+            and each value is a list of column values.
+        index (str): The key in the data dictionary to be used as the index for the DataFrame.
+        columns (list[str]): The list of column names for the DataFrame.
+        timezone (str, optional): The timezone to convert the DataFrame index to.
+            Defaults to "Europe/Brussels".
+
+    Returns:
+        pd.DataFrame: A pandas DataFrame with the specified columns and index,
+            converted to the specified timezone.
+    """
+    df = pd.DataFrame(
+        data,
+        index=pd.to_datetime([x[index] for x in data], utc=True),
+        columns=columns,
+    )
+    df.index = pd.DatetimeIndex(df.index)
+    df = df.tz_convert(timezone)
+    df.sort_index(inplace=True)
+    df.dropna(inplace=True)
+
+    return df

openenergyid/elia/const.py

@@ -0,0 +1,18 @@
+from enum import Enum
+
+
+class Region(Enum):
+    Belgium = "Belgium"
+    Brussels = "Brussels"
+    Flanders = "Flanders"
+    Wallonia = "Wallonia"
+    Antwerp = "Antwerp"
+    East_Flanders = "East-Flanders"
+    Flemish_Brabant = "Flemish-Brabant"
+    Limburg = "Limburg"
+    West_Flanders = "West-Flanders"
+    Hainaut = "Hainaut"
+    Liège = "Liège"
+    Luxembourg = "Luxembourg"
+    Namur = "Namur"
+    Walloon_Brabant = "Walloon-Brabant"

openenergyid/energysharing/__init__.py

@@ -0,0 +1,12 @@
+"""Energy Sharing package."""
+
+from .main import calculate
+from .models import CalculationMethod, EnergySharingInput, EnergySharingOutput, KeyInput
+
+__all__ = [
+    "calculate",
+    "CalculationMethod",
+    "EnergySharingInput",
+    "EnergySharingOutput",
+    "KeyInput",
+]

openenergyid/energysharing/const.py

@@ -0,0 +1,8 @@
+"""Constants for the energysharing module."""
+
+GROSS_INJECTION = "Gross Injection"
+NET_INJECTION = "Net Injection"
+GROSS_OFFTAKE = "Gross Offtake"
+NET_OFFTAKE = "Net Offtake"
+KEY = "Key"
+SHARED_ENERGY = "Shared Energy"

openenergyid/energysharing/data_formatting.py

@@ -0,0 +1,77 @@
+"""Functions to create multi-indexed DataFrames for input and output data for energy sharing."""
+
+import pandas as pd
+
+from .const import (
+    GROSS_INJECTION,
+    GROSS_OFFTAKE,
+    KEY,
+    NET_INJECTION,
+    NET_OFFTAKE,
+    SHARED_ENERGY,
+)
+
+
+def create_multi_index_input_frame(
+    gross_injection: pd.DataFrame,
+    gross_offtake: pd.DataFrame,
+    key: pd.DataFrame,
+) -> pd.DataFrame:
+    """Create a multi-indexed DataFrame with the input data for energy sharing."""
+    gross_injection = gross_injection.copy()
+    gross_offtake = gross_offtake.copy()
+    key = key.copy()
+
+    gross_injection.columns = pd.MultiIndex.from_product(
+        [[GROSS_INJECTION], gross_injection.columns]
+    )
+    gross_offtake.columns = pd.MultiIndex.from_product([[GROSS_OFFTAKE], gross_offtake.columns])
+    key.columns = pd.MultiIndex.from_product([[KEY], key.columns])
+
+    df = pd.concat([gross_injection, gross_offtake, key], axis=1)
+
+    return df
+
+
+def create_multi_index_output_frame(
+    net_injection: pd.DataFrame,
+    net_offtake: pd.DataFrame,
+    shared_energy: pd.DataFrame,
+) -> pd.DataFrame:
+    """Create a multi-indexed DataFrame with the output data for energy sharing."""
+    net_injection = net_injection.copy()
+    net_offtake = net_offtake.copy()
+    shared_energy = shared_energy.copy()
+
+    net_injection.columns = pd.MultiIndex.from_product([[NET_INJECTION], net_injection.columns])
+    net_offtake.columns = pd.MultiIndex.from_product([[NET_OFFTAKE], net_offtake.columns])
+    shared_energy.columns = pd.MultiIndex.from_product([[SHARED_ENERGY], shared_energy.columns])
+
+    df = pd.concat([net_injection, net_offtake, shared_energy], axis=1)
+
+    return df
+
+
+def result_to_input_for_reiteration(result: pd.DataFrame, key: pd.DataFrame) -> pd.DataFrame:
+    """Create a multi-indexed DataFrame with the input data for energy sharing after the first iteration."""
+    # We iterate again. The net injection of the previous result is taken as gross injection input
+    # And the net offtake is taken as the gross offtake input
+    # When a user's net offtake is 0, the key is set to 0; and the keys are re-normalized
+
+    gross_injection = result[NET_INJECTION].copy()
+    gross_offtake = result[NET_OFFTAKE].copy()
+
+    # Take the original key, but replace the value with 0.0 if result[NET_OFFTAKE] is 0.0
+
+    key = key.copy()
+    key = key.where(~result[NET_OFFTAKE].eq(0), 0)
+
+    # Re-normalize the keys
+
+    key = key.div(key.sum(axis=1), axis=0)
+
+    df = create_multi_index_input_frame(
+        gross_injection=gross_injection, gross_offtake=gross_offtake, key=key
+    )
+
+    return df