openenergyid 0.1.20__tar.gz → 0.1.28__tar.gz

openenergyid-0.1.28/PKG-INFO

@@ -0,0 +1,41 @@
+Metadata-Version: 2.3
+Name: openenergyid
+Version: 0.1.28
+Summary: Open Source Python library for energy analytics and simulations
+License: MIT
+Keywords: energy,analytics,simulation
+Author: Jan Pecinovsky
+Author-email: jan@energieid.be
+Requires-Python: >=3.11,<4.0
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Natural Language :: English
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Mathematics
+Classifier: Topic :: Scientific/Engineering :: Physics
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Dist: numpy (>=2.0.0,<3.0.0)
+Requires-Dist: pandas (>=2.2.2,<3.0.0)
+Requires-Dist: pandera[polars] (>=0.22.1,<0.23.0)
+Requires-Dist: patsy (>=0.5.6,<0.6.0)
+Requires-Dist: polars (>=1.9.0,<2.0.0)
+Requires-Dist: pydantic (>=2.8.2,<3.0.0)
+Requires-Dist: statsmodels (>=0.14.2,<0.15.0)
+Project-URL: Documentation, https://github.com/EnergieID/OpenEnergyID
+Project-URL: Homepage, https://energyid.eu
+Project-URL: Repository, https://github.com/EnergieID/OpenEnergyID
+Description-Content-Type: text/markdown
+
+# OpenEnergyID
+
+Open Source Python library for energy data analytics and simulations
+
+[*more info for developers*](DEVELOPERS.md)
+

{openenergyid-0.1.20 → openenergyid-0.1.28}/README.md

@@ -2,4 +2,4 @@
 
 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.20 → openenergyid-0.1.28}/openenergyid/__init__.py

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

openenergyid-0.1.28/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-0.1.28/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-0.1.28/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-0.1.28/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-0.1.20 → openenergyid-0.1.28}/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-0.1.20 → openenergyid-0.1.28}/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.20 → openenergyid-0.1.28}/pyproject.toml

