setpoint_events

setpoint_events ¤

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)