openenergyid 0.1.21__py3-none-any.whl

openenergyid/energysharing/models.py

@@ -0,0 +1,79 @@
+"""Data models for energy sharing."""
+
+from enum import Enum
+from typing import Annotated, Any
+
+from pydantic import BaseModel, Field, confloat
+import pandas as pd
+
+from openenergyid import TimeDataFrame
+from .data_formatting import create_multi_index_input_frame
+from .const import NET_INJECTION, NET_OFFTAKE, SHARED_ENERGY
+
+
+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,164 @@
+"""Data models for the Open Energy ID."""
+
+import datetime as dt
+from typing import overload
+
+from typing import Self
+
+import pandas as pd
+from pydantic import BaseModel
+import polars as pl
+
+
+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.")
+
+
+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."""
+        return cls(name=str(data.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,
+    MultiVariableRegressionInput,
+    MultiVariableRegressionResult,
+    ValidationParameters,
+    IndependentVariableResult,
+)
+
+__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 .models import MultiVariableRegressionInput, MultiVariableRegressionResult
+from .helpers import resample_input_data
+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})"
+    )

openenergyid/mvlr/models.py

@@ -0,0 +1,228 @@
+"""Models for multivariable linear regression."""
+
+from typing import Any
+import pandas as pd
+
+from pydantic import BaseModel, Field, ConfigDict
+import statsmodels.formula.api as fm
+
+from openenergyid.enums import Granularity
+from openenergyid.models import TimeDataFrame
+
+from .mvlr import MultiVariableLinearRegression
+
+
+COLUMN_TEMPERATUREEQUIVALENT = "temperatureEquivalent"
+
+
+######################
+# MVLR Input Models #
+######################
+
+
+class ValidationParameters(BaseModel):
+    """Parameters for validation of a multivariable linear regression model."""
+
+    rsquared: float = Field(
+        0.75, ge=0, le=1, description="Minimum acceptable value for the adjusted R-squared"
+    )
+    f_pvalue: float = Field(
+        0.05, ge=0, le=1, description="Maximum acceptable value for the F-statistic"
+    )
+    pvalues: float = Field(
+        0.05, ge=0, le=1, description="Maximum acceptable value for the p-values of the t-statistic"
+    )
+
+
+class IndependentVariableInput(BaseModel):
+    """
+    Independent variable.
+
+    Has to corresponds to a column in the data frame.
+    """
+
+    name: str = Field(
+        description="Name of the independent variable. "
+        "If the name is `temperatureEquivalent`, "
+        "it will be unpacked into columns according to the variants."
+    )
+    variants: list[str] | None = Field(
+        default=None,
+        description="Variants of the `temperatureEquivalent` independent variable. "
+        "Eg. `HDD_16.5` will be Heating Degree Days with a base temperature of 16.5°C, "
+        "`CDD_0` will be Cooling Degree Days with a base temperature of 0°C.",
+    )
+    allow_negative_coefficient: bool = Field(
+        default=True,
+        alias="allowNegativeCoefficient",
+        description="Whether the coefficient can be negative.",
+    )
+
+
+class MultiVariableRegressionInput(BaseModel):
+    """Multi-variable regression input."""
+
+    timezone: str = Field(alias="timeZone")
+    independent_variables: list[IndependentVariableInput] = Field(
+        alias="independentVariables", min_length=1
+    )
+    dependent_variable: str = Field(alias="dependentVariable")
+    frame: TimeDataFrame
+    granularities: list[Granularity]
+    allow_negative_predictions: bool = Field(alias="allowNegativePredictions", default=False)
+    validation_parameters: ValidationParameters = Field(
+        alias="validationParameters", default=ValidationParameters()
+    )
+    single_use_exog_prefixes: list[str] | None = Field(
+        # default=["HDD", "CDD", "FDD"],
+        default=None,
+        alias="singleUseExogPrefixes",
+        description="List of prefixes to be used as single-use exogenous variables.",
+    )
+
+    def model_post_init(self, __context: Any) -> None:
+        """Post init hook."""
+        # Check if all independent variables are present in the data frame
+        for iv in self.independent_variables:  # pylint: disable=not-an-iterable
+            if iv.name not in self.frame.columns:
+                raise ValueError(f"Independent variable {iv.name} not found in the data frame.")
+
+        return super().model_post_init(__context)
+
+    def _data_frame(self) -> pd.DataFrame:
+        """Convert the data to a pandas DataFrame."""
+        return self.frame.to_pandas(timezone=self.timezone)
+
+    def data_frame(self) -> pd.DataFrame:
+        """
+        Return the data frame ready for analysis.
+
+        Unpacks degree days and removes unnecessary columns.
+
+        If an independent variable named `temperatureEquivalent` is present,
+        it will be unpacked into columns according to the variants.
+        Eg. Variant "HDD_16.5" will be Heating Degree Days
+        with a base temperature of 16.5°C,
+        "CDD_0" will be Cooling Degree Days with a base temperature of 0°C.
+        """
+        frame = self._data_frame()
+        columns_to_retain = [self.dependent_variable]
+        for iv in self.independent_variables:  # pylint: disable=not-an-iterable
+            if iv.name == COLUMN_TEMPERATUREEQUIVALENT and iv.variants is not None:
+                for variant in iv.variants:
+                    prefix, base_temperature = variant.split("_")
+                    if prefix == "CDD":
+                        frame[variant] = frame[COLUMN_TEMPERATUREEQUIVALENT] - float(
+                            base_temperature
+                        )
+                    else:
+                        frame[variant] = (
+                            float(base_temperature) - frame[COLUMN_TEMPERATUREEQUIVALENT]
+                        )
+                    frame[variant] = frame[variant].clip(lower=0)
+                    columns_to_retain.append(variant)
+                frame.drop(columns=[COLUMN_TEMPERATUREEQUIVALENT], inplace=True)
+            else:
+                columns_to_retain.append(iv.name)
+
+        frame = frame[columns_to_retain].copy()
+
+        return frame
+
+    def get_disallowed_negative_coefficients(self) -> list[str]:
+        """Get independent variables that are not allowed to have a negative coefficient."""
+        result = []
+        for iv in self.independent_variables:  # pylint: disable=not-an-iterable
+            if iv.name == COLUMN_TEMPERATUREEQUIVALENT and iv.variants is not None:
+                if not iv.allow_negative_coefficient:
+                    result.extend(iv.variants)
+            elif not iv.allow_negative_coefficient:
+                result.append(iv.name)
+        return result
+
+
+######################
+# MVLR Result Models #
+######################
+
+
+class ConfidenceInterval(BaseModel):
+    """Confidence interval for a coefficient."""
+
+    confidence: float = Field(ge=0, le=1)
+    lower: float
+    upper: float
+
+
+class IndependentVariableResult(BaseModel):
+    """Independent variable for a multivariable linear regression model."""
+
+    name: str
+    coef: float
+    t_stat: float | None = Field(default=None, alias="tStat")
+    p_value: float | None = Field(ge=0, le=1, default=None, alias="pValue")
+    std_err: float | None = Field(default=None, alias="stdErr")
+    confidence_interval: ConfidenceInterval | None = Field(default=None, alias="confidenceInterval")
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    @classmethod
+    def from_fit(cls, fit: fm.ols, name: str) -> "IndependentVariableResult":
+        """Create an IndependentVariable from a fit."""
+        return cls(
+            name=name,
+            coef=fit.params[name],
+            t_stat=fit.tvalues[name],
+            p_value=fit.pvalues[name],
+            std_err=fit.bse[name],
+            confidence_interval=ConfidenceInterval(
+                confidence=0.95,
+                lower=fit.conf_int().transpose()[name][0],
+                upper=fit.conf_int().transpose()[name][1],
+            ),
+        )
+
+
+class MultiVariableRegressionResult(BaseModel):
+    """Result of a multivariable regression model."""
+
+    dependent_variable: str = Field(alias="dependentVariable")
+    independent_variables: list[IndependentVariableResult] = Field(alias="independentVariables")
+    r2: float = Field(ge=0, le=1, alias="rSquared")
+    r2_adj: float = Field(ge=0, le=1, alias="rSquaredAdjusted")
+    f_stat: float = Field(ge=0, alias="fStat")
+    prob_f_stat: float = Field(ge=0, le=1, alias="probFStat")
+    intercept: IndependentVariableResult
+    granularity: Granularity
+    frame: TimeDataFrame
+
+    model_config = ConfigDict(populate_by_name=True)
+
+    @classmethod
+    def from_mvlr(cls, mvlr: MultiVariableLinearRegression) -> "MultiVariableRegressionResult":
+        """Create a MultiVariableRegressionResult from a MultiVariableLinearRegression."""
+
+        # Get independent variables
+        param_keys = mvlr.fit.params.keys().tolist()
+        param_keys.remove("Intercept")
+        independent_variables = []
+        for k in param_keys:
+            independent_variables.append(IndependentVariableResult.from_fit(mvlr.fit, k))
+
+        # Create resulting TimeSeries
+        cols_to_keep = list(param_keys)
+        cols_to_keep.append(mvlr.y)
+        cols_to_remove = list(filter(lambda v: v not in cols_to_keep, mvlr.data.columns.values))
+        frame = mvlr.data.drop(cols_to_remove, axis=1)
+
+        return cls(
+            dependent_variable=mvlr.y,
+            independent_variables=independent_variables,
+            r2=mvlr.fit.rsquared,
+            r2_adj=mvlr.fit.rsquared_adj,
+            f_stat=mvlr.fit.fvalue,
+            prob_f_stat=mvlr.fit.f_pvalue,
+            intercept=IndependentVariableResult.from_fit(mvlr.fit, "Intercept"),
+            granularity=mvlr.granularity,
+            frame=TimeDataFrame.from_pandas(frame),
+        )