threshold_monitoring

threshold_monitoring ¤

ThresholdMonitoringEvents ¤

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

Bases: Base

Engineering: Threshold Monitoring

Multi-level threshold monitoring with hysteresis for numeric signals.

Methods: - multi_level_threshold: Intervals exceeding configurable warning/alarm/critical levels. - threshold_with_hysteresis: Alarm entry/exit with separate high/low thresholds. - time_above_threshold: Time and percentage above a threshold per window. - threshold_exceedance_trend: Track exceedance frequency over time.

Example

import pandas as pd from ts_shape import ThresholdMonitoringEvents df = pd.DataFrame({ ... "systime": pd.date_range("2025-01-01 08:00", periods=6, freq="1min"), ... "uuid": "temp", ... "value_double": [70.0, 82.0, 91.0, 85.0, 75.0, 70.0], ... }) monitor = ThresholdMonitoringEvents(df, "temp") monitor.multi_level_threshold({"warning": 80.0, "alarm": 90.0})[ ... ["start", "end", "level"]] start end level 0 2025-01-01 08:02:00 2025-01-01 08:03:00 alarm 1 2025-01-01 08:01:00 2025-01-01 08:04:00 warning monitor.threshold_with_hysteresis(upper_limit=80.0, lower_limit=76.0)[ ... ["start", "end", "duration_seconds"]] start end duration_seconds 0 2025-01-01 08:01:00 2025-01-01 08:04:00 180.0

multi_level_threshold ¤

multi_level_threshold(
    levels: dict[str, float],
    direction: str = "above",
    *,
    interval_end: str = "next_change"
) -> pd.DataFrame

Detect intervals where signal exceeds configurable threshold levels.

Parameters:

Name	Type	Description	Default
`levels`	`dict[str, float]`	Dict mapping level names to threshold values. e.g. {'warning': 80, 'alarm': 90, 'critical': 95}	required
`direction`	`str`	'above' or 'below'.	`'above'`
`interval_end`	`str`	`"next_change"` (default) ends an interval at the next sample (the transition), so the interval spans the time the condition held and change-encoded signals -- one row per change -- keep their duration. `"last_sample"` ends it at its last flagged sample. See :func:`ts_shape.utils.intervals.interval_end_times`.	`'next_change'`

Returns:

Type	Description
`DataFrame`	DataFrame with columns: start, end, duration_seconds, uuid,
`DataFrame`	source_uuid, duration (Timedelta), level, peak_value.

threshold_with_hysteresis ¤

threshold_with_hysteresis(
    upper_limit: float,
    lower_limit: float,
    *,
    max_gap: str | Timedelta | None = None
) -> pd.DataFrame

Alarm intervals with hysteresis to prevent chattering.

Enter alarm when signal crosses upper_limit, exit when it drops below lower_limit.

Parameters:

Name	Type	Description	Default
`upper_limit`	`float`	Upper threshold to enter alarm state.	required
`lower_limit`	`float`	Lower threshold to exit alarm state.	required
`max_gap`	`str \| Timedelta \| None`	Longest time between two samples an alarm may span (e.g. `"15min"`). A longer gap is "no data": an open alarm ends at its last sample before the gap, and after the gap the signal must reach `upper_limit` again to start a new one. `None` (default): no limit.	`None`

Returns:

Type	Description
`DataFrame`	DataFrame with columns: start, end, duration_seconds, uuid,
`DataFrame`	source_uuid, duration (Timedelta), peak_value.

time_above_threshold ¤

time_above_threshold(
    threshold: float,
    window: str = "1h",
    *,
    interval_end: str = "next_change"
) -> pd.DataFrame

Per window: total time and percentage above threshold.

Parameters:

Name	Type	Description	Default
`threshold`	`float`	Value threshold.	required
`window`	`str`	Resample window.	`'1h'`
`interval_end`	`str`	`"next_change"` (default) holds each value until the next sample and measures the real time above the threshold inside each window (`pct_above` is relative to the window length). `"last_sample"` estimates the time as the fraction of samples above the threshold times the window length, which is only right for uniform sampling.	`'next_change'`

Returns:

Type	Description
`DataFrame`	DataFrame with columns: start, end, duration_seconds, time_above,
`DataFrame`	pct_above, exceedance_count. `end` is `start` + `window`.
`DataFrame`	Canonical twin columns: `time_above_pct` (after `pct_above`); each holds the
`DataFrame`	same values as the deprecated column right before it, which is removed in
`DataFrame`	the next major release.

threshold_exceedance_trend ¤

threshold_exceedance_trend(
    threshold: float, window: str = "1D"
) -> pd.DataFrame

Track exceedance frequency and duration trend over time.

Parameters:

Name	Type	Description	Default
`threshold`	`float`	Value threshold.	required
`window`	`str`	Resample window (e.g. '1D' for daily).	`'1D'`

Returns:

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