openenergyid 0.1.31__py3-none-any.whl

openenergyid/energysharing/main.py

@@ -0,0 +1,122 @@
+"""Main Calcuation Module for Energy Sharing."""
+
+import pandas as pd
+
+from .const import (
+    GROSS_INJECTION,
+    GROSS_OFFTAKE,
+    KEY,
+    NET_INJECTION,
+    NET_OFFTAKE,
+    SHARED_ENERGY,
+)
+from .data_formatting import (
+    create_multi_index_output_frame,
+    result_to_input_for_reiteration,
+)
+from .models import CalculationMethod
+
+
+def _calculate(df: pd.DataFrame, method: CalculationMethod) -> pd.DataFrame:
+    """Calculate the energy sharing for the given input data. This function is not iterative."""
+    # Step 1: Calculate the maximum available gross injection that can be shared
+    # A participant cannot share their injection with themselves
+
+    # Take the injection of P1, and divide it per participant as per their key
+
+    injections_to_share = []
+    rest = {}
+
+    for participant in df[GROSS_INJECTION].columns:
+        injection_to_share = df[GROSS_INJECTION][participant].copy()
+
+        key = df[KEY].copy()
+        if method == CalculationMethod.RELATIVE or method == CalculationMethod.OPTIMAL:
+            # Set the key of the current participant to 0
+            # Re-normalize the keys for the other participants
+            if participant in df[KEY].columns:
+                key.loc[:, participant] = 0
+                key = key.div(key.sum(axis=1), axis=0)
+
+        # Multiply injection_to_share with the key of each participant
+        shared_by_participant = (injection_to_share * key.T).T
+        shared_by_participant.fillna(0, inplace=True)
+
+        # Set the value for the current participant to 0
+        if participant in shared_by_participant.columns:
+            shared_by_participant.loc[:, participant] = 0
+
+        # Put the not shared injection in the rest
+        rest[participant] = injection_to_share - shared_by_participant.sum(axis=1)
+
+        injections_to_share.append(shared_by_participant)
+
+    # Sum the injections to share
+    max_allocated_injection = sum(injections_to_share)
+
+    # Concat the rest
+    injection_that_cannot_be_shared = pd.concat(rest, axis=1)
+
+    # Step 2: Calculate the Net Offtake, by assigning the injections to each participant
+    # But, a participant cannot receive more than their offtake
+
+    net_offtake = df[GROSS_OFFTAKE] - max_allocated_injection
+
+    # Sum all negative values into a column "Not Shared"
+    not_shared_after_assignment = net_offtake.clip(upper=0).sum(axis=1).abs()
+
+    # Clip the values to 0
+    net_offtake = net_offtake.clip(lower=0)
+
+    # Calculate the amount of actual shared energy
+    # This is the difference between the gross offtake and the net offtake
+    shared_energy = df[GROSS_OFFTAKE] - net_offtake
+
+    # Step 3: Assign the Rests back to the original injectors
+
+    # The energy that is not shared after assignment
+    # should be divided back to the original injectors
+    # A ratio of the original injection should be used
+
+    re_distributed_not_shared = (
+        (df[GROSS_INJECTION].T / df[GROSS_INJECTION].sum(axis=1)) * not_shared_after_assignment
+    ).T
+    re_distributed_not_shared.fillna(0, inplace=True)
+
+    # The nett injection is the sum of:
+    # the injection that cannot be shared to begin with
+    # (because participants cannot share with themselves)
+    # and the injection that cannot be shared after assignment
+    # (because participants cannot receive more than their offtake)
+
+    net_injection = injection_that_cannot_be_shared + re_distributed_not_shared
+
+    result = create_multi_index_output_frame(
+        net_injection=net_injection, net_offtake=net_offtake, shared_energy=shared_energy
+    )
+
+    return result
+
+
+def calculate(df: pd.DataFrame, method: CalculationMethod) -> pd.DataFrame:
+    """Calculate the energy sharing for the given input data.
+
+    This function is iterative if the method is optimal."""
+    result = _calculate(df, method)
+
+    if method in [CalculationMethod.FIXED, CalculationMethod.RELATIVE]:
+        return result
+
+    # Optimal method, we iterate until the amount of shared energy is 0
+    final_result = result.copy()
+    while not result[SHARED_ENERGY].eq(0).all().all():
+        df = result_to_input_for_reiteration(result, df[KEY])
+        result = _calculate(df, method)
+
+        # Add the result to the final result
+        # Overwrite NET_INJECTION and NET_OFFTAKE, Sum SHARED_ENERGY
+        final_result[NET_INJECTION] = result[NET_INJECTION]
+        final_result[NET_OFFTAKE] = result[NET_OFFTAKE]
+        final_result[SHARED_ENERGY] += result[SHARED_ENERGY]
+
+    return final_result

openenergyid/energysharing/models.py

