init

engineering

Engineering Events

Detectors for engineering-related patterns over shaped timeseries.

• SetpointChangeEvents: Detect setpoint changes and compute response KPIs.
• detect_setpoint_steps: Point events where |Δsetpoint| ≥ min_delta and holds for min_hold.
• detect_setpoint_ramps: Intervals where |dS/dt| ≥ min_rate for at least min_duration.
• detect_setpoint_changes: Unified table of steps and ramps with standardized columns.
• time_to_settle: Time until |actual − setpoint| ≤ tol for a hold duration within a window.

• overshoot_metrics: Peak overshoot magnitude/percent and time-to-peak after a change.

• StartupDetectionEvents: Detect startup intervals from thresholds or slope.

• detect_startup_by_threshold: Rising threshold crossing with minimum dwell above threshold.

• detect_startup_by_slope: Intervals with sustained positive slope ≥ min_slope for min_duration.

• ThresholdMonitoringEvents: Multi-level threshold monitoring with hysteresis.

• multi_level_threshold: Intervals exceeding warning/alarm/critical levels.
• threshold_with_hysteresis: Alarm entry/exit with separate high/low thresholds.
• time_above_threshold: Time and percentage above threshold per window.

• threshold_exceedance_trend: Track exceedance frequency over time.

• RateOfChangeEvents: Detect rapid changes and step jumps.

• detect_rapid_change: Flag intervals where rate exceeds threshold.
• rate_statistics: Per-window rate of change statistics.

• detect_step_changes: Sudden value jumps within a short duration.

• SteadyStateDetectionEvents: Identify steady-state vs transient periods.

• detect_steady_state: Intervals where rolling std stays below threshold.
• detect_transient_periods: Intervals where signal is changing.
• steady_state_statistics: Summary of steady vs transient time.

• steady_state_value_bands: Operating band (mean ± std) per steady interval.

• SignalComparisonEvents: Compare two signals and detect divergence.

• detect_divergence: Intervals where |actual - reference| > tolerance.
• deviation_statistics: Per-window MAE, max error, RMSE, bias.
• tracking_error_trend: Whether deviation is growing or shrinking.

• correlation_windows: Per-window Pearson correlation.

• OperatingRangeEvents: Analyze signal operating envelope and range.

• operating_envelope: Per-window min/max/mean/percentiles.
• detect_regime_change: Detect shifts in the operating point.
• time_in_range: Percentage of time within a defined range.

• value_distribution: Histogram of signal values.

• WarmUpCoolDownEvents: Detect and characterize warm-up / cool-down curves.

• detect_warmup: Rising ramp intervals.
• detect_cooldown: Falling ramp intervals.
• warmup_consistency: Compare warm-up durations and rates.

• time_to_target: Time from ramp start until target value is reached.

• ProcessWindowEvents: Time-windowed process statistics and shift detection.

• windowed_statistics: Per-window count, mean, std, min, max, percentiles.
• detect_mean_shift: Flag windows where mean shifts significantly.
• detect_variance_change: Flag windows where variance changes.

• window_comparison: Compare each window to overall baseline.

• ControlLoopHealthEvents: Continuous PID/control loop health assessment.

• error_integrals: Per-window IAE, ISE, ITAE, bias.
• detect_oscillation: Sustained oscillation in the error signal.
• output_saturation: Valve pegged at limits.

• loop_health_summary: Shift-level report card.

• DisturbanceRecoveryEvents: Detect external upsets and measure recovery.

• detect_disturbances: Intervals where signal deviates from baseline.
• recovery_time: Time until signal returns to baseline after disturbance.
• disturbance_frequency: Count disturbances per window.

• before_after_comparison: Compare process stats before vs after disturbance.

• MaterialBalanceEvents: Check whether inputs and outputs balance.

• 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.

• ProcessStabilityIndex: Single 0-100 stability score per shift/day.

• stability_score: Composite 0-100 score per window.
• score_trend: Is stability improving or degrading?
• worst_periods: N worst-scoring windows.
• stability_comparison: Compare each window to best-observed.

SetpointChangeEvents

SetpointChangeEvents(
    dataframe: DataFrame,
    setpoint_uuid: str,
    *,
    event_uuid: str = "setpoint_change_event",
    value_column: str = "value_double",
    time_column: str = "systime"
)

Bases: Base

