openenergyid 0.1.21__py3-none-any.whl

openenergyid/__init__.py

@@ -0,0 +1,8 @@
+"""Open Energy ID Python SDK."""
+
+__version__ = "0.1.21"
+
+from .enums import Granularity
+from .models import TimeDataFrame, TimeSeries
+
+__all__ = ["Granularity", "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/capacity/__init__.py

@@ -0,0 +1,6 @@
+"""Power Offtake peak analysis module."""
+
+from .models import CapacityInput, CapacityOutput, PeakDetail
+from .main import CapacityAnalysis
+
+__all__ = ["CapacityInput", "CapacityAnalysis", "CapacityOutput", "PeakDetail"]

openenergyid/capacity/main.py

@@ -0,0 +1,102 @@
+"""Main module for capacity analysis."""
+
+import datetime as dt
+import typing
+import pandas as pd
+import pandera.typing as pdt
+
+
+class CapacityAnalysis:
+    """
+    A class for performing capacity analysis on a given dataset.
+
+    Attributes:
+        data (CapacityInput): The input data for capacity analysis.
+        threshold (float): The value above which a peak is considered significant.
+        window (str): The window size for grouping data before finding peaks. Defaults to "MS" (month start).
+        x_padding (int): The padding to apply on the x-axis for visualization purposes.
+
+    Methods:
+        find_peaks(): Identifies peaks in the data based on the specified threshold and window.
+        find_peaks_with_surroundings(num_peaks=10): Finds peaks along with their surrounding data points.
+    """
+
+    def __init__(
+        self,
+        data: pdt.Series,
+        threshold: float = 2.5,
+        window: str = "MS",  # Default to month start
+        x_padding: int = 4,
+    ):
+        """
+        Constructs all the necessary attributes for the CapacityAnalysis object.
+
+        Parameters:
+            data (CapacityInput): Localized Pandas Series containing power measurements.
+            threshold (float): The value above which a peak is considered significant. Defaults to 2.5.
+            window (str): The window size for grouping data before finding peaks. Defaults to "MS" (month start).
+            x_padding (int): The padding to apply on the x-axis for visualization purposes. Defaults to 4.
+        """
+
+        self.data = data
+        self.threshold = threshold
+        self.window = window
+        self.x_padding = x_padding
+
+    def find_peaks(self) -> pd.Series:
+        """
+        Identifies peaks in the data based on the specified threshold and window.
+
+        Returns:
+            pd.Series: A Pandas Series containing the peaks
+        """
+        # Group by the specified window (default is month start)
+        grouped = self.data.groupby(pd.Grouper(freq=self.window))
+
+        # Find the index (timestamp) of the maximum value in each group
+        peak_indices = grouped.idxmax()
+
+        # Get the corresponding peak values
+        peaks = self.data.loc[peak_indices][self.data > self.threshold]
+        return peaks
+
+    def find_peaks_with_surroundings(
+        self, num_peaks: int = 10
+    ) -> list[tuple[dt.datetime, float, pd.Series]]:
+        """
+        Finds peaks along with their surrounding data points.
+
+        Parameters:
+            num_peaks (int): The number of peaks to find. Defaults to 10.
+
+        Returns:
+            List[tuple[dt.datetime,float,pd.Series]]: A list of tuples containing peak time, peak value, and surrounding data.
+        """
+        peaks = self.data.nlargest(num_peaks * 2)
+        peaks = peaks[peaks > self.threshold]
+        if peaks.empty:
+            return []
+
+        result = []
+        window_size = dt.timedelta(minutes=15 * (2 * self.x_padding + 1))
+
+        for peak_time, peak_value in peaks.items():
+            peak_time = typing.cast(pd.Timestamp, peak_time)
+
+            if any(abs(peak_time - prev_peak[0]) < window_size for prev_peak in result):
+                continue
+
+            start_time = peak_time - dt.timedelta(minutes=15 * self.x_padding)
+            end_time = peak_time + dt.timedelta(minutes=15 * (self.x_padding + 1))
+            surrounding_data = self.data[start_time:end_time]
+
+            result.append(
+                [
+                    peak_time,
+                    peak_value,
+                    surrounding_data,
+                ]
+            )
+            if len(result) == num_peaks:
+                break
+        return result

openenergyid/capacity/models.py

@@ -0,0 +1,30 @@
+"""Model for Capacity Analysis."""
+
+import datetime as dt
+from pydantic import BaseModel, ConfigDict, Field
+from openenergyid.models import TimeSeries
+
+
+class CapacityInput(BaseModel):
+    """Model for capacity input"""
+
+    timezone: str = Field(alias="timeZone")
+    series: TimeSeries
+    threshold: float = Field(default=2.5, ge=0)
+
+
+class PeakDetail(BaseModel):
+    """Model for peak detail"""
+
+    peak_time: dt.datetime = Field(alias="peakTime")
+    peak_value: float = Field(alias="peakValue")
+    surrounding_data: TimeSeries = Field(alias="surroundingData")
+    model_config = ConfigDict(populate_by_name=True)
+
+
+class CapacityOutput(BaseModel):
+    """Model for capacity output"""
+
+    peaks: TimeSeries
+    peak_details: list[PeakDetail] = Field(alias="peakDetails")
+    model_config = ConfigDict(populate_by_name=True)

openenergyid/const.py

@@ -0,0 +1,18 @@
+"""Constants for the Open Energy ID package."""
+
+from typing import Literal
+
+# METRICS
+
+ELECTRICITY_DELIVERED: Literal["electricity_delivered"] = "electricity_delivered"
+ELECTRICITY_EXPORTED: Literal["electricity_exported"] = "electricity_exported"
+ELECTRICITY_PRODUCED: Literal["electricity_produced"] = "electricity_produced"
+
+PRICE_DAY_AHEAD: Literal["price_day_ahead"] = "price_day_ahead"
+PRICE_IMBALANCE_UPWARD: Literal["price_imbalance_upward"] = "price_imbalance_upward"
+PRICE_IMBALANCE_DOWNWARD: Literal["price_imbalance_downward"] = "price_imbalance_downward"
+PRICE_ELECTRICITY_DELIVERED: Literal["price_electricity_delivered"] = "price_electricity_delivered"
+PRICE_ELECTRICITY_EXPORTED: Literal["price_electricity_exported"] = "price_electricity_exported"
+
+RLP: Literal["RLP"] = "RLP"
+SPP: Literal["SPP"] = "SPP"

openenergyid/dyntar/__init__.py

@@ -0,0 +1,20 @@
+"""Dynamic Tariff Analysis module."""
+
+from .main import calculate_dyntar_columns, summarize_result
+from .models import (
+    DynamicTariffAnalysisInput,
+    DynamicTariffAnalysisOutput,
+    DynamicTariffAnalysisOutputSummary,
+    OutputColumns,
+    RequiredColumns,
+)
+
+__all__ = [
+    "calculate_dyntar_columns",
+    "DynamicTariffAnalysisInput",
+    "DynamicTariffAnalysisOutput",
+    "DynamicTariffAnalysisOutputSummary",
+    "OutputColumns",
+    "RequiredColumns",
+    "summarize_result",
+]

openenergyid/dyntar/const.py

@@ -0,0 +1,31 @@
+"""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"
+ELECTRICITY_EXPORTED_SMR2 = "electricity_exported_smr2"
+
+COST_ELECTRICITY_DELIVERED_SMR2 = "cost_electricity_delivered_smr2"
+COST_ELECTRICITY_EXPORTED_SMR2 = "cost_electricity_exported_smr2"
+COST_ELECTRICITY_DELIVERED_SMR3 = "cost_electricity_delivered_smr3"
+COST_ELECTRICITY_EXPORTED_SMR3 = "cost_electricity_exported_smr3"
+
+RLP_WEIGHTED_PRICE_DELIVERED = "rlp_weighted_price_delivered"
+SPP_WEIGHTED_PRICE_EXPORTED = "spp_weighted_price_exported"
+
+HEATMAP_DELIVERED = "heatmap_delivered"
+HEATMAP_EXPORTED = "heatmap_exported"
+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"