energy_performance_indicator

energy_performance_indicator ¤

EnergyPerformanceIndicatorEvents ¤

EnergyPerformanceIndicatorEvents(
    dataframe: DataFrame,
    *,
    event_uuid: str = "energy:enpi",
    time_column: str = "systime",
    uuid_column: str = "uuid"
)

Bases: Base

Energy: Performance Indicator (EnPI) per ISO 50001

Calculate energy consumed per unit of production output (EnPI = kWh/unit). Tracks EnPI against a rolling baseline and identifies improvement/degradation trends. Supports comparison across multiple meters / production areas.

Supports two data models via constructor parameters:

Standard (ts-shape default)::

EnergyPerformanceIndicatorEvents(df)

expects: systime | uuid | value_double | value_integer¤
Raw CSV::

EnergyPerformanceIndicatorEvents(df, time_column="time", uuid_column="id")

Methods: - enpi_by_window: EnPI (energy / units) per time window. - enpi_vs_baseline: EnPI vs rolling baseline with anomaly flags. - enpi_by_hierarchy: EnPI across multiple meters for area comparison.

enpi_by_window ¤

enpi_by_window(
    meter_uuid: str,
    counter_uuid: str,
    *,
    value_column_energy: str = "value_double",
    value_column_counter: str = "value_integer",
    window: str = "1D",
    handle_resets: bool = True
) -> pd.DataFrame

Calculate energy per unit produced (EnPI) for each time window.

Parameters:

Name	Type	Description	Default
`meter_uuid`	`str`	Identifier of the energy meter signal.	required
`counter_uuid`	`str`	Identifier of the production counter signal.	required
`value_column_energy`	`str`	Column containing energy readings.	`'value_double'`
`value_column_counter`	`str`	Column containing counter readings.	`'value_integer'`
`window`	`str`	Aggregation window (e.g. '1D', '1h', '1W').	`'1D'`
`handle_resets`	`bool`	`True` (default) treats a decreasing production counter as a reset and sums reset-aware increments per window (see :func:`ts_shape.utils.counters.counter_per_window`), so a window with a reset still reports what was produced. `False` uses the per-window `max - min`.	`True`

Returns:

Name	Type	Description
`DataFrame`	`DataFrame`	start, end, duration_seconds, uuid, source_uuid, is_delta, energy_kwh, units_produced, enpi. `end` is `start` plus `window`.

enpi_vs_baseline ¤

enpi_vs_baseline(
    meter_uuid: str,
    counter_uuid: str,
    *,
    value_column_energy: str = "value_double",
    value_column_counter: str = "value_integer",
    window: str = "1D",
    handle_resets: bool = True,
    baseline_window: int = 30,
    deviation_threshold: float = 0.1,
    baseline: str = "rolling",
    baseline_period: (
        tuple[str | Timestamp, str | Timestamp] | None
    ) = None
) -> pd.DataFrame

Compare current EnPI against a baseline.

baseline="rolling" (default) compares each window with the EnPI of the preceding baseline_window windows (itself included) taken as one period: their summed energy over their summed output (ISO 50006), not the mean of the per-window EnPI values, which over-weights low-output windows. A rolling baseline drifts with the process, so it never shows a lasting improvement, and kWh/unit is biased by load: a fixed base load makes EnPI look worse whenever output is low.

baseline="regression" is the ISO 50006 energy baseline: fit energy = a + b * units on a fixed baseline period, then compare each window's energy with what the model expects for its output. baseline_enpi is that expected energy per unit and deviation_pct is (actual - expected) / expected energy, so the comparison is normalized for production volume. Two columns are added: expected_energy_kwh and energy_savings_kwh (expected - actual; its cumulative sum is the CUSUM of savings).

Parameters:

Name	Type	Description	Default
`meter_uuid`	`str`	Identifier of the energy meter signal.	required
`counter_uuid`	`str`	Identifier of the production counter signal.	required
`value_column_energy`	`str`	Column containing energy readings.	`'value_double'`
`value_column_counter`	`str`	Column containing counter readings.	`'value_integer'`
`window`	`str`	Aggregation window.	`'1D'`
`baseline_window`	`int`	Number of windows for rolling baseline.	`30`
`deviation_threshold`	`float`	Fractional deviation to flag as anomaly (0.1 = 10%).	`0.1`
`baseline`	`str`	`"rolling"` or `"regression"` (see above).	`'rolling'`
`baseline_period`	`tuple[str \| Timestamp, str \| Timestamp] \| None`	`(start, end)` of the regression baseline period, end exclusive. Default: the first `baseline_window` windows.	`None`
`handle_resets`	`bool`	`True` (default) treats a decreasing production counter as a reset and sums reset-aware increments per window (see :func:`ts_shape.utils.counters.counter_per_window`), so a window with a reset still reports what was produced. `False` uses the per-window `max - min`.	`True`

Returns:

Name	Type	Description
`DataFrame`	`DataFrame`	start, end, duration_seconds, uuid, source_uuid, enpi, baseline_enpi, deviation_pct, is_anomaly, trend

enpi_by_hierarchy ¤

enpi_by_hierarchy(
    meter_uuids: list[str],
    counter_uuid: str,
    *,
    value_column_energy: str = "value_double",
    value_column_counter: str = "value_integer",
    window: str = "1D",
    handle_resets: bool = True
) -> pd.DataFrame

Calculate EnPI per meter for cross-area comparison.

Useful for comparing energy intensity across production lines, buildings, or hierarchy levels. Combine with series metadata to map meter_uuid to label_lvl / hierarchy columns.

Parameters:

Name	Type	Description	Default
`meter_uuids`	`list[str]`	List of energy meter identifiers.	required
`counter_uuid`	`str`	Shared production counter identifier.	required
`value_column_energy`	`str`	Column containing energy readings.	`'value_double'`
`value_column_counter`	`str`	Column containing counter readings.	`'value_integer'`
`window`	`str`	Aggregation window.	`'1D'`
`handle_resets`	`bool`	`True` (default) treats a decreasing production counter as a reset and sums reset-aware increments per window (see :func:`ts_shape.utils.counters.counter_per_window`), so a window with a reset still reports what was produced. `False` uses the per-window `max - min`.	`True`

Returns:

Name	Type	Description
`DataFrame`	`DataFrame`	start, end, duration_seconds, meter_uuid, energy_kwh, units_produced, enpi

energy_performance_indicator