Detect step/ramp changes on a setpoint signal and compute follow-up KPIs like time-to-settle and overshoot based on an actual (process) value.

Schema assumptions (columns): - uuid, sequence_number, systime, plctime, is_delta - value_integer, value_string, value_double, value_bool, value_bytes

detect_setpoint_steps

detect_setpoint_steps(
    min_delta: float,
    min_hold: str = "0s",
    filter_noise: bool = False,
    noise_threshold: float = 0.01,
) -> pd.DataFrame

Point events at times where the setpoint changes by >= min_delta and the new level holds for at least min_hold (no subsequent change within that time).

Parameters:

Name	Type	Description	Default
min_delta	float	Minimum magnitude of change to detect	required
min_hold	str	Minimum duration the new level must hold	'0s'
filter_noise	bool	If True, filter out changes smaller than noise_threshold	False
noise_threshold	float	Threshold for noise filtering (absolute value)	0.01

Returns:

Type	Description
DataFrame	DataFrame with columns: start, end (== start), uuid, is_delta,
DataFrame	change_type='step', magnitude, prev_level, new_level.

detect_setpoint_ramps

detect_setpoint_ramps(
    min_rate: float, min_duration: str = "0s"
) -> pd.DataFrame

Interval events where |dS/dt| >= min_rate for at least min_duration.

Returns:

Type	Description
DataFrame	DataFrame with columns: start, end, uuid, is_delta, change_type='ramp',
DataFrame	avg_rate, delta.

detect_setpoint_changes

detect_setpoint_changes(
    *,
    min_delta: float = 0.0,
    min_rate: Optional[float] = None,
    min_hold: str = "0s",
    min_duration: str = "0s"
) -> pd.DataFrame

Unified setpoint change table (steps + ramps) with standardized columns.

time_to_settle

time_to_settle(
    actual_uuid: str,
    *,
    tol: float = 0.0,
    settle_pct: Optional[float] = None,
    hold: str = "0s",
    lookahead: str = "10m"
) -> pd.DataFrame

For each setpoint change (any change), compute time until the actual signal is within ±tol of the new setpoint for a continuous duration of hold.

Parameters:

Name	Type	Description	Default
actual_uuid	str	UUID of the actual/process value signal	required
tol	float	Absolute tolerance (used if settle_pct is None)	0.0
settle_pct	Optional[float]	Percentage-based tolerance (e.g., 0.02 for 2% of step magnitude)	None
hold	str	Minimum duration the signal must stay within tolerance	'0s'
lookahead	str	Maximum time window to search for settling	'10m'

Returns:

Type	Description
DataFrame	DataFrame with columns: start, uuid, is_delta, t_settle_seconds, settled.

overshoot_metrics

overshoot_metrics(
    actual_uuid: str, *, window: str = "10m"
) -> pd.DataFrame

For each change, compute peak overshoot, undershoot, and oscillation metrics relative to the new setpoint within a lookahead window.

Returns:

Type	Description
DataFrame	DataFrame with columns: start, uuid, is_delta, overshoot_abs, overshoot_pct,
DataFrame	t_peak_seconds, undershoot_abs, undershoot_pct, t_undershoot_seconds,
DataFrame	oscillation_count, oscillation_amplitude.

time_to_settle_derivative

time_to_settle_derivative(
    actual_uuid: str,
    *,
    rate_threshold: float = 0.01,
    lookahead: str = "10m",
    hold: str = "0s"
) -> pd.DataFrame

Detect settling based on rate of change (derivative) falling below threshold. More sensitive to when the process has truly stopped moving.

Parameters:

Name	Type	Description	Default
actual_uuid	str	UUID of the actual/process value signal	required
rate_threshold	float	Maximum absolute rate of change to consider settled	0.01
lookahead	str	Maximum time window to search for settling	'10m'
hold	str	Minimum duration the rate must stay below threshold	'0s'

Returns:

Type	Description
DataFrame	DataFrame with columns: start, uuid, is_delta, t_settle_seconds, settled, final_rate.

rise_time

rise_time(
    actual_uuid: str,
    *,
    start_pct: float = 0.1,
    end_pct: float = 0.9,
    lookahead: str = "10m"
) -> pd.DataFrame

Compute rise time: time for actual to go from start_pct to end_pct of the setpoint change. Typically measured from 10% to 90% of the final value.

Parameters:

