disturbance_recovery

disturbance_recovery ¤

DisturbanceRecoveryEvents ¤

DisturbanceRecoveryEvents(
    dataframe: DataFrame,
    signal_uuid: str,
    *,
    setpoint_uuid: str | None = None,
    event_uuid: str = "eng:disturbance_recovery",
    value_column: str = "value_double",
    time_column: str = "systime"
)

Bases: Base

Engineering: Disturbance / Upset Detection and Recovery

Detect external upsets hitting a process signal and measure how the process recovered. Works with a rolling baseline or an optional setpoint.

Methods: - detect_disturbances: Intervals where signal deviates from baseline. - recovery_time: How long until signal returns to normal after each upset. - disturbance_frequency: Count disturbances per shift/day. - before_after_comparison: Did the upset permanently change the process?

detect_disturbances ¤

detect_disturbances(
    baseline_window: str = "10min",
    n_sigma: float = 3.0,
    min_duration: str = "30s",
) -> pd.DataFrame

Detect intervals where signal deviates significantly from baseline.

Parameters:

Name	Type	Description	Default
`baseline_window`	`str`	Window for rolling baseline computation.	`'10min'`
`n_sigma`	`float`	Deviation threshold in multiples of rolling std.	`3.0`
`min_duration`	`str`	Minimum disturbance duration.	`'30s'`

Returns:

Type	Description
`DataFrame`	DataFrame with columns: start, end, duration_seconds, uuid,
`DataFrame`	source_uuid, is_delta, peak_deviation, mean_deviation, direction,
`DataFrame`	disturbance_type.

recovery_time ¤

recovery_time(
    baseline_window: str = "10min",
    n_sigma: float = 3.0,
    recovery_pct: float = 0.95,
    max_recovery: str = "1h",
) -> pd.DataFrame

Measure recovery time after each disturbance.

Parameters:

Name	Type	Description	Default
`baseline_window`	`str`	Window for the rolling baseline and rolling std (pandas offset string). Ignored for the baseline when a `setpoint_uuid` was given; the setpoint is used instead.	`'10min'`
`n_sigma`	`float`	Deviation threshold in multiples of the rolling std.	`3.0`
`recovery_pct`	`float`	Signal must return to within (1 - recovery_pct) of peak deviation to be considered recovered.	`0.95`
`max_recovery`	`str`	Maximum time to look for recovery.	`'1h'`

Returns:

Type	Description
`DataFrame`	DataFrame with columns: start, end, duration_seconds (of the
`DataFrame`	disturbance), uuid, source_uuid, recovery_time_seconds, recovered,
`DataFrame`	pre_disturbance_mean, post_recovery_mean, residual_offset.

disturbance_frequency ¤

disturbance_frequency(
    window: str = "8h",
    baseline_window: str = "10min",
    n_sigma: float = 3.0,
) -> pd.DataFrame

Count disturbances per time window.

Parameters:

Name	Type	Description	Default
`window`	`str`	Counting window as a pandas offset string (e.g. '8h' per shift, '1D' per day).	`'8h'`
`baseline_window`	`str`	Window for the rolling baseline and rolling std used by :meth:`detect_disturbances`.	`'10min'`
`n_sigma`	`float`	Deviation threshold in multiples of the rolling std.	`3.0`

Returns:

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

before_after_comparison ¤

before_after_comparison(
    baseline_window: str = "10min",
    n_sigma: float = 3.0,
    comparison_window: str = "5min",
) -> pd.DataFrame

Compare process statistics before vs after each disturbance.

Parameters:

Name	Type	Description	Default
`baseline_window`	`str`	Window for the rolling baseline and rolling std used by :meth:`detect_disturbances`.	`'10min'`
`n_sigma`	`float`	Deviation threshold in multiples of the rolling std.	`3.0`
`comparison_window`	`str`	Length of the span compared just before the disturbance start and just after its end. Disturbances with fewer than two samples on either side are skipped.	`'5min'`

Returns:

Type	Description
`DataFrame`	DataFrame with columns: start, end, duration_seconds, uuid,
`DataFrame`	source_uuid, pre_mean, post_mean, pre_std, post_std, mean_shift,
`DataFrame`	variance_ratio. `start` / `end` are the disturbance bounds.