Skip to content

init

energy ¤

Energy Events

Detectors for energy-related patterns: consumption analysis, efficiency tracking, idle waste detection, EnPI, and carbon intensity on manufacturing and industrial IoT time series data.

All classes accept both the standard ts-shape schema (systime | uuid | value_*) and the raw CSV model (time | id | value) via time_column and uuid_column constructor parameters.

  • EnergyConsumptionEvents: Analyze energy consumption patterns.
  • consumption_by_window: Aggregate energy consumption per time window.
  • peak_demand_detection: Detect peak demand periods exceeding thresholds.
  • consumption_baseline_deviation: Compare actual vs baseline consumption.
  • energy_per_unit: Calculate energy consumption per production unit.
  • normalize: Convert raw CSV DataFrame to standard schema.

  • EnergyEfficiencyEvents: Track energy efficiency metrics.

  • efficiency_trend: Rolling efficiency metric over time.
  • idle_energy_waste: Detect energy consumption during idle periods.
  • specific_energy_consumption: Energy per unit output over time.
  • efficiency_comparison: Compare efficiency across shifts or periods.
  • normalize: Convert raw CSV DataFrame to standard schema.

  • IdleEnergyDetectionEvents: Detect and quantify idle energy waste.

  • idle_energy_by_window: Idle vs running energy per time window.
  • idle_energy_by_shift: Idle waste aggregated per shift.
  • idle_energy_trend: Rolling trend of idle energy waste.

  • EnergyPerformanceIndicatorEvents: ISO 50001 EnPI (energy per unit produced).

  • enpi_by_window: EnPI for each time window.
  • enpi_vs_baseline: EnPI vs rolling baseline with anomaly flags.
  • enpi_by_hierarchy: EnPI across multiple meters for area comparison.

  • CarbonIntensityEvents: Scope 1 & 2 CO2e emissions tracking.

  • emissions_by_window: CO2e per source per time window.
  • total_emissions_by_window: Aggregated Scope 1 + 2 per window.
  • carbon_intensity_per_unit: kgCO2e per unit produced.
  • emission_factor_audit: Return configured factors for audit trail.

CarbonIntensityEvents ¤

CarbonIntensityEvents(
    dataframe: DataFrame,
    emission_factors: dict[str, float],
    *,
    scope_map: dict[str, int] | None = None,
    event_uuid: str = "energy:carbon",
    time_column: str = "systime",
    uuid_column: str = "uuid"
)

Bases: Base

Energy: Carbon Intensity Tracking (Scope 1 & 2)

Converts energy and fuel consumption signals to CO2-equivalent emissions using configurable emission factors. Supports Scope 1 (direct fuel) and Scope 2 (electricity) calculations, plus carbon intensity per unit produced. Designed for CSRD and ISO 14064 reporting.

Supports two data models via constructor parameters:

  • Standard (ts-shape default)::

    CarbonIntensityEvents(df, emission_factors={"meter:elec": 0.233})

    expects: systime | uuid | value_double¤

  • Raw CSV::

    CarbonIntensityEvents(df, emission_factors={"sensor_01": 0.233}, time_column="time", uuid_column="id")

emission_factors is a dict mapping signal identifier → kgCO2e per unit of the energy/fuel reading::

emission_factors = {
    "meter:electricity": 0.233,   # kgCO2e/kWh  (UK grid average 2026)
    "meter:gas":         2.034,   # kgCO2e/m³   (natural gas)
}

Each factor's scope is inferred from scope_map. Any uuid not in scope_map defaults to Scope 2.

Methods: - emissions_by_window: CO2e per source per time window. - total_emissions_by_window: Aggregated Scope 1 + 2 per window. - carbon_intensity_per_unit: kgCO2e per unit produced. - emission_factor_audit: Return configured factors for audit trail.

Parameters:

Name Type Description Default
dataframe DataFrame

Input signal DataFrame.

required
emission_factors dict[str, float]

Mapping of signal identifier → kgCO2e per unit.

required
scope_map dict[str, int] | None

Optional mapping of signal identifier → scope (1 or 2). Defaults to Scope 2 for any uuid not in the map.

None
event_uuid str

UUID assigned to output events.

'energy:carbon'
time_column str

Name of the timestamp column.