Name	Type	Description	Default
actual_uuid	str	UUID of the actual/process value signal	required
start_pct	float	Starting percentage of change (e.g., 0.1 for 10%)	0.1
end_pct	float	Ending percentage of change (e.g., 0.9 for 90%)	0.9
lookahead	str	Maximum time window to search	'10m'

Returns:

Type	Description
DataFrame	DataFrame with columns: start, uuid, is_delta, rise_time_seconds, reached_end.

decay_rate

decay_rate(
    actual_uuid: str,
    *,
    lookahead: str = "10m",
    min_points: int = 5
) -> pd.DataFrame

Estimate exponential decay rate of the settling behavior. Fits error(t) = A * exp(-lambda * t) and returns lambda.

Parameters:

Name	Type	Description	Default
actual_uuid	str	UUID of the actual/process value signal	required
lookahead	str	Time window for analysis	'10m'
min_points	int	Minimum number of points required for fitting	5

Returns:

Type	Description
DataFrame	DataFrame with columns: start, uuid, is_delta, decay_rate_lambda, fit_quality_r2.

oscillation_frequency

oscillation_frequency(
    actual_uuid: str,
    *,
    window: str = "10m",
    min_oscillations: int = 2
) -> pd.DataFrame

Estimate the frequency of oscillations during settling. Counts zero crossings and estimates period.

Parameters:

Name	Type	Description	Default
actual_uuid	str	UUID of the actual/process value signal	required
window	str	Time window for analysis	'10m'
min_oscillations	int	Minimum number of oscillations to compute frequency	2

Returns:

Type	Description
DataFrame	DataFrame with columns: start, uuid, is_delta, oscillation_freq_hz, period_seconds.

control_quality_metrics

control_quality_metrics(
    actual_uuid: str,
    *,
    tol: float = 0.0,
    settle_pct: Optional[float] = None,
    hold: str = "0s",
    lookahead: str = "10m",
    rate_threshold: float = 0.01
) -> pd.DataFrame

Comprehensive control quality metrics combining multiple performance indicators.

Computes all available metrics for each setpoint change and returns them in a single DataFrame. This includes: settling time, rise time, overshoot, undershoot, oscillations, and decay characteristics.

Parameters:

Name	Type	Description	Default
actual_uuid	str	UUID of the actual/process value signal	required
tol	float	Absolute tolerance for settling (used if settle_pct is None)	0.0
settle_pct	Optional[float]	Percentage-based tolerance for settling	None
hold	str	Minimum duration to confirm settling	'0s'
lookahead	str	Time window for all analyses	'10m'
rate_threshold	float	Rate threshold for derivative-based settling	0.01

Returns:

Type	Description
DataFrame	DataFrame with comprehensive metrics including:
DataFrame	start, uuid, is_delta
DataFrame	t_settle_seconds, settled (from time_to_settle)
DataFrame	t_settle_derivative_seconds (from time_to_settle_derivative)
DataFrame	rise_time_seconds (from rise_time)
DataFrame	overshoot_abs, overshoot_pct (from overshoot_metrics)
DataFrame	undershoot_abs, undershoot_pct
DataFrame	oscillation_count, oscillation_amplitude, oscillation_freq_hz
DataFrame	decay_rate_lambda, fit_quality_r2
DataFrame	steady_state_error (final error in window)

StartupDetectionEvents

StartupDetectionEvents(
    dataframe: DataFrame,
    target_uuid: str,
    *,
    event_uuid: str = "startup_event",
    value_column: str = "value_double",
    time_column: str = "systime"
)

Bases: Base

Detect equipment startup intervals based on threshold crossings or sustained positive slope in a numeric metric (speed, temperature, etc.).

Schema assumptions (columns): - uuid, sequence_number, systime, plctime, is_delta - value_integer, value_string, value_double, value_bool, value_bytes

detect_startup_by_threshold

detect_startup_by_threshold(
    *,
    threshold: float,
    hysteresis: tuple[float, float] | None = None,
    min_above: str = "0s"
) -> pd.DataFrame

Startup begins at first crossing above threshold (or hysteresis enter) and is valid only if the metric stays above the (exit) threshold for at least min_above.

Returns:

Type	Description
DataFrame	DataFrame with columns: start, end, uuid, is_delta, method, threshold.

detect_startup_by_slope

detect_startup_by_slope(
    *,
    min_slope: float,
    slope_window: str = "0s",
    min_duration: str = "0s"
) -> pd.DataFrame

