tolerance_deviation

tolerance_deviation ¤

ToleranceDeviationEvents ¤

ToleranceDeviationEvents(
    dataframe: DataFrame,
    tolerance_column: str,
    actual_column: str,
    tolerance_uuid: str | None = None,
    actual_uuid: str | None = None,
    event_uuid: str | None = None,
    compare_func: Callable[
        [Series, Series], Series
    ] = operator.ge,
    time_threshold: str = "5min",
    upper_tolerance_uuid: str | None = None,
    lower_tolerance_uuid: str | None = None,
    warning_threshold: float = 0.8,
    tolerance_lag: str = "0s",
)

Bases: Base

Inherits from Base and processes DataFrame data for specific events, comparing tolerance and actual values.

Enhanced features: - Upper and lower tolerances (two-sided, or one-sided with only one of them) - Warning zones with configurable thresholds - Deviation magnitude tracking (absolute and percentage) - Severity level classification (minor, major, critical) - Process capability indices (Cp, Cpk, Pp, Ppk) - Time-lagged tolerance application

Example

import pandas as pd, ts_shape act = ts_shape.make_timeseries(["act"], n_points=60, n_outliers=3) limits = pd.DataFrame({"systime": act["systime"].min(), "uuid": ["usl", "lsl"], ... "value_double": [103.0, 97.0]}) tde = ts_shape.ToleranceDeviationEvents( ... pd.concat([limits, act]), "value_double", "value_double", actual_uuid="act", ... upper_tolerance_uuid="usl", lower_tolerance_uuid="lsl") out = tde.detect_deviations() out[["systime", "value_double", "severity"]].round({"value_double": 1}) systime value_double severity 4 2025-01-01 00:02:00 110.0 major 33 2025-01-01 00:16:30 111.2 major 49 2025-01-01 00:24:30 112.1 major

Initializes the ToleranceDeviationEvents with specific event attributes. Inherits the sorted dataframe from the Base class.

Parameters:

Name	Type	Description	Default
`dataframe`	`DataFrame`	Input DataFrame with measurement data	required
`tolerance_column`	`str`	Column name containing tolerance values	required
`actual_column`	`str`	Column name containing actual measurement values	required
`tolerance_uuid`	`str \| None`	Deprecated (removed in the next major release; passing it without `upper_tolerance_uuid`/`lower_tolerance_uuid` emits a `DeprecationWarning`). UUID of a single tolerance signal that is compared with the actual values through `compare_func`. Use `upper_tolerance_uuid` and/or `lower_tolerance_uuid` instead: a single upper limit is `upper_tolerance_uuid` alone.	`None`
`actual_uuid`	`str \| None`	UUID for actual measurements. Required: a `ValueError` is raised when it is missing.	`None`
`event_uuid`	`str \| None`	UUID for generated events (default None)	`None`
`compare_func`	`Callable[[Series, Series], Series]`	Comparison used by the deprecated single `tolerance_uuid` path only (default: `operator.ge`, so `actual >= tolerance` is a deviation).	`ge`
`time_threshold`	`str`	Time window for grouping events (default: '5min')	`'5min'`
`upper_tolerance_uuid`	`str \| None`	UUID for the upper tolerance limit. Given alone, it is a one-sided upper limit.	`None`
`lower_tolerance_uuid`	`str \| None`	UUID for the lower tolerance limit. Given alone, it is a one-sided lower limit.	`None`
`warning_threshold`	`float`	Threshold ratio for warning zone (default: 0.8 = 80% of tolerance)	`0.8`
`tolerance_lag`	`str`	Time lag for tolerance application (default: '0s')	`'0s'`

detect_deviations ¤

detect_deviations() -> pd.DataFrame

Processes DataFrame to apply tolerance checks, group events by time, and generate an events DataFrame.

Enhanced with: - Upper/lower tolerances (two-sided or one-sided) - Deviation magnitude tracking (absolute and percentage) - Warning zones - Severity level classification - Time-lagged tolerance application

Out-of-tolerance samples of the actual signal closer than time_threshold form one event, reported as its first and last row; an event of a single sample is reported as that one row.

Returns:

Name	Type	Description
	`DataFrame`	pd.DataFrame: A DataFrame of processed and grouped event data with enhanced metrics.
