operating_range

operating_range ¤

OperatingRangeEvents ¤

OperatingRangeEvents(
    dataframe: DataFrame,
    signal_uuid: str,
    *,
    event_uuid: str = "eng:operating_range",
    value_column: str = "value_double",
    time_column: str = "systime"
)

Bases: Base

Engineering: Operating Range Analysis

Analyze the operating envelope of a signal — what ranges it operates in, how often, and when the operating point shifts.

Methods: - operating_envelope: Per-window min/max/mean/percentiles. - detect_regime_change: Detect significant shifts in the operating point. - time_in_range: Percentage of time within a defined range per window. - value_distribution: Histogram of signal values.

operating_envelope ¤

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

Per-window operating envelope statistics.

Parameters:

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

Returns:

Type	Description
`DataFrame`	DataFrame with columns: start, end, duration_seconds, uuid,
`DataFrame`	source_uuid, min_value, p5, mean_value, p95, max_value,
`DataFrame`	range_width. `end` is `start` + `window`.

detect_regime_change ¤

detect_regime_change(
    window: str = "1h", shift_threshold: float = 2.0
) -> pd.DataFrame

Detect significant shifts in the operating point between windows.

A regime change is flagged when the window mean differs from the previous window mean by more than shift_threshold * pooled std.

Parameters:

Name	Type	Description	Default
`window`	`str`	Resample window (pandas offset string). Windows with fewer than two samples are skipped.	`'1h'`
`shift_threshold`	`float`	Minimum shift between consecutive window means, in multiples of the two windows' average std, to flag a regime change.	`2.0`

Returns:

Type	Description
`DataFrame`	DataFrame with columns: start, end, duration_seconds, uuid,
`DataFrame`	source_uuid, is_delta, prev_mean, new_mean, shift_magnitude.
`DataFrame`	`start` is the previous window's start and `end` the new
`DataFrame`	window's start.

time_in_range ¤

time_in_range(
    lower_limit: float,
    upper_limit: float,
    window: str = "1h",
    time_weighted: bool = True,
) -> pd.DataFrame

Share of each window spent within, below and above a range.

By default the *_pct columns are percentages of time: each value is held until the next sample (zero-order hold), so a window without samples that holds an earlier value is reported too. With time_weighted=False they are percentages of the samples in each window (equal to the share of time only for evenly spaced data).

Parameters:

Name	Type	Description	Default
`lower_limit`	`float`	Lower bound of the range (inclusive), in signal units.	required
`upper_limit`	`float`	Upper bound of the range (inclusive), in signal units.	required
`window`	`str`	Resample window (pandas offset string).	`'1h'`
`time_weighted`	`bool`	`True` (default) weights each value by how long it was held; `False` counts samples.	`True`

Returns:

Type	Description
`DataFrame`	DataFrame with columns: start, end, duration_seconds, uuid,
`DataFrame`	source_uuid, time_in_range_pct, time_below_pct, time_above_pct.
`DataFrame`	`end` is `start` + `window`.

value_distribution ¤

value_distribution(n_bins: int = 10) -> pd.DataFrame

Histogram of signal values.

Parameters:

Name	Type	Description	Default
`n_bins`	`int`	Number of equal-width histogram bins between the signal's minimum and maximum.	`10`

Returns:

Type	Description
`DataFrame`	DataFrame with columns: bin_lower, bin_upper, count, pct,
`DataFrame`	cumulative_pct.