shewhart_control_chart

Shewhart control chart algorithm for online change-point detection.

This module provides ShewhartControlChart, an online detector that tracks running mean and variance, computing a standardized deviation of a sliding-window mean from the global running mean.

class pysatl_cpd.algorithms.online.control_charts.shewhart_control_chart.ShewhartControlChartState(*, is_in_learning_period=False, mean=0.0, variance=0.0, samples_count=0, window_contents=<factory>)

Bases: OnlineAlgorithmState

State snapshot of the Shewhart control chart algorithm.

This class captures the internal state of the algorithm at a specific point in time, allowing for state inspection and debugging.

Variables:

• mean – Current running mean estimate.

• variance – Current running variance estimate.

• samples_count – Number of observations processed so far.

• window_contents – Current contents of the sliding window in order.

Parameters:

• is_in_learning_period (bool)

• mean (Number)

• variance (Number)

• samples_count (int)

• window_contents (list[Number])

mean: Number = 0.0

variance: Number = 0.0

samples_count: int = 0

window_contents: list[Number]

property standard_deviation: Number

property window_sum: Number

property window_size: int

property window_mean: Number

__hash__()

Return a stable hash for the Shewhart state snapshot.

Return type:

int

__init__(*, is_in_learning_period=False, mean=0.0, variance=0.0, samples_count=0, window_contents=<factory>)

Parameters:

• is_in_learning_period (bool)

• mean (Number)

• variance (Number)

• samples_count (int)

• window_contents (list[Number])

Return type:

None

class pysatl_cpd.algorithms.online.control_charts.shewhart_control_chart.ShewhartControlChartConfiguration(*, learning_period_size=0, window_size=0)

Bases: OnlineAlgorithmConfiguration

Configuration parameters for the Shewhart control chart algorithm.

Variables:

window_size – Size of the sliding window used to compute the local mean statistic.

Raises:

• ValueError – If learning_period_size is not positive.

• ValueError – If window_size is not positive.

• ValueError – If window_size is greater than learning_period_size.

Parameters:

• learning_period_size (int)

• window_size (int)

window_size: int = 0

__post_init__()

Validate configuration parameters.

Return type:

None

__repr__()

Return a short string representation of the configuration.

Return type:

str

__hash__()

Return a stable hash for the Shewhart configuration.

Return type:

int

__init__(*, learning_period_size=0, window_size=0)

Parameters:

• learning_period_size (int)

• window_size (int)

Return type:

None

class pysatl_cpd.algorithms.online.control_charts.shewhart_control_chart.ShewhartControlChart(learning_period_size, window_size)

Bases: OnlineAlgorithm[Number, ShewhartControlChartConfiguration, ShewhartControlChartState]

Shewhart control chart with sliding-window statistic.

This algorithm maintains running estimates of mean and variance, and computes a standardized deviation between the sliding-window mean and the global running mean. The statistic follows the formula:

\[S_t = \frac{|\bar{x}_w - \mu| \sqrt{w}}{\sigma}\]

where: - \(\bar{x}_w\) is the mean of the last window_size observations - \(\mu\) is the running mean of all observations - \(w\) is the window size - \(\sigma\) is the running standard deviation

Parameters:

• learning_period_size (int) – Number of initial observations used for training before non-zero statistics are emitted. Must be positive.

• window_size (int) – Size of the sliding window used to compute the local mean statistic. Must be positive and less than or equal to learning_period_size.

__init__(learning_period_size, window_size)

Parameters:

• learning_period_size (int)

• window_size (int)

Return type:

None

property configuration: ShewhartControlChartConfiguration

Current algorithm configuration.

Return type:

ShewhartControlChartConfiguration

property state: ShewhartControlChartState

Materialise an immutable state snapshot.

Return type:

ShewhartControlChartState

process(observation)

Ingest one observation and return the chart statistic value.

Computes the standardised absolute deviation between the sliding-window mean and the running mean. Returns 0 during the learning period or when the running standard deviation is zero.

Parameters:

observation (double | int | float) – New scalar observation.

Return type:

double | int | float

reset()

Reset the algorithm to its initial state.

Clears all internal statistics, counters, and the sliding window.

Return type:

None

recreate()

Create a fresh chart with identical configuration and reset state.

Return type:

Self