'systime'
uuid_column str

Name of the signal identifier column.

'uuid'

emissions_by_window ¤

emissions_by_window(
    *,
    scope: int = 0,
    value_column: str = "value_double",
    window: str = "1D"
) -> pd.DataFrame

CO2e emissions per configured source per time window.

Parameters:

Name Type Description Default
scope int

Filter by scope: 1 = fuel only, 2 = electricity only, 0 = all sources (default).

0
value_column str

Column containing consumption readings.

'value_double'
window str

Aggregation window (e.g. '1D', '1h').

'1D'

Returns:

Name Type Description
DataFrame DataFrame

start, uuid, source_uuid, scope, consumption, emission_factor, kgco2e

total_emissions_by_window ¤

total_emissions_by_window(
    *,
    value_column: str = "value_double",
    window: str = "1D"
) -> pd.DataFrame

Aggregate Scope 1 + Scope 2 emissions across all configured meters.

Parameters:

Name Type Description Default
value_column str

Column containing consumption readings.

'value_double'
window str

Aggregation window.

'1D'

Returns:

Name Type Description
DataFrame DataFrame

start, uuid, scope1_kgco2e, scope2_kgco2e, total_kgco2e

carbon_intensity_per_unit ¤

carbon_intensity_per_unit(
    counter_uuid: str,
    *,
    value_column: str = "value_double",
    counter_column: str = "value_integer",
    window: str = "1D"
) -> pd.DataFrame

Carbon intensity per unit produced (kgCO2e / unit).

Parameters:

Name Type Description Default
counter_uuid str

Identifier of the production counter signal.

required
value_column str

Column containing energy/fuel readings.

'value_double'
counter_column str

Column containing counter readings.

'value_integer'
window str

Aggregation window.

'1D'

Returns:

Name Type Description
DataFrame DataFrame

start, uuid, total_kgco2e, units_produced, carbon_intensity, trend

emission_factor_audit ¤

emission_factor_audit() -> pd.DataFrame

Return the configured emission factors for audit and reporting.

Returns:

Name Type Description
DataFrame DataFrame

source_uuid, scope, emission_factor_kgco2e_per_unit

EnergyConsumptionEvents ¤

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

Bases: Base

Energy: Consumption Analysis

Analyze energy consumption patterns from meter/sensor signals.

Supports two data models via constructor parameters:

  • Standard (ts-shape default)::

    EnergyConsumptionEvents(df)

    expects: systime | uuid | value_double¤

  • Raw CSV (time + id + value)::

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

    expects: time | id | value¤

    pass value_column="value" to each method¤

Methods: - consumption_by_window: Aggregate energy per time window from a meter UUID. - peak_demand_detection: Flag windows where consumption exceeds a threshold. - consumption_baseline_deviation: Compare actual vs rolling baseline. - energy_per_unit: Energy per production unit when paired with a counter. - normalize: Static helper to convert raw CSV format to standard schema.

normalize staticmethod ¤

normalize(
    df: DataFrame,
    *,
    series_id: str,
    time_column: str = "time",
    value_column: str = "value",
    id_column: str | None = None
) -> pd.DataFrame

Convert a raw energy DataFrame to the standard ts-shape schema.

Handles two input formats:

  • Two-column CSV: (time, value) — series_id is assigned as uuid.
  • Three-column with explicit id: (time, id_column, value) — values from id_column are used as uuid; series_id is ignored.

Parameters:

Name Type Description Default
df DataFrame

Raw DataFrame.

required
series_id str

UUID to assign when no id_column is provided.

required
time_column str

Name of the timestamp column in df.

'time'
value_column str

Name of the value column in df.

'value'
id_column str | None

Optional column name whose values become the uuid.

None

Returns:

Type Description
DataFrame

DataFrame with columns: systime, uuid, value_double, is_delta

consumption_by_window ¤

consumption_by_window(
    meter_uuid: str,
    *,
    value_column: str = "value_double",
    window: str = "1h",
    agg: str = "sum"
) -> pd.DataFrame

Aggregate energy consumption per time window.

Parameters:

Name Type Description Default
meter_uuid str

UUID of the energy meter signal.

required
value_column str

Column containing energy readings.

'value_double'
window str