@@ -1,18 +1,21 @@
 [build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
+requires = ["poetry-core>=1.0.0"]
+build-backend = "poetry.core.masonry.api"
 
-[project]
-dynamic = ["version"]
+[tool.poetry]
 name = "openenergyid"
+version = "0.1.28"
+description = "Open Source Python library for energy analytics and simulations"
 authors = [
-    { name = "Jan Pecinovsky", email = "jan@energieid.be" },
-    { name = "Max Helskens", email = "max@energieid.be" },
+    "Jan Pecinovsky <jan@energieid.be>",
+    "Max Helskens <max@energieid.be>",
+    "Oscar Swyns <oscar@energieid.be>"
 ]
-maintainers = [{ name = "Jan Pecinovsky", email = "jan@energieid.be" }]
-description = "Open Source Python library for energy analytics and simulations"
 readme = "README.md"
-license = { file = "LICENSE" }
+license = "MIT"
+homepage = "https://energyid.eu"
+repository = "https://github.com/EnergieID/OpenEnergyID"
+documentation = "https://github.com/EnergieID/OpenEnergyID"
 keywords = ["energy", "analytics", "simulation"]
 classifiers = [
     "Development Status :: 3 - Alpha",
@@ -25,37 +28,18 @@ classifiers = [
     "Topic :: Scientific/Engineering",
     "Topic :: Scientific/Engineering :: Mathematics",
     "Topic :: Scientific/Engineering :: Physics",
-    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Software Development :: Libraries :: Python Modules"
 ]
 
-[project.urls]
-Homepage = "https://energyid.eu"
-Repository = "https://github.com/EnergieID/OpenEnergyID"
-"Bugs Tracker" = "https://github.com/EnergieID/OpenEnergyID/issues"
-
-[tool.hatch.version]
-path = "openenergyid/__init__.py"
-
-[tool.ruff]
-line-length = 100
-
-[tool.poetry]
-name = "openenergyid"
-version = "0.1.20" # You'll need to set this manually or use a different method for dynamic versioning
-description = "Open Source Python library for energy analytics and simulations"
-authors = [
-    "Jan Pecinovsky <jan@energieid.be>",
-    "Max Helskens <max@energieid.be>",
-    "Oscar Swyns <oscar@energieid.be>",
-]
-dependencies.python = "^3.10"
-dependencies.polars = "^1.9.0"
-dependencies.pandera = "^0.20.3"
-dependencies.numpy = "^2.0.0"
-dependencies.patsy = "^0.5.6"
-dependencies.statsmodels = "^0.14.2"
-dependencies.pydantic = "^2.8.2"
-dependencies.pandas = "^2.2.2"
+[tool.poetry.dependencies]
+python = "^3.11"
+polars = "^1.9.0"
+numpy = "^2.0.0"
+patsy = "^0.5.6"
+statsmodels = "^0.14.2"
+pydantic = "^2.8.2"
+pandas = "^2.2.2"
+pandera = {extras = ["polars"], version = "^0.22.1"}
 
 [tool.poetry.group.dev.dependencies]
 altair = "^5.4.1"
@@ -68,3 +52,14 @@ entsoe-py = "^0.6.8"
 energyid = "^0.0.17"
 snakeviz = "^2.2.0"
 plotly = "^5.24.1"
+vegafusion = {version = ">=1.5.0", extras = ["embed"]}
+vl-convert-python = "^1.7.0"
+pyarrow = "^19.0.0"
+pyinstrument = "^5.0.0"
+deptry = "^0.23.0"
+
+[tool.poetry.requires-plugins]
+poetry-plugin-export = ">=1.8"
+
+[tool.ruff]
+line-length = 100

openenergyid-0.1.20/.devcontainer/devcontainer.json

@@ -1,39 +0,0 @@
-{
-  "name": "Python 3",
-  "image": "mcr.microsoft.com/devcontainers/python:1.1.9-3.11-bookworm",
-  "features": {},
-  "postCreateCommand": "zsh -l .devcontainer/post-install.sh",
-  // "postStartCommand": "",
-  "remoteUser": "root",
-  "customizations": {
-    "vscode": {
-      "extensions": [
-        "ms-toolsai.jupyter",
-        "charliermarsh.ruff",
-        "ms-python.pylint",
-        "ms-python.vscode-pylance",
-        "visualstudioexptteam.vscodeintellicode",
-        "esbenp.prettier-vscode",
-        "GitHub.vscode-pull-request-github",
-        "mhutchie.git-graph"
-      ],
-      "settings": {
-        "python.pythonPath": "/usr/local/bin/python",
-        "python.testing.pytestArgs": ["--no-cov"],
-        "editor.formatOnPaste": false,
-        "editor.formatOnSave": true,
-        "editor.formatOnType": true,
-        "files.trimTrailingWhitespace": true,
-        "terminal.integrated.profiles.linux": {
-          "zsh": {
-            "path": "/usr/bin/zsh"
-          }
-        },
-        "terminal.integrated.defaultProfile.linux": "zsh",
-        "[python]": {
-          "editor.defaultFormatter": "charliermarsh.ruff"
-        }
-      }
-    }
-  }
-}

openenergyid-0.1.20/.devcontainer/post-install.sh

@@ -1,24 +0,0 @@
-#!/bin/zsh -l
-# Add the current directory to Git's safe directory list
-git config --global --add safe.directory /workspaces/OpenEnergyID
-
-# Install Python tools
-pipx install ruff poetry pre-commit
-
-# Install project dependencies using Poetry
-poetry install
-
-# Install pre-commit hooks
-pre-commit install
-
-# Install Node.js and Pure prompt
-# nvm install node
-# npm install --global pure-prompt
-
-# # Configure Zsh to use Pure prompt
-# "autoload -U promptinit; promptinit; prompt pure"
-# "echo "autoload -U promptinit; promptinit; prompt pure" >> ~/.zshrc"
-
-# # Uncomment the following line to install zsh-syntax-highlighting
-# # sudo apt-get install zsh-syntax-highlighting
-# # echo "source /usr/share/zsh-syntax-highlighting/zsh-syntax-highlighting.zsh" >> ${ZDOTDIR:-$HOME}/.zshrc

openenergyid-0.1.20/.github/workflows/python-publish.yml

@@ -1,39 +0,0 @@
-# This workflow will upload a Python Package using Twine when a release is created
-# For more information see: https://docs.github.com/en/actions/automating-builds-and-tests/building-and-testing-python#publishing-to-package-registries
-
-# This workflow uses actions that are not certified by GitHub.
-# They are provided by a third-party and are governed by
-# separate terms of service, privacy policy, and support
-# documentation.
-
-name: Upload Python Package
-
-on:
-  release:
-    types: [published]
-
-permissions:
-  contents: read
-
-jobs:
-  deploy:
-    runs-on: ubuntu-latest
-    permissions:
-        id-token: write
-    environment: release
-
-    steps:
-    - uses: actions/checkout@v3
-    - name: Set up Python
-      uses: actions/setup-python@v3
-      with:
-        python-version: '3.x'
-    - name: Install dependencies
-      run: |
-        python -m pip install --upgrade pip
-        pip install build
-    - name: Build package
-      run: python -m build
-    - name: Publish package
-      uses: pypa/gh-action-pypi-publish@release/v1
-      

openenergyid-0.1.20/.github/workflows/ruff.yml

@@ -1,8 +0,0 @@
-name: Ruff
-on: [push, pull_request]
-jobs:
-  ruff:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-      - uses: chartboost/ruff-action@v1