Startup intervals where per-second slope >= min_slope for at least min_duration. slope_window is accepted for API completeness but the current implementation uses instantaneous slope between samples.

Returns:

Type	Description
DataFrame	DataFrame with columns: start, end, uuid, is_delta, method, min_slope, avg_slope.

detect_startup_multi_signal

detect_startup_multi_signal(
    signals: Dict[str, Dict[str, Any]],
    logic: str = "all",
    *,
    time_tolerance: str = "30s"
) -> pd.DataFrame

Detect startups based on multiple signals with configurable AND/OR logic.

Parameters:

Name	Type	Description	Default
signals	Dict[str, Dict[str, Any]]	Dict mapping uuid to detection config. Each config should contain: - 'method': 'threshold' or 'slope' - For threshold: 'threshold', optional 'hysteresis', 'min_above' - For slope: 'min_slope', optional 'slope_window', 'min_duration'	required
logic	str	'all' (AND - all signals must detect) or 'any' (OR - at least one)	'all'
time_tolerance	str	Maximum time difference between signals for 'all' logic	'30s'

Returns:

Type	Description
DataFrame	DataFrame with columns: start, end, uuid, is_delta, method, signals_triggered, signal_details

detect_startup_adaptive

detect_startup_adaptive(
    *,
    baseline_window: str = "1h",
    sensitivity: float = 2.0,
    min_above: str = "10s",
    lookback_periods: int = 5
) -> pd.DataFrame

Detect startups using adaptive thresholds calculated from historical baseline data.

Parameters:

Name	Type	Description	Default
baseline_window	str	Window size for calculating baseline statistics	'1h'
sensitivity	float	Multiplier for standard deviation (threshold = mean + sensitivity * std)	2.0
min_above	str	Minimum time the value must stay above threshold	'10s'
lookback_periods	int	Number of baseline periods to use for statistics	5

Returns:

Type	Description
DataFrame	DataFrame with columns: start, end, uuid, is_delta, method, adaptive_threshold, baseline_mean, baseline_std

assess_startup_quality

assess_startup_quality(
    startup_events: DataFrame,
    *,
    smoothness_window: int = 5,
    anomaly_threshold: float = 3.0
) -> pd.DataFrame

Assess the quality of detected startup events.

Parameters:

Name	Type	Description	Default
startup_events	DataFrame	DataFrame of detected startup events (must have 'start' and 'end' columns)	required
smoothness_window	int	Window size for calculating smoothness metrics	5
anomaly_threshold	float	Z-score threshold for detecting anomalies	3.0

Returns:

Type	Description
DataFrame	DataFrame with quality metrics for each startup: - duration: Total duration of startup - smoothness_score: Inverse of derivative variance (higher = smoother) - anomaly_flags: Number of anomalous points detected - value_change: Total change in value during startup - avg_rate: Average rate of change - max_value: Maximum value reached - stability_score: Measure of how stable the final state is

track_startup_phases

track_startup_phases(
    phases: List[Dict[str, Any]],
    *,
    min_phase_duration: str = "5s"
) -> pd.DataFrame

Track progression through defined startup phases.

Parameters:

Name	Type	Description	Default
phases	List[Dict[str, Any]]	List of phase definitions, each containing: - 'name': Phase name - 'condition': 'threshold', 'range', or 'slope' - For 'threshold': 'min_value' (value must be >= min_value) - For 'range': 'min_value' and 'max_value' (value in range) - For 'slope': 'min_slope' (slope must be >= min_slope)	required
min_phase_duration	str	Minimum time to stay in phase to be considered valid	'5s'

Returns:

Type	Description
DataFrame	DataFrame with phase transitions: - phase_name: Name of the phase - phase_number: Sequential phase number (0-indexed) - start: Phase start time - end: Phase end time - duration: Time spent in phase - next_phase: Name of the next phase (None for last phase) - completed: Whether full startup sequence completed

detect_failed_startups

detect_failed_startups(
    *,
    threshold: float,
    min_rise_duration: str = "5s",
    max_completion_time: str = "5m",
    completion_threshold: Optional[float] = None,
    required_stability: str = "10s"
) -> pd.DataFrame

Detect failed or aborted startup attempts.

A failed startup is identified when: 1. Value rises above threshold for at least min_rise_duration 2. But fails to reach completion_threshold within max_completion_time 3. Or drops back below threshold before achieving required_stability