Resample window (e.g. '1h', '15min', '1D').

'1h'
agg str

Aggregation method ('sum', 'mean', 'max').

'sum'

Returns:

Name Type Description
DataFrame DataFrame

start, uuid, source_uuid, is_delta, consumption

peak_demand_detection ¤

peak_demand_detection(
    meter_uuid: str,
    *,
    value_column: str = "value_double",
    window: str = "15min",
    threshold: float | None = None,
    percentile: float = 0.95
) -> pd.DataFrame

Detect peak demand periods exceeding a threshold.

If threshold is None, uses the given percentile of windowed consumption.

Parameters:

Name Type Description Default
meter_uuid str

UUID of the energy meter signal.

required
value_column str

Column containing energy readings.

'value_double'
window str

Resample window for demand calculation.

'15min'
threshold float | None

Absolute demand threshold. If None, auto-calculated.

None
percentile float

Percentile to use for auto-threshold (default 95th).

0.95

Returns:

Name Type Description
DataFrame DataFrame

start, uuid, source_uuid, is_delta, demand, threshold, is_peak

consumption_baseline_deviation ¤

consumption_baseline_deviation(
    meter_uuid: str,
    *,
    value_column: str = "value_double",
    window: str = "1h",
    baseline_periods: int = 24,
    deviation_threshold: float = 0.2
) -> pd.DataFrame

Compare actual consumption vs rolling baseline.

Parameters:

Name Type Description Default
meter_uuid str

UUID of the energy meter signal.

required
value_column str

Column containing energy readings.

'value_double'
window str

Resample window for consumption.

'1h'
baseline_periods int

Number of windows for rolling baseline.

24
deviation_threshold float

Fractional deviation to flag (0.2 = 20%).

0.2

Returns:

Name Type Description
DataFrame DataFrame

start, uuid, source_uuid, is_delta, consumption, baseline, deviation_pct, is_anomaly

energy_per_unit ¤

energy_per_unit(
    meter_uuid: str,
    counter_uuid: str,
    *,
    energy_column: str = "value_double",
    counter_column: str = "value_integer",
    window: str = "1h"
) -> pd.DataFrame

Calculate energy consumption per production unit.

Parameters:

Name Type Description Default
meter_uuid str

UUID of the energy meter signal.

required
counter_uuid str

UUID of the production counter signal.

required
energy_column str

Column with energy readings.

'value_double'
counter_column str

Column with counter readings.

'value_integer'
window str

Time window for aggregation.

'1h'

Returns:

Name Type Description
DataFrame DataFrame

start, uuid, source_uuid, is_delta, energy, units_produced, energy_per_unit

EnergyEfficiencyEvents ¤

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

Bases: Base

Energy: Efficiency Tracking

Track energy efficiency metrics against production and machine state.

Supports two data models via constructor parameters:

  • Standard (ts-shape default)::

    EnergyEfficiencyEvents(df)

    expects: systime | uuid | value_double / value_integer / value_bool¤

  • Raw CSV (time + id + value)::

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

    pass value_column="value" to each method¤

Methods: - efficiency_trend: Rolling efficiency metric over time. - idle_energy_waste: Detect energy consumption during idle periods. - specific_energy_consumption: Energy per unit output trend. - efficiency_comparison: Compare efficiency across shifts or periods. - normalize: Static helper to convert raw CSV format to standard schema.

normalize staticmethod ¤

normalize(
    df: DataFrame,
    *,
    series_id: str,
    time_column: str = "time",
    value_column: str = "value",
    id_column: str | None = None
) -> pd.DataFrame

Convert a raw energy DataFrame to the standard ts-shape schema.

Parameters:

Name Type Description Default
df DataFrame

Raw DataFrame.

required
series_id str

UUID to assign when no id_column is provided.

required
time_column str

Name of the timestamp column in df.

'time'
value_column str

Name of the value column in df.

'value'
id_column str | None

Optional column name whose values become the uuid.

None

Returns:

Type Description
DataFrame

DataFrame with columns: systime, uuid, value_double, is_delta

efficiency_trend ¤

efficiency_trend(
    meter_uuid: str,
    counter_uuid: str,
    *,
    energy_column: str = "value_double",
    counter_column: str = "value_integer",
    window: str = "1h",
    trend_window: int = 24
) -> pd.DataFrame

