disturbance_recovery

disturbance_recovery

DisturbanceRecoveryEvents

DisturbanceRecoveryEvents(
    dataframe: DataFrame,
    signal_uuid: str,
    *,
    setpoint_uuid: Optional[str] = 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 = "10m",
    threshold_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.	'10m'
threshold_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, uuid, is_delta,
DataFrame	peak_deviation, mean_deviation, direction, duration_seconds,
DataFrame	disturbance_type.

recovery_time

recovery_time(
    baseline_window: str = "10m",
    threshold_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
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: disturbance_start, disturbance_end,
DataFrame	recovery_time_seconds, recovered, pre_disturbance_mean,
DataFrame	post_recovery_mean, residual_offset.

disturbance_frequency

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

Count disturbances per time window.

Returns:

Type	Description
DataFrame	DataFrame with columns: window_start, disturbance_count,
DataFrame	total_disturbance_seconds, pct_time_disturbed,
DataFrame	avg_recovery_seconds.

before_after_comparison

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

Compare process statistics before vs after each disturbance.

Returns:

Type	Description
DataFrame	DataFrame with columns: disturbance_start, pre_mean, post_mean,
DataFrame	pre_std, post_std, mean_shift, variance_ratio.