Parameters:

Name	Type	Description	Default
threshold	float	Initial threshold that must be crossed to begin startup	required
min_rise_duration	str	Minimum time above threshold to consider it a startup attempt	'5s'
max_completion_time	str	Maximum time allowed to complete startup	'5m'
completion_threshold	Optional[float]	Target threshold for successful completion (default: 2x threshold)	None
required_stability	str	Time that must be maintained at completion level	'10s'

Returns:

Type	Description
DataFrame	DataFrame with columns: start, end, uuid, is_delta, method, failure_reason, max_value_reached, time_to_failure

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.

multi_level_threshold

multi_level_threshold(
    levels: Dict[str, float], direction: str = "above"
) -> 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'

Returns:

Type	Description
DataFrame	DataFrame with columns: start_time, end_time, duration, level, peak_value.

threshold_with_hysteresis

threshold_with_hysteresis(
    high: float, low: float
) -> pd.DataFrame

Alarm intervals with hysteresis to prevent chattering.

Enter alarm when signal crosses high, exit when it drops below low.

Parameters:

Name	Type	Description	Default
high	float	Upper threshold to enter alarm state.	required
low	float	Lower threshold to exit alarm state.	required

Returns:

Type	Description
DataFrame	DataFrame with columns: start_time, end_time, duration, peak_value.

time_above_threshold

time_above_threshold(
    threshold: float, window: str = "1h"
) -> 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'

Returns:

Type	Description
DataFrame	DataFrame with columns: window_start, time_above, pct_above, exceedance_count.

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: window_start, exceedance_count,
DataFrame	total_duration, trend_direction.

RateOfChangeEvents

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

Bases: Base

Engineering: Rate of Change Events

Detect rapid changes and step jumps in a numeric signal.

Methods: - detect_rapid_change: Flag intervals where rate of change exceeds threshold. - rate_statistics: Per-window rate of change statistics. - detect_step_changes: Sudden value jumps within a short duration.

detect_rapid_change

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

Flag intervals where rate of change exceeds threshold.

Parameters:

Name	Type	Description	Default
threshold	float	Minimum absolute rate (units/second) to flag.	required
window	str	Minimum duration to group rapid change intervals.	'1m'

Returns:

Type	Description
DataFrame	DataFrame with columns: start_time, end_time, max_rate, direction.

rate_statistics

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

Per-window rate of change statistics.

Parameters:

Name	Type	Description	Default
window	str	Resample window.	'1h'

Returns:

Type	Description
DataFrame	DataFrame with columns: window_start, mean_rate, std_rate,
DataFrame	max_rate, min_rate.

detect_step_changes

detect_step_changes(
    min_delta: float, max_duration: str = "5s"
) -> pd.DataFrame

Detect sudden value jumps within a short duration.

Parameters:

Name	Type	Description	Default
min_delta	float	Minimum absolute value change to qualify.	required
max_duration	str	Maximum time window for the step to occur.	'5s'

Returns:

Type	Description
DataFrame	DataFrame with columns: time, value_before, value_after, delta, duration.

SteadyStateDetectionEvents

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

Bases: Base

Engineering: Steady-State Detection

Identify when a process signal has settled into a steady operating state (low variance, no trend) versus transient/dynamic periods.

Methods: - detect_steady_state: Intervals where rolling std stays below threshold. - detect_transient_periods: Inverse — intervals where signal is changing. - steady_state_statistics: Summary of steady vs transient time. - steady_state_value_bands: Operating band (mean +/- std) per steady interval.

detect_steady_state

detect_steady_state(
    window: str = "5m",
    std_threshold: float = 1.0,
    min_duration: str = "10m",
) -> pd.DataFrame

Detect intervals where signal is in steady state.

Parameters:

Name	Type	Description	Default
window	str	Rolling window for std computation.	'5m'
std_threshold	float	Maximum rolling std to consider steady.	1.0
min_duration	str	Minimum duration of a steady interval.	'10m'

Returns:

Type	Description
DataFrame	DataFrame with columns: start, end, uuid, is_delta,
DataFrame	mean_value, std_value, duration_seconds.

detect_transient_periods

detect_transient_periods(
    window: str = "5m", std_threshold: float = 1.0
) -> pd.DataFrame

Detect intervals where signal is in transient/dynamic state.

Parameters:

