generalized_cusum

Generalized CUSUM source implementation.

This module provides GeneralizedCUSUM, a configurable online detector that combines three components:

an estimating schema,
a monitoring schema,
and a change-point function (CPF).

Concrete CUSUM algorithms configure these components via factory functions.

class pysatl_cpd.algorithms.online.cusum.abstracts.generalized_cusum.GeneralizedCUSUMConfiguration(*, learning_period_size=0, adaptive_estimation=True)[source]

Bases: OnlineAlgorithmConfiguration

Configuration for Generalized CUSUM algorithms.

Parameters:

learning_period_size (int)
adaptive_estimation (bool)

adaptive_estimation: bool = True

__hash__()[source]

Return a stable hash for the CUSUM configuration.

Return type:: int

__init__(*, learning_period_size=0, adaptive_estimation=True)

Parameters:

learning_period_size (int)
adaptive_estimation (bool)

Return type:

None

class pysatl_cpd.algorithms.online.cusum.abstracts.generalized_cusum.GeneralizedCUSUMState(*, is_in_learning_period=False, statistics)[source]

Bases: OnlineAlgorithmState, Generic

State for Generalized CUSUM algorithms.

Parameters:

is_in_learning_period (bool)
statistics (ISchemaEstimates)

statistics: ISchemaEstimates

__hash__()[source]

Return a stable hash for the CUSUM state snapshot.

Return type:: int

__init__(*, is_in_learning_period=False, statistics)

Parameters:

is_in_learning_period (bool)
statistics (ISchemaEstimates)

Return type:

None

class pysatl_cpd.algorithms.online.cusum.abstracts.generalized_cusum.GeneralizedCUSUM(configuration, estimating_schema, monitoring_schema, changepoint_func, adaptive_estimation=True)[source]

Bases: OnlineAlgorithm, Generic

Base class for configurable online CUSUM detectors.

Parameters:

configuration (TypeVar(ConfigurationT, bound= GeneralizedCUSUMConfiguration)) – Algorithm configuration instance.
estimating_schema (IEstimatingSchema[TypeVar(DataT), TypeVar(EstimatesT, bound= ISchemaEstimates)]) – Schema that estimates model parameters from data.
monitoring_schema (IMonitoringSchema[TypeVar(DataT), TypeVar(EstimatesT, bound= ISchemaEstimates), TypeVar(MonitoringT)]) – Schema that transforms observations into monitoring-space residuals.
changepoint_func (ICusumChangepointFunc[TypeVar(MonitoringT)]) – CUSUM change-point function applied to monitoring residuals.
adaptive_estimation (bool) – Whether to update estimates online after training.

__init__(configuration, estimating_schema, monitoring_schema, changepoint_func, adaptive_estimation=True)[source]

Parameters:

configuration (ConfigurationT)
estimating_schema (IEstimatingSchema)
monitoring_schema (IMonitoringSchema)
changepoint_func (ICusumChangepointFunc)
adaptive_estimation (bool)

Return type:

None

abstract property configuration: ConfigurationT

Configuration parameters of the algorithm.

Returns:: Immutable configuration object containing algorithm settings.
Return type:: ConfigurationT
Raises:: NotImplementedError – Subclasses must implement this property.

abstract property state: StateT

Current internal state snapshot of the algorithm.

Returns:: Immutable state snapshot of the algorithm.
Return type:: StateT
Raises:: NotImplementedError – Subclasses must implement this property.

residual(argument)[source]

Transform a raw observation into monitoring-space residual.

Delegates to the monitoring schema.

Parameters:: argument (TypeVar(DataT)) – Raw input observation.
Return type:: TypeVar(MonitoringT)

property estimating_schema: IEstimatingSchema

Estimating schema instance.

Return type:: IEstimatingSchema[DataT, EstimatesT]

property monitoring_schema: IMonitoringSchema

Monitoring schema instance.

Return type:: IMonitoringSchema[DataT, EstimatesT, MonitoringT]

property changepoint_func: ICusumChangepointFunc

CUSUM change-point function instance.

Return type:: ICusumChangepointFunc[MonitoringT]

property dim: int | None

Observation dimensionality detected from the first sample.

Returns:: None before the first process call.
Return type:: int or None

property estimates: EstimatesT

Current model parameter estimates from the estimating schema.

Return type:: EstimatesT

property cpf: float

Current scalar change-point statistic value.

Return type:: float

process(observation)[source]

Ingest one observation and return the change-point statistic.

During training (learning_period_size steps) accumulates samples and returns 0. After training, updates the CUSUM change-point function and optionally the estimating schema (adaptive mode).

Parameters:: observation (TypeVar(DataT)) – New data point (first call sets the dimensionality).
Returns:: Change-point statistic value.
Return type:: double | int | float

reset()[source]

Reset the detector to its initial (training) state.

Clears all component states, training buffer, and flags.

Return type:: None

recreate()[source]

Create a fresh copy with the same configuration and reset state.

Returns:: A new instance in initial (training) state.
Return type:: Self