idle_energy_detection

idle_energy_detection ¤

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,
    run_state_uuid: str,
    *,
    value_column_energy: str = "value_double",
    value_column_state: str = "value_bool",
    window: str = "1h",
    idle_threshold: float = 0.1,
    time_weighted: bool = True
) -> pd.DataFrame

Aggregate energy consumed during idle periods per time window.

The machine-running share is the share of each window the boolean state signal was True. It is reported as machine_running_ratio (0-1) and as machine_running_pct (0-100). Windows whose ratio is below idle_threshold count as fully idle; otherwise the idle fraction is 1 - machine_running_ratio.

Parameters:

Name	Type	Description	Default
`meter_uuid`	`str`	Identifier of the energy meter signal.	required
`run_state_uuid`	`str`	Identifier of the boolean machine-state signal (True=running).	required
`value_column_energy`	`str`	Column containing energy readings.	`'value_double'`
`value_column_state`	`str`	Column containing boolean state values.	`'value_bool'`
`window`	`str`	Resample window (e.g. '1h', '15min').	`'1h'`
`idle_threshold`	`float`	Running ratio (0-1) below which the window is classified as fully idle.	`0.1`
`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, total_energy, idle_energy, running_energy, machine_running_pct (0-100), idle_fraction, machine_running_ratio (0-1)

idle_energy_by_shift ¤

idle_energy_by_shift(
    meter_uuid: str,
    run_state_uuid: str,
    *,
    value_column_energy: str = "value_double",
    value_column_state: str = "value_bool",
    shift_definitions: (
        dict[str, tuple[str, str]] | None
    ) = None,
    idle_threshold: float | None = None
) -> pd.DataFrame

Aggregate idle energy waste per shift across all dates.

The idle fraction of a shift is 1 - running ratio (the mean of the state samples in that shift). Pass idle_threshold to apply the same rule as :meth:idle_energy_by_window: a shift whose running ratio is below the threshold counts as fully idle.

Parameters:

Name	Type	Description	Default
`meter_uuid`	`str`	Identifier of the energy meter signal.	required
`run_state_uuid`	`str`	Identifier of the boolean machine-state signal.	required
`value_column_energy`	`str`	Column containing energy readings.	`'value_double'`
`value_column_state`	`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`
`idle_threshold`	`float \| None`	Running ratio (0-1) below which a shift counts as fully idle. Default None: no threshold, the idle fraction is always `1 - running ratio`; 0.1 matches :meth:`idle_energy_by_window`.	`None`

Returns:

Name	Type	Description
`DataFrame`	`DataFrame`	shift, total_energy, idle_energy, waste_fraction

idle_energy_trend ¤

idle_energy_trend(
    meter_uuid: str,
    run_state_uuid: str,
    *,
    value_column_energy: str = "value_double",
    value_column_state: 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
`run_state_uuid`	`str`	Identifier of the boolean machine-state signal.	required
`value_column_energy`	`str`	Column containing energy readings.	`'value_double'`
`value_column_state`	`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`	Running ratio (0-1) below which a window counts as fully idle (see :meth:`idle_energy_by_window`).	`0.1`

Returns:

Name	Type	Description
`DataFrame`	`DataFrame`	start, end, duration_seconds, uuid, source_uuid, idle_energy, rolling_avg_idle_energy, trend_direction

idle_energy_detection