consumption_analysis

consumption_analysis ¤

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.

Values are expected to be energy deltas in kWh (consumption since the previous reading). For an instantaneous power signal in kW, integrate it with :class:~ts_shape.transform.calculator.power_integration.PowerIntegrator first -- summing kW samples measures the logging rate, not the energy.

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.

Example

import ts_shape df = ts_shape.make_timeseries(["meter"], n_points=96, freq="15min", ... baseline=5.0, noise=0.5) # kWh per 15 min energy = ts_shape.EnergyConsumptionEvents(df) out = energy.consumption_by_window("meter", window="6h") out[["start", "consumption"]].round({"consumption": 1}) start consumption 0 2025-01-01 00:00:00 119.8 1 2025-01-01 06:00:00 122.1 2 2025-01-01 12:00:00 118.9 3 2025-01-01 18:00:00 118.1

normalize `staticmethod` ¤

normalize(
    dataframe: DataFrame,
    *,
    series_id: str,
    time_column: str = "time",
    value_column: str = "value",
    uuid_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, uuid_column, value) — values from uuid_column are used as uuid; series_id is ignored.

Parameters:

Name	Type	Description	Default
`dataframe`	`DataFrame`	Raw DataFrame.	required
`series_id`	`str`	UUID to assign when no uuid_column is provided.	required
`time_column`	`str`	Name of the timestamp column in dataframe.	`'time'`
`value_column`	`str`	Name of the value column in dataframe.	`'value'`
`uuid_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, end, duration_seconds, uuid, source_uuid, is_delta, consumption. `end` is `start` plus `window`.

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, end, duration_seconds, 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, end, duration_seconds, uuid, source_uuid, is_delta, consumption, baseline, deviation_pct, is_anomaly

energy_per_unit ¤

energy_per_unit(
    meter_uuid: str,
    counter_uuid: str,
    *,
    value_column_energy: str = "value_double",
    value_column_counter: str = "value_integer",
    window: str = "1h",
    handle_resets: bool = True
) -> 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
`value_column_energy`	`str`	Column with energy readings.	`'value_double'`
`value_column_counter`	`str`	Column with counter readings.	`'value_integer'`
`window`	`str`	Time window for aggregation.	`'1h'`
`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, units_produced, energy_per_unit

consumption_analysis