@@ -0,0 +1,80 @@
+"""Data models for energy sharing."""
+
+from enum import Enum
+from typing import Annotated, Any
+
+import pandas as pd
+from pydantic import BaseModel, Field, confloat
+
+from openenergyid import TimeDataFrame
+
+from .const import NET_INJECTION, NET_OFFTAKE, SHARED_ENERGY
+from .data_formatting import create_multi_index_input_frame
+
+
+class CalculationMethod(Enum):
+    """Calculation method for energy sharing."""
+
+    FIXED = "Fixed"
+    RELATIVE = "Relative"
+    OPTIMAL = "Optimal"
+
+
+class KeyInput(TimeDataFrame):
+    """Energy Sharing Keys."""
+
+    data: Annotated[
+        list[list[confloat(ge=0.0, le=1.0)]],  # type: ignore
+        Field(
+            description="Key data, column per participant. "
+            "Must be between 0 and 1. "
+            "Each row must sum to 1."
+        ),
+    ]
+
+    def model_post_init(self, __context: Any) -> None:
+        """Post-initialization validation."""
+        for row in self.data:
+            if round(sum(row), 3) != 1.0:
+                raise ValueError("Each row must sum to 1.")
+        return super().model_post_init(__context)
+
+
+class EnergySharingInput(BaseModel):
+    """Input data for energy sharing."""
+
+    gross_injection: Annotated[
+        TimeDataFrame,
+        Field(alias="grossInjection", description="Gross injection data, column per participant"),
+    ]
+    gross_offtake: Annotated[
+        TimeDataFrame,
+        Field(alias="grossOfftake", description="Gross offtake data, column per participant"),
+    ]
+    key: KeyInput
+
+    def to_pandas(self) -> pd.DataFrame:
+        """Return the data as a combined DataFrame"""
+        df = create_multi_index_input_frame(
+            gross_injection=self.gross_injection.to_pandas(),
+            gross_offtake=self.gross_offtake.to_pandas(),
+            key=self.key.to_pandas(),
+        )
+        return df
+
+
+class EnergySharingOutput(BaseModel):
+    """Output data for energy sharing."""
+
+    net_injection: TimeDataFrame = Field(alias="netInjection")
+    net_offtake: TimeDataFrame = Field(alias="netOfftake")
+    shared_energy: TimeDataFrame = Field(alias="sharedEnergy")
+
+    @classmethod
+    def from_calculation_result(cls, result: pd.DataFrame) -> "EnergySharingOutput":
+        """Create an output model from a calculation result."""
+        return cls.model_construct(
+            net_injection=TimeDataFrame.from_pandas(result[NET_INJECTION]),
+            net_offtake=TimeDataFrame.from_pandas(result[NET_OFFTAKE]),
+            shared_energy=TimeDataFrame.from_pandas(result[SHARED_ENERGY]),
+        )

openenergyid/enums.py

@@ -0,0 +1,16 @@
+"""Static enums for Open Energy ID."""
+
+from enum import Enum
+
+
+class Granularity(Enum):
+    """Granularity of a time series."""
+
+    P1Y = "P1Y"  # 1 year
+    P1M = "P1M"  # 1 month
+    P7D = "P7D"  # 7 days
+    P1D = "P1D"  # 1 day
+    PT1H = "PT1H"  # 1 hour
+    PT15M = "PT15M"  # 15 minutes
+    PT5M = "PT5M"  # 5 minutes
+    PT1M = "PT1M"  # 1 minute

openenergyid/models.py