Rolling energy efficiency trend (units produced per kWh).

Parameters:

Name Type Description Default
meter_uuid str

UUID of the energy meter signal.

required
counter_uuid str

UUID of the production counter signal.

required
energy_column str

Column with energy readings.

'value_double'
counter_column str

Column with counter readings.

'value_integer'
window str

Time window for aggregation.

'1h'
trend_window int

Number of windows for rolling average.

24

Returns:

Name Type Description
DataFrame DataFrame

start, uuid, source_uuid, is_delta, energy, units, efficiency, rolling_avg_efficiency, trend_direction

idle_energy_waste ¤

idle_energy_waste(
    meter_uuid: str,
    state_uuid: str,
    *,
    energy_column: str = "value_double",
    state_column: str = "value_bool",
    window: str = "15min",
    idle_threshold: float = 0.0
) -> pd.DataFrame

Detect energy consumed during idle periods (waste).

Compares energy consumption with machine run/idle state to find windows where the machine is idle but still consuming energy.

Parameters:

Name Type Description Default
meter_uuid str

UUID of the energy meter signal.

required
state_uuid str

UUID of the boolean machine state signal (True=run).

required
energy_column str

Column with energy readings.

'value_double'
state_column str

Column with boolean state.

'value_bool'
window str

Time window for analysis.

'15min'
idle_threshold float

Energy above this during idle is waste.

0.0

Returns:

Name Type Description
DataFrame DataFrame

start, uuid, source_uuid, is_delta, energy_consumed, machine_running_pct, is_idle_waste, waste_energy

specific_energy_consumption ¤

specific_energy_consumption(
    meter_uuid: str,
    counter_uuid: str,
    *,
    energy_column: str = "value_double",
    counter_column: str = "value_integer",
    window: str = "1D"
) -> pd.DataFrame

Daily/periodic specific energy consumption (SEC = energy / output).

Lower SEC indicates better efficiency.

Parameters:

Name Type Description Default
meter_uuid str

UUID of the energy meter signal.

required
counter_uuid str

UUID of the production counter.

required
energy_column str

Column with energy readings.

'value_double'
counter_column str

Column with counter readings.

'value_integer'
window str

Time window (default daily).

'1D'

Returns:

Name Type Description
DataFrame DataFrame

start, uuid, source_uuid, is_delta, total_energy, total_output, sec, sec_trend

efficiency_comparison ¤

efficiency_comparison(
    meter_uuid: str,
    counter_uuid: str,
    *,
    energy_column: str = "value_double",
    counter_column: str = "value_integer",
    shift_definitions: dict[str, tuple] | None = None
) -> pd.DataFrame

Compare energy efficiency across shifts.

Parameters:

Name Type Description Default
meter_uuid str

UUID of the energy meter signal.

required
counter_uuid str

UUID of the production counter.

required
energy_column str

Column with energy readings.

'value_double'
counter_column str

Column with counter readings.

'value_integer'
shift_definitions dict[str, tuple] | None

Dict mapping shift name to (start_time, end_time) strings. Default: 3-shift operation.

None

Returns:

Name Type Description
DataFrame DataFrame

shift, avg_energy, avg_output, avg_efficiency, total_energy, total_output

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,
    *,
    energy_column: str = "value_double",
    counter_column: str = "value_integer",
    window: str = "1D"
) -> 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
energy_column str

Column containing energy readings.

'value_double'
counter_column str

Column containing counter readings.

'value_integer'
window str

Aggregation window (e.g. '1D', '1h', '1W').

'1D'

Returns:

Name Type Description
DataFrame DataFrame

start, uuid, source_uuid, is_delta, energy_kwh, units_produced, enpi

enpi_vs_baseline ¤

enpi_vs_baseline(
    meter_uuid: str,
    counter_uuid: str,
    *,
    energy_column: str = "value_double",
    counter_column: str = "value_integer",
    window: str = "1D",
    baseline_window: int = 30,
    deviation_threshold: float = 0.1
) -> pd.DataFrame

Compare current EnPI against a rolling baseline.

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
energy_column str

Column containing energy readings.

'value_double'
counter_column 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

Returns:

