sensor_drift

sensor_drift ¤

Sensor drift: slow calibration loss of a measurement against a reference.

Detects zero (offset) drift and span (gain) drift against a reference, tracks the drift trend per window, and scores overall calibration health.

SensorDriftEvents ¤

SensorDriftEvents(
    dataframe: DataFrame,
    signal_uuid: str,
    *,
    reference_uuid: str | None = None,
    reference_value: float | None = None,
    value_column: str = "value_double",
    event_uuid: str = "quality:sensor_drift",
    time_column: str = "systime"
)

Bases: Base

Quality: Sensor Calibration Drift Detection

Detect gradual calibration drift in inline sensors by tracking measurement behavior against reference values or historical baselines.

Reference can be provided as a UUID (time-aligned signal in the DataFrame) or as a fixed float value.

Methods: - detect_zero_drift: Track mean offset from baseline per window. - detect_span_drift: Track measurement sensitivity changes over time. - drift_trend: Rolling linear trend analysis on signal statistics. - calibration_health: Composite health score per window.

Example

A probe that should read 10.0 and drifts upward by 2.0 over two days:

import ts_shape df = ts_shape.make_timeseries(["probe"], n_points=48, freq="1h", ... baseline=10, noise=0.1, drift=2.0) drift = ts_shape.SensorDriftEvents(df, "probe", reference_value=10.0) drift.detect_zero_drift(window="8h", threshold=0.5)[ ... ["start", "mean_offset", "severity"]].round({"mean_offset": 2}) start mean_offset severity 0 2025-01-01 00:00:00 0.12 low 1 2025-01-01 08:00:00 0.51 critical 2 2025-01-01 16:00:00 0.84 critical 3 2025-01-02 00:00:00 1.20 critical 4 2025-01-02 08:00:00 1.50 critical 5 2025-01-02 16:00:00 1.88 critical

detect_zero_drift ¤

detect_zero_drift(
    window: str = "8h", threshold: float | None = None
) -> pd.DataFrame

Track mean offset from baseline per window.

Parameters:

Name	Type	Description	Default
`window`	`str`	Resample window size.	`'8h'`
`threshold`	`float \| None`	Offset threshold for severity. Auto-calculated as 3x std of first window if not provided.	`None`

Returns:

Type	Description
`DataFrame`	DataFrame with columns: start, end, duration_seconds, uuid,
`DataFrame`	source_uuid, mean_offset, drift_rate, severity.

detect_span_drift ¤

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

Track measurement sensitivity changes over time.

Requires reference_uuid or reference_value. Computes ratio of signal mean to reference per window to detect gain/span changes.

Parameters:

Name	Type	Description	Default
`window`	`str`	Resample window size.	`'8h'`

Returns:

Type	Description
`DataFrame`	DataFrame with columns: start, end, duration_seconds, uuid,
`DataFrame`	source_uuid, sensitivity, sensitivity_change_pct.
`DataFrame`	`end` is `start` plus one `window`.

drift_trend ¤

drift_trend(
    window: str = "1D", metric: str = "mean"
) -> pd.DataFrame

Rolling trend analysis on signal statistics.

Parameters:

Name	Type	Description	Default
`window`	`str`	Resample window size.	`'1D'`
`metric`	`str`	Statistic to trend ('mean' or 'std').	`'mean'`

Returns:

Type	Description
`DataFrame`	DataFrame with columns: start, end, duration_seconds, uuid,
`DataFrame`	source_uuid, value, slope, r_squared, direction.
`DataFrame`	`end` is `start` plus one `window`.

calibration_health ¤

calibration_health(
    window: str = "8h", tolerance: float | None = None
) -> pd.DataFrame

Composite calibration health score per window.

Parameters:

Name	Type	Description	Default
`window`	`str`	Resample window size.	`'8h'`
`tolerance`	`float \| None`	Acceptable measurement tolerance. Used to normalize bias and precision into a 0-100 score.	`None`

Returns:

Type	Description
`DataFrame`	DataFrame with columns: start, end, duration_seconds, uuid,
`DataFrame`	source_uuid, bias, precision, health_score.
`DataFrame`	`end` is `start` plus one `window`.