efficiency_tracking

efficiency_tracking ¤

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(
    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.

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

efficiency_trend ¤

efficiency_trend(
    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,
    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
`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'`
`trend_window`	`int`	Number of trailing windows (itself included) in `rolling_avg_efficiency`: their summed units over their summed energy.	`24`
`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, efficiency, rolling_avg_efficiency, trend_direction

idle_energy_waste ¤

idle_energy_waste(
    meter_uuid: str,
    run_state_uuid: str,
    *,
    value_column_energy: str = "value_double",
    value_column_state: str = "value_bool",
    window: str = "15min",
    idle_threshold: float = 0.0,
    time_weighted: bool = True
) -> 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
`run_state_uuid`	`str`	UUID of the boolean machine state signal (True=run).	required
`value_column_energy`	`str`	Column with energy readings.	`'value_double'`
`value_column_state`	`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`
`time_weighted`	`bool`	`True` (default) weights the machine state by how long it was held (until the next state change) and keeps every energy window. `False` averages state samples and keeps only windows that contain a state row; that is only right for a densely, uniformly sampled state signal.	`True`

Returns:

Name	Type	Description
`DataFrame`	`DataFrame`	start, end, duration_seconds, uuid, source_uuid, is_delta, energy_consumed, machine_running_pct (0-100), machine_running_ratio (0-1), is_idle_waste, waste_energy. A window is idle waste when the machine ran less than 10 % of it and consumed more than `idle_threshold`.

specific_energy_consumption ¤

specific_energy_consumption(
    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

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
`value_column_energy`	`str`	Column with energy readings.	`'value_double'`
`value_column_counter`	`str`	Column with counter readings.	`'value_integer'`
`window`	`str`	Time window (default daily).	`'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, total_energy, total_output, sec, sec_trend

efficiency_comparison ¤

efficiency_comparison(
    meter_uuid: str,
    counter_uuid: str,
    *,
    value_column_energy: str = "value_double",
    value_column_counter: 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
`value_column_energy`	`str`	Column with energy readings.	`'value_double'`
`value_column_counter`	`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. `total_output` is the counter increase within the shift (reset-aware) and `avg_output` the mean increase per counter reading.

efficiency_tracking