`Columns`	`DataFrame`	systime, uuid (the event uuid), source_uuid (the actual
	`DataFrame`	measurement signal's uuid), the value columns (`actual_column`
	`DataFrame`	holds the measured value), is_delta, deviation_abs,
	`DataFrame`	deviation_pct and severity.

capability_indices ¤

capability_indices(
    target_value: float | None = ...,
    *,
    as_frame: Literal[True] = ...,
    sigma_method: SigmaMethod = ...
) -> pd.DataFrame

capability_indices(
    target_value: float | None = ...,
    *,
    as_frame: Literal[False],
    sigma_method: SigmaMethod = ...
) -> dict[str, float]

capability_indices(
    target_value: float | None = None,
    *,
    as_frame: bool = True,
    sigma_method: SigmaMethod = "moving_range"
) -> pd.DataFrame | dict[str, float]

Calculate process capability indices (Cp, Cpk, Pp, Ppk and Cpm).

Process capability indices measure how well a process meets specification limits (AIAG SPC manual; Montgomery, Introduction to Statistical Quality Control, section 8.3): - Cp = (USL - LSL) / 6σ_within: potential capability assuming perfect centering - Cpk = min(USL - mean, mean - LSL) / 3σ_within: accounts for centering - Pp / Ppk: the same formulas with the overall σ - Cpm (only when target_value is given): the Taguchi index (USL - LSL) / 6 sqrt(σ² + (mean - T)²) = Pp / sqrt(1 + ((mean - T) / σ)²) with the overall σ, which penalizes distance from the target T

The overall σ (std) is the sample standard deviation (ddof=1) of all actual measurements. The within (short-term) σ (std_within) is, with the default sigma_method="moving_range", the individuals-chart estimate MR-bar / 1.128 from consecutive measurements in time order; with sigma_method="std" it is the overall σ, so Cp/Cpk equal Pp/Ppk (the behavior before October 2026).

With a one-sided spec (only an upper or only a lower limit) Cp/Pp are NaN and Cpk/Ppk are the one-sided index (CPU or CPL); the missing limit is reported as NaN.

Measurements without spread (constant values, a single measurement or only missing values) give NaN indices and a :class:~ts_shape.errors.DataQualityWarning, as in :class:CapabilityTrendingEvents.

Parameters:

Name	Type	Description	Default
`target_value`	`float \| None`	Target/nominal value for the process. If None, the midpoint of the tolerances (or the single limit of a one-sided spec) is reported as `target` and no `Cpm` is computed.	`None`
`sigma_method`	`SigmaMethod`	Within σ for Cp/Cpk: `"moving_range"` (default, `MR-bar / 1.128`) or `"std"` (the overall σ).	`'moving_range'`
`as_frame`	`bool`	When True (default), return a one-row DataFrame (see below). `as_frame=False` returns the dictionary form; it is deprecated, emits a `DeprecationWarning` and will be removed in the next major release.	`True`

Returns:

Type	Description
`DataFrame \| dict[str, float]`	With `as_frame=True` (default), a one-row summary DataFrame with
`DataFrame \| dict[str, float]`	columns start, end, duration_seconds (first to last actual
`DataFrame \| dict[str, float]`	measurement), uuid (event uuid), source_uuid (actual uuid), Cp,
`DataFrame \| dict[str, float]`	Cpk, Pp, Ppk, Cpm (always present; NaN unless `target_value`
`DataFrame \| dict[str, float]`	is given), mean, std (overall σ), std_within (the σ behind Cp /
`DataFrame \| dict[str, float]`	Cpk), usl, lsl, target, and sample_count (the
`DataFrame \| dict[str, float]`	number of measurements the indices are computed from).
`DataFrame \| dict[str, float]`	With `as_frame=False` (deprecated), a dictionary containing: - 'Cp': Process capability - 'Cpk': Process capability index - 'Pp': Process performance - 'Ppk': Process performance index - 'Cpm': Taguchi capability index; only present when `target_value` is given (NaN for a one-sided spec) - 'mean': Process mean - 'std': Overall process standard deviation - 'std_within': Within σ used for Cp / Cpk - 'usl': Upper specification limit - 'lsl': Lower specification limit - 'target': Target value used

Note

Values > 1.33 are generally considered acceptable
Values > 1.67 are considered good