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.

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