@@ -0,0 +1,174 @@
+"""Data models for the Open Energy ID."""
+
+import datetime as dt
+from typing import Self, overload
+
+import pandas as pd
+import polars as pl
+from pydantic import BaseModel
+
+
+class TimeSeriesBase(BaseModel):
+    """Pydantic base model for time series data."""
+
+    index: list[dt.datetime]
+
+    @classmethod
+    def from_pandas(cls, data: pd.Series | pd.DataFrame) -> Self:
+        """Create from a Pandas Object."""
+        raise NotImplementedError
+
+    def to_pandas(self, timezone: str = "UTC") -> pd.Series | pd.DataFrame:
+        """Convert to a Pandas Object."""
+        raise NotImplementedError
+
+    @overload
+    def to_json(self, path: None = None, **kwargs) -> str:
+        """Dump to a JSON string."""
+
+    @overload
+    def to_json(self, path: str, **kwargs) -> None:
+        """Dump to a JSON file."""
+
+    def to_json(self, path: str | None = None, **kwargs) -> str | None:
+        """Dump to a JSON string or file."""
+        if path is None:
+            return self.model_dump_json(**kwargs)
+        encoding = kwargs.pop("encoding", "UTF-8")
+        with open(path, "w", encoding=encoding) as file:
+            file.write(self.model_dump_json(**kwargs))
+        return None
+
+    @overload
+    @classmethod
+    def from_json(cls, string: str, **kwargs) -> Self:
+        """Load from a JSON string."""
+
+    @overload
+    @classmethod
+    def from_json(cls, *, path: str, **kwargs) -> Self:
+        """Load from a JSON file."""
+
+    @classmethod
+    def from_json(cls, string: str | None = None, path: str | None = None, **kwargs) -> Self:
+        """Load from a JSON file or string."""
+        if string:
+            return cls.model_validate_json(string, **kwargs)
+        if path:
+            encoding = kwargs.pop("encoding", "UTF-8")
+            with open(path, encoding=encoding) as file:
+                return cls.model_validate_json(file.read(), **kwargs)
+        raise ValueError("Either string or path must be provided.")
+
+    def first_timestamp(self) -> dt.datetime:
+        """Get the first timestamp in the index."""
+        return min(self.index)
+
+    def last_timestamp(self) -> dt.datetime:
+        """Get the last timestamp in the index."""
+        return max(self.index)
+
+
+class TimeSeries(TimeSeriesBase):
+    """
+    Represents a time series data.
+    Attributes:
+        name (str | None): The name of the time series.
+        data (list[float | None]): The data points of the time series.
+    Methods:
+        replace_nan_with_none(cls, data: list[float]) -> list[float | None]:
+            Replace NaN values with None.
+        from_pandas(cls, data: pd.Series) -> Self:
+            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 | None]
+
+    @classmethod
+    def from_pandas(cls, data: pd.Series) -> Self:
+        """Create from a Pandas Series."""
+        if not hasattr(data, "name") or data.name is None:
+            name = None
+        else:
+            name = str(data.name)
+        return cls(name=name, data=data.tolist(), index=data.index.tolist())
+
+    def to_pandas(self, timezone: str = "UTC") -> pd.Series:
+        """Convert to a Pandas Series."""
+        series = pd.Series(self.data, name=self.name, index=self.index)
+        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 | None]]
+
+    @classmethod
+    def from_pandas(cls, data: pd.DataFrame) -> Self:
+        """Create from a Pandas DataFrame."""
+        # 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."""
+        frame = pd.DataFrame(self.data, columns=self.columns, index=self.index)
+        frame.index = pd.to_datetime(frame.index, utc=True)
+        return frame.tz_convert(timezone)
+
+    @classmethod
+    def from_timeseries(cls, data: list[TimeSeries]) -> Self:
+        """Create from a list of TimeSeries objects."""
+        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=col, data=[row[i] for row in self.data], index=self.index)
+            for i, col in enumerate(self.columns)
+        ]

openenergyid/mvlr/__init__.py

@@ -0,0 +1,19 @@
+"""Multi-variable linear regression (MVLR) module."""
+
+from .main import find_best_mvlr
+from .models import (
+    IndependentVariableInput,
+    IndependentVariableResult,
+    MultiVariableRegressionInput,
+    MultiVariableRegressionResult,
+    ValidationParameters,
+)
+
+__all__ = [
+    "find_best_mvlr",
+    "IndependentVariableInput",
+    "MultiVariableRegressionInput",
+    "MultiVariableRegressionResult",
+    "ValidationParameters",
+    "IndependentVariableResult",
+]

openenergyid/mvlr/helpers.py

@@ -0,0 +1,30 @@
+"""Miscelaneous helper functions for the MVLR app."""
+
+import pandas as pd
+
+from openenergyid.enums import Granularity
+
+pandas_granularity_map = {Granularity.P7D: "W-MON", Granularity.P1M: "MS", Granularity.P1D: "D"}
+
+
+def resample_input_data(
+    data: pd.DataFrame,
+    granularity: Granularity,
+    aggregation_methods: dict = None,
+) -> pd.DataFrame:
+    """Resample input data to the given granularity.
+
+    By default, the data is summed up for each column.
+    Provide a dictionary of aggregation methods to override this behaviour.
+    """
+    if granularity not in pandas_granularity_map:
+        raise NotImplementedError("Granularity not implemented.")
+    aggregation_methods = aggregation_methods.copy() if aggregation_methods else {}
+
+    for column in data.columns:
+        if column not in aggregation_methods:
+            aggregation_methods[column] = "sum"
+
+    return data.resample(rule=pandas_granularity_map[granularity]).agg(
+        aggregation_methods,
+    )

openenergyid/mvlr/main.py

@@ -0,0 +1,34 @@
+"""Main module for the MultiVariableLinearRegression class."""
+
+from .helpers import resample_input_data
+from .models import MultiVariableRegressionInput, MultiVariableRegressionResult
+from .mvlr import MultiVariableLinearRegression
+
+
+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)
+        mvlr = MultiVariableLinearRegression(
+            data=frame,
+            y=data.dependent_variable,
+            granularity=granularity,
+            allow_negative_predictions=data.allow_negative_predictions,
+            single_use_exog_prefixes=data.single_use_exog_prefixes or [],
+            exogs__disallow_negative_coefficient=data.get_disallowed_negative_coefficients(),
+        )
+        mvlr.do_analysis()
+        if mvlr.validate(
+            min_rsquared=data.validation_parameters.rsquared,
+            max_f_pvalue=data.validation_parameters.f_pvalue,
+            max_pvalues=data.validation_parameters.pvalues,
+        ):
+            return MultiVariableRegressionResult.from_mvlr(mvlr)
+        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})"
+    )