material_balance

material_balance ¤

MaterialBalanceEvents ¤

MaterialBalanceEvents(
    dataframe: DataFrame,
    input_uuids: list[str],
    output_uuids: list[str],
    *,
    event_uuid: str = "eng:material_balance",
    value_column: str = "value_double",
    time_column: str = "systime",
    time_weighted: bool = True,
    missing_as_zero: bool = False
)

Bases: Base

Engineering: Material / Energy Balance

Check whether inputs and outputs balance (mass, energy, flow) per time window. The most fundamental daily engineering check for any process.

Methods: - balance_check: Per-window sum(inputs) vs sum(outputs). - imbalance_trend: Track whether imbalance is growing or shrinking. - detect_balance_exceedance: Sustained imbalance events. - contribution_breakdown: Each signal's share of total input/output.

Parameters:

Name	Type	Description	Default
`dataframe`	`DataFrame`	Long-format input data.	required
`input_uuids`	`list[str]`	Signals flowing into the balance boundary.	required
`output_uuids`	`list[str]`	Signals flowing out of it.	required
`event_uuid`	`str`	UUID assigned to generated events.	`'eng:material_balance'`
`value_column`	`str`	Column holding the flow values.	`'value_double'`
`time_column`	`str`	Timestamp column.	`'systime'`
`time_weighted`	`bool`	`True` (default) averages each flow by time (value held until the next sample). `False` uses `resample().mean()` over the samples, which is biased on irregular or change-encoded flow signals.	`True`
`missing_as_zero`	`bool`	`False` (default) leaves a window's totals NaN when a signal has no data in it; the window is marked not balanced but is not reported by :meth:`detect_balance_exceedance`, so a sensor outage is not read as a real imbalance. `True` treats a window without data for a signal as zero flow.	`False`

balance_check ¤

balance_check(
    window: str = "1h", tolerance_pct: float = 5.0
) -> pd.DataFrame

Per-window balance check: sum(inputs) vs sum(outputs).

Parameters:

Name	Type	Description	Default
`window`	`str`	Resample window.	`'1h'`
`tolerance_pct`	`float`	Maximum acceptable imbalance percentage.	`5.0`

Returns:

Type	Description
`DataFrame`	DataFrame with columns: start, end, duration_seconds,
`DataFrame`	total_input, total_output, imbalance, imbalance_pct, balanced.
`DataFrame`	`end` is `start` + `window`.

imbalance_trend ¤

imbalance_trend(window: str = '1h') -> pd.DataFrame

Track whether imbalance is growing, shrinking, or stable.

Parameters:

Name	Type	Description	Default
`window`	`str`	Resample window passed to :meth:`balance_check`. The rolling average spans the last three windows.	`'1h'`

Returns:

Type	Description
`DataFrame`	DataFrame with columns: start, end, duration_seconds,
`DataFrame`	imbalance_pct, rolling_avg_imbalance, trend_direction. `end` is
`DataFrame`	`start` + `window`.

detect_balance_exceedance ¤

detect_balance_exceedance(
    window: str = "1h",
    tolerance_pct: float = 5.0,
    min_duration: str = "2h",
) -> pd.DataFrame

Detect sustained imbalance events.

Parameters:

Name	Type	Description	Default
`window`	`str`	Resample window passed to :meth:`balance_check`.	`'1h'`
`tolerance_pct`	`float`	Maximum acceptable imbalance percentage per window.	`5.0`
`min_duration`	`str`	Minimum length of a run of consecutive unbalanced windows to report it as an event (pandas offset string). Windows whose totals are NaN (missing data) end a run.	`'2h'`

Returns:

Type	Description
`DataFrame`	DataFrame with columns: start, end, duration_seconds, uuid,
`DataFrame`	source_uuid (input and output uuids, comma-joined), is_delta,
`DataFrame`	avg_imbalance_pct, max_imbalance_pct, likely_cause.

contribution_breakdown ¤

contribution_breakdown(window: str = '1h') -> pd.DataFrame

Each signal's contribution to total input/output per window.

Parameters:

Name	Type	Description	Default
`window`	`str`	Resample window (pandas offset string).	`'1h'`

Returns:

Type	Description
`DataFrame`	DataFrame with columns: start, end, duration_seconds, uuid,
`DataFrame`	source_uuid, role, value, pct_of_total. `uuid` and
`DataFrame`	`source_uuid` both hold the contributing signal's uuid; `end`
`DataFrame`	is `start` + `window`.
`DataFrame`	Canonical twin columns: `share_of_total_pct` (after `pct_of_total`); each
`DataFrame`	holds the same values as the deprecated column right before it, which is
`DataFrame`	removed in the next major release.