Name	Type	Description	Default
window	str	Rolling window for std computation.	'5m'
std_threshold	float	Minimum rolling std to consider transient.	1.0

Returns:

Type	Description
DataFrame	DataFrame with columns: start, end, uuid, is_delta,
DataFrame	max_std, duration_seconds.

steady_state_statistics

steady_state_statistics(
    window: str = "5m",
    std_threshold: float = 1.0,
    min_duration: str = "10m",
) -> Dict[str, Any]

Summary statistics of steady vs transient time.

Returns:

Type	Description
Dict[str, Any]	Dict with: total_steady_seconds, total_transient_seconds,
Dict[str, Any]	steady_pct, num_steady_periods, avg_steady_duration_seconds.

steady_state_value_bands

steady_state_value_bands(
    window: str = "5m",
    std_threshold: float = 1.0,
    min_duration: str = "10m",
) -> pd.DataFrame

Operating band (mean +/- std) for each steady-state interval.

Returns:

Type	Description
DataFrame	DataFrame with columns: start, end, mean_value, lower_band,
DataFrame	upper_band, duration_seconds.

SignalComparisonEvents

SignalComparisonEvents(
    dataframe: DataFrame,
    reference_uuid: str,
    *,
    event_uuid: str = "eng:signal_comparison",
    value_column: str = "value_double",
    time_column: str = "systime"
)

Bases: Base

Engineering: Signal Comparison

Compare two related signals (e.g. setpoint vs actual, sensor A vs sensor B) and detect divergence, compute deviation statistics, and track correlation.

Methods: - detect_divergence: Intervals where |actual - reference| exceeds tolerance. - deviation_statistics: Per-window MAE, max error, RMSE, bias. - tracking_error_trend: Whether deviation is growing or shrinking over time. - correlation_windows: Per-window Pearson correlation.

detect_divergence

detect_divergence(
    actual_uuid: str,
    tolerance: float,
    min_duration: str = "1m",
) -> pd.DataFrame

Detect intervals where |actual - reference| > tolerance.

Parameters:

Name	Type	Description	Default
actual_uuid	str	UUID of the actual/comparison signal.	required
tolerance	float	Maximum acceptable absolute deviation.	required
min_duration	str	Minimum duration of divergence interval.	'1m'

Returns:

Type	Description
DataFrame	DataFrame with columns: start, end, uuid, is_delta,
DataFrame	max_deviation, mean_deviation, direction.

deviation_statistics

deviation_statistics(
    actual_uuid: str, window: str = "1h"
) -> pd.DataFrame

Per-window deviation statistics.

Returns:

Type	Description
DataFrame	DataFrame with columns: window_start, mae, max_error, rmse, bias.

tracking_error_trend

tracking_error_trend(
    actual_uuid: str, window: str = "1D"
) -> pd.DataFrame

Track whether deviation is growing or shrinking over time.

Returns:

Type	Description
DataFrame	DataFrame with columns: window_start, mae, trend_slope,
DataFrame	trend_direction.

correlation_windows

correlation_windows(
    actual_uuid: str, window: str = "1h"
) -> pd.DataFrame

Per-window Pearson correlation between reference and actual.

Returns:

Type	Description
DataFrame	DataFrame with columns: window_start, correlation, sample_count.

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.

Returns:

Type	Description
DataFrame	DataFrame with columns: window_start, min_value, p5,
DataFrame	mean_value, p95, max_value, range_width.

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.

Returns:

Type	Description
DataFrame	DataFrame with columns: start, end, uuid, is_delta,
DataFrame	prev_mean, new_mean, shift_magnitude.

time_in_range

time_in_range(
    lower: float, upper: float, window: str = "1h"
) -> pd.DataFrame

Percentage of time within a defined range per window.

Returns:

Type	Description
DataFrame	DataFrame with columns: window_start, time_in_range_pct,
DataFrame	time_below_pct, time_above_pct.

value_distribution

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

Histogram of signal values.

Returns:

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

WarmUpCoolDownEvents

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

Bases: Base

Engineering: Warm-Up / Cool-Down Analysis

Detect and characterize warm-up and cool-down curves — common for ovens, extruders, molds, hydraulic systems. Analyzes the shape, consistency, and timing of monotonic temperature/pressure ramps.

Methods: - detect_warmup: Intervals where signal rises by at least min_rise. - detect_cooldown: Intervals where signal falls by at least min_fall. - warmup_consistency: Compare warm-up durations and rates for consistency. - time_to_target: Time from warmup start until target value is reached.