Name Type Description
DataFrame DataFrame

start, uuid, source_uuid, enpi, baseline_enpi, deviation_pct, is_anomaly, trend

enpi_by_hierarchy ¤

enpi_by_hierarchy(
    meter_uuids: list[str],
    counter_uuid: str,
    *,
    energy_column: str = "value_double",
    counter_column: str = "value_integer",
    window: str = "1D"
) -> 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
energy_column str

Column containing energy readings.

'value_double'
counter_column str

Column containing counter readings.

'value_integer'
window str

Aggregation window.

'1D'

Returns:

Name Type Description
DataFrame DataFrame

start, meter_uuid, energy_kwh, units_produced, enpi

IdleEnergyDetectionEvents ¤

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

Bases: Base

Energy: Idle Energy Detection

Cross-reference an energy meter signal with a boolean machine-state signal to detect and quantify energy consumed during idle (non-production) periods.

Supports two data models via constructor parameters:

  • Standard (ts-shape default)::

    IdleEnergyDetectionEvents(df)

    expects: systime | uuid | value_double | value_bool¤

  • Raw CSV::

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

Methods: - idle_energy_by_window: Idle vs running energy per time window. - idle_energy_by_shift: Idle waste aggregated per shift. - idle_energy_trend: Rolling trend of idle energy waste.

idle_energy_by_window ¤

idle_energy_by_window(
    meter_uuid: str,
    state_uuid: str,
    *,
    energy_column: str = "value_double",
    state_column: str = "value_bool",
    window: str = "1h",
    idle_threshold: float = 0.1
) -> pd.DataFrame

Aggregate energy consumed during idle periods per time window.

Machine-running percentage is the mean of the boolean state signal within each window. Windows below idle_threshold are classified as idle.

Parameters:

Name Type Description Default
meter_uuid str

Identifier of the energy meter signal.

required
state_uuid str

Identifier of the boolean machine-state signal (True=running).

required
energy_column str

Column containing energy readings.

'value_double'
state_column str

Column containing boolean state values.

'value_bool'
window str

Resample window (e.g. '1h', '15min').

'1h'
idle_threshold float

machine_running_pct below this classifies the window as idle.

0.1

Returns:

Name Type Description
DataFrame DataFrame

start, uuid, source_uuid, is_delta, total_energy, idle_energy, running_energy, machine_running_pct, idle_fraction

idle_energy_by_shift ¤

idle_energy_by_shift(
    meter_uuid: str,
    state_uuid: str,
    *,
    energy_column: str = "value_double",
    state_column: str = "value_bool",
    shift_definitions: (
        dict[str, tuple[str, str]] | None
    ) = None
) -> pd.DataFrame

Aggregate idle energy waste per shift across all dates.

Parameters:

Name Type Description Default
meter_uuid str

Identifier of the energy meter signal.

required
state_uuid str

Identifier of the boolean machine-state signal.

required
energy_column str

Column containing energy readings.

'value_double'
state_column str

Column containing boolean state values.

'value_bool'
shift_definitions dict[str, tuple[str, str]] | None

Dict mapping shift name → (start_time, end_time). Default: three-shift operation (06-14, 14-22, 22-06).

None

Returns:

Name Type Description
DataFrame DataFrame

shift, total_energy, idle_energy, waste_fraction

idle_energy_trend ¤

idle_energy_trend(
    meter_uuid: str,
    state_uuid: str,
    *,
    energy_column: str = "value_double",
    state_column: str = "value_bool",
    window: str = "1D",
    trend_window: int = 7,
    idle_threshold: float = 0.1
) -> pd.DataFrame

Rolling trend of idle energy waste over time.

Parameters:

Name Type Description Default
meter_uuid str

Identifier of the energy meter signal.

required
state_uuid str

Identifier of the boolean machine-state signal.

required
energy_column str

Column containing energy readings.

'value_double'
state_column str

Column containing boolean state values.

'value_bool'
window str

Aggregation window (default daily).

'1D'
trend_window int

Number of windows for rolling average.

7
idle_threshold float

machine_running_pct below this → idle.

0.1

Returns:

Name Type Description
DataFrame DataFrame

start, uuid, source_uuid, idle_energy, rolling_avg_idle_energy, trend_direction