detect_warmup

detect_warmup(
    min_rise: float, min_duration: str = "1m"
) -> pd.DataFrame

Detect intervals where signal rises by at least min_rise.

Parameters:

Name	Type	Description	Default
min_rise	float	Minimum total value increase to qualify.	required
min_duration	str	Minimum duration of the ramp.	'1m'

Returns:

Type	Description
DataFrame	DataFrame with columns: start, end, uuid, is_delta,
DataFrame	start_value, end_value, rise, duration_seconds, avg_rate.

detect_cooldown

detect_cooldown(
    min_fall: float, min_duration: str = "1m"
) -> pd.DataFrame

Detect intervals where signal falls by at least min_fall.

Parameters:

Name	Type	Description	Default
min_fall	float	Minimum total value decrease to qualify (positive number).	required
min_duration	str	Minimum duration of the ramp.	'1m'

Returns:

Type	Description
DataFrame	DataFrame with columns: start, end, uuid, is_delta,
DataFrame	start_value, end_value, fall, duration_seconds, avg_rate.

warmup_consistency

warmup_consistency(
    min_rise: float, min_duration: str = "1m"
) -> pd.DataFrame

Compare warm-up curves for consistency in duration and rate.

Returns:

Type	Description
DataFrame	DataFrame with columns: warmup_index, start, duration_seconds,
DataFrame	avg_rate, deviation_from_median_duration.

time_to_target

time_to_target(
    target_value: float, direction: str = "rising"
) -> pd.DataFrame

Time from each ramp start until target value is reached.

Parameters:

Name	Type	Description	Default
target_value	float	The target value to reach.	required
direction	str	'rising' or 'falling'.	'rising'

Returns:

Type	Description
DataFrame	DataFrame with columns: start, target_reached_at,
DataFrame	time_to_target_seconds, overshoot.

ProcessWindowEvents

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

Bases: Base

Engineering: Process Window Analysis

Analyze time-windowed process statistics for shift reports, SPC context, and trend monitoring. Answers 'how is my process doing this hour/shift/day?'

Methods: - windowed_statistics: Per-window count, mean, std, min, max, percentiles. - detect_mean_shift: Flag windows where mean shifts significantly. - detect_variance_change: Flag windows where variance changes significantly. - window_comparison: Compare each window to overall baseline.

windowed_statistics

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

Per-window descriptive statistics.

Returns:

Type	Description
DataFrame	DataFrame with columns: window_start, count, mean, std,
DataFrame	min, max, median, p25, p75, range.

detect_mean_shift

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

Flag windows where mean shifts significantly from the previous window.

A shift is detected when |current_mean - prev_mean| > sensitivity * prev_std.

Returns:

Type	Description
DataFrame	DataFrame with columns: start, end, uuid, is_delta,
DataFrame	prev_mean, current_mean, shift_sigma.

detect_variance_change

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

Flag windows where variance changes significantly.

A change is detected when (current_std / prev_std) > ratio_threshold or < (1 / ratio_threshold).

Returns:

Type	Description
DataFrame	DataFrame with columns: start, end, uuid, is_delta,
DataFrame	prev_std, current_std, variance_ratio.

window_comparison

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

Compare each window mean to the overall baseline.

Returns:

Type	Description
DataFrame	DataFrame with columns: window_start, mean, z_score_vs_global,
DataFrame	is_anomalous.

ControlLoopHealthEvents

ControlLoopHealthEvents(
    dataframe: DataFrame,
    setpoint_uuid: str,
    actual_uuid: str,
    *,
    output_uuid: Optional[str] = None,
    event_uuid: str = "eng:control_loop_health",
    value_column: str = "value_double",
    time_column: str = "systime"
)

Bases: Base

Engineering: Control Loop Health

Continuously assess PID/control loop health from setpoint + actual pairs, independent of setpoint changes. Computes error integrals, detects oscillation in the error signal, and checks for valve saturation.

Methods: - error_integrals: Per-window IAE, ISE, ITAE, bias. - detect_oscillation: Sustained oscillation in the error signal. - output_saturation: Valve pegged at limits. - loop_health_summary: Shift-level report card.

error_integrals

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

Per-window error integrals for control loop performance.

Parameters:

Name	Type	Description	Default
window	str	Resample window (e.g. '1h', '8h').	'1h'

Returns:

Type	Description
DataFrame	DataFrame with columns: window_start, iae, ise, itae, bias,
DataFrame	sample_count.

detect_oscillation

detect_oscillation(
    window: str = "5min", min_crossings: int = 4
) -> pd.DataFrame

Detect sustained oscillation in the error signal.

Parameters:

Name	Type	Description	Default
window	str	Analysis window size.	'5min'
min_crossings	int	Minimum zero-crossings to flag oscillation.	4

Returns:

Type	Description
DataFrame	DataFrame with columns: start, end, uuid, is_delta,
DataFrame	crossing_count, estimated_period_seconds, amplitude,
DataFrame	damping_direction.

output_saturation

output_saturation(
    high_limit: float = 100.0,
    low_limit: float = 0.0,
    window: str = "1h",
) -> pd.DataFrame

Detect when controller output is pegged at limits.

Requires output_uuid in constructor.

Returns:

Type	Description
DataFrame	DataFrame with columns: window_start, pct_time_at_high,
DataFrame	pct_time_at_low, pct_time_saturated, longest_saturation_seconds.

loop_health_summary

loop_health_summary(window: str = '8h') -> pd.DataFrame

Shift-level report card combining all loop health metrics.

Returns:

Type	Description
DataFrame	DataFrame with columns: window_start, iae, bias,
DataFrame	oscillation_count, pct_saturated, health_grade.

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.

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"
)

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.

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: window_start, total_input,
DataFrame	total_output, imbalance, imbalance_pct, balanced.

imbalance_trend

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

Track whether imbalance is growing, shrinking, or stable.

Returns:

Type	Description
DataFrame	DataFrame with columns: window_start, imbalance_pct,
DataFrame	rolling_avg_imbalance, trend_direction.

detect_balance_exceedance

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

Detect sustained imbalance events.

Returns:

Type	Description
DataFrame	DataFrame with columns: start, end, uuid, is_delta,
DataFrame	avg_imbalance_pct, max_imbalance_pct, duration_seconds,
DataFrame	likely_cause.

contribution_breakdown

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

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

Returns:

Type	Description
DataFrame	DataFrame with columns: window_start, uuid, role, value,
DataFrame	pct_of_total.

ProcessStabilityIndex

ProcessStabilityIndex(
    dataframe: DataFrame,
    signal_uuid: str,
    *,
    target: Optional[float] = None,
    lower_spec: Optional[float] = None,
    upper_spec: Optional[float] = None,
    event_uuid: str = "eng:stability_index",
    value_column: str = "value_double",
    time_column: str = "systime"
)

Bases: Base

Engineering: Process Stability Index

Generate a single 0-100 stability score per shift/day for a signal. Answers 'is my process running well today?' with one number.

Methods: - stability_score: Composite 0-100 score per window. - score_trend: Is stability improving or degrading? - worst_periods: N worst-scoring windows. - stability_comparison: Compare each window to best-observed.

stability_score

stability_score(window: str = '8h') -> pd.DataFrame

Composite 0-100 stability score per window.

Four sub-scores (each 0-25): - variance_score: low std = high score - bias_score: on-target = high score - excursion_score: in-spec = high score - smoothness_score: low point-to-point jitter = high score

Returns:

Type	Description
DataFrame	DataFrame with columns: window_start, stability_score,
DataFrame	variance_score, bias_score, excursion_score, smoothness_score,
DataFrame	grade.

score_trend

score_trend(
    window: str = "8h", n_windows: int = 7
) -> pd.DataFrame

Track whether stability is improving or degrading.

Returns:

Type	Description
DataFrame	DataFrame with columns: window_start, stability_score,
DataFrame	rolling_avg, trend_direction, score_change.

worst_periods

worst_periods(
    window: str = "1h", n: int = 5
) -> pd.DataFrame

Return the N worst-scoring windows.

Returns:

Type	Description
DataFrame	DataFrame with columns: window_start, stability_score,
DataFrame	variance_score, bias_score, excursion_score, smoothness_score,
DataFrame	primary_issue.

stability_comparison

stability_comparison(window: str = '8h') -> pd.DataFrame

Compare each window to the best-observed window.

Returns:

Type	Description
DataFrame	DataFrame with columns: window_start, stability_score,
DataFrame	best_score, gap_to_best, pct_of_best.