ionline_algorithm

Interface for online change-point detection algorithms.

This module defines the abstract OnlineAlgorithm protocol used by solvers and concrete detector implementations.

Examples

>>> from pysatl_cpd.typedefs import Number
>>> from dataclasses import dataclass
>>>
>>> @dataclass(frozen=True, kw_only=True)
... class MyConfig(OnlineAlgorithmConfiguration):
...     window_size: int = 10
...
>>> @dataclass(frozen=True, kw_only=True)
... class MyState(OnlineAlgorithmState):
...     values: list[float] = field(default_factory=list)
...
>>> class MyAlgorithm(OnlineAlgorithm[float, MyConfig, MyState]):
...     def __init__(self, config: MyConfig) -> None:
...         self._config = config
...         self._state = MyState()
...         self._name = "MyAlgorithm"
...
...     @property
...     def name(self) -> str:
...         return self._name
...
...     @property
...     def configuration(self) -> MyConfig:
...         return self._config
...
...     @property
...     def state(self) -> MyState:
...         return self._state
...
...     def process(self, observation: float) -> Number:
...         new_values = self._state.values + [observation]
...         if len(new_values) > self._config.window_size:
...             new_values = new_values[1:]
...         self._state = MyState(values=new_values)
...         return sum(new_values) / len(new_values) if new_values else 0.0
...
...     def reset(self) -> None:
...         self._state = MyState()
...
...     @classmethod
...     def recreate(cls, configuration: MyConfig, state: MyState | None = None) -> "MyAlgorithm":
...         algorithm = cls(configuration)
...         if state is not None:
...             algorithm._state = state
...         return algorithm
>>>
>>> config = MyConfig(window_size=5)
>>> algorithm = MyAlgorithm(config)
>>> algorithm.name
'MyAlgorithm'
>>> algorithm.process(5.0)
5.0

class pysatl_cpd.core.online.ionline_algorithm.OnlineAlgorithmState(*, is_in_learning_period=False)

Bases: object

Immutable state snapshot of an online change-point detection algorithm.

This class captures the internal state of an algorithm at a specific point in time. Being frozen and immutable ensures state consistency when used across different contexts or for debugging purposes.

Variables:

is_in_learning_period – Indicates whether the algorithm is currently in its initial learning phase where change-point detection may be disabled or adapted.

Parameters:

is_in_learning_period (bool)

is_in_learning_period: bool = False

__hash__()

Return a stable hash for algorithm state snapshots.

Return type:

int

__init__(*, is_in_learning_period=False)

Parameters:

is_in_learning_period (bool)

Return type:

None

class pysatl_cpd.core.online.ionline_algorithm.OnlineAlgorithmConfiguration(*, learning_period_size=0)

Bases: object

Configuration parameters for an online change-point detection algorithm.

This class holds static configuration settings that define the algorithm’s behavior. Being frozen ensures configuration immutability after creation.

Variables:

learning_period_size – Number of initial observations used for algorithm warm-up or parameter estimation before change-point detection begins.

Parameters:

learning_period_size (int)

learning_period_size: int = 0

__hash__()

Return a stable hash for algorithm configuration.

Return type:

int

__init__(*, learning_period_size=0)

Parameters:

learning_period_size (int)

Return type:

None

class pysatl_cpd.core.online.ionline_algorithm.OnlineAlgorithmDescription(*, name, configuration)

Bases: Generic

Immutable description of an online algorithm: public name and configuration. :ivar name: Human-readable algorithm name (often matches OnlineAlgorithm.name). :ivar configuration: Frozen configuration object for this algorithm.

Parameters:

• name (str)

• configuration (ConfigurationT)

name: str

configuration: ConfigurationT

__hash__()

Return a stable hash for the algorithm description.

Return type:

int

__init__(*, name, configuration)

Parameters:

• name (str)

• configuration (ConfigurationT)

Return type:

None

class pysatl_cpd.core.online.ionline_algorithm.OnlineAlgorithm

Bases: ABC, Generic

Abstract source class for online change-point detection algorithms.

Implementations process observations sequentially, updating internal state and producing a scalar change-point statistic after each observation. Algorithms must support state reset and provide configuration access.

Parameters:

• DataT (type) – Observation type accepted by the algorithm. For univariate data, this is typically a numeric scalar. For multivariate data, this is typically a one-dimensional array.

• ConfigurationT (OnlineAlgorithmConfiguration) – Configuration type that extends the source configuration.

• StateT (OnlineAlgorithmState) – State type that extends the source state.

property name: str

Human-readable name of the algorithm.

Returns:

Algorithm identifier suitable for logging and display.

Return type:

str

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.

property description: OnlineAlgorithmDescription

Return name and configuration as a single immutable description.

Returns:

Immutable description combining the algorithm name and its configuration parameters.

Return type:

OnlineAlgorithmDescription

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.

abstractmethod process(observation)

Process a single observation and return detection function value.

This method updates the algorithm’s internal state with the new observation and computes the current change-point detection statistic.

Parameters:

observation (TypeVar(DataT)) – New observation to incorporate into the algorithm’s state.

Returns:

Current value of the change-point statistic. Higher values indicate higher likelihood of a change-point occurrence.

Return type:

double | int | float

Raises:

NotImplementedError – Subclasses must implement this method.

abstractmethod reset()

Reset the algorithm to its initial state.

This method clears all accumulated state and returns the algorithm to the same condition as after initialization. Concrete implementations must provide this capability to enable proper solver behavior after change-point detections.

Return type:

None

abstractmethod recreate()

Recreate an algorithm instance

Returns:

A new algorithm instance

Return type:

OnlineAlgorithm[TypeVar(DataT), TypeVar(ConfigurationT, bound= OnlineAlgorithmConfiguration), TypeVar(StateT, bound= OnlineAlgorithmState)]

Raises:

NotImplementedError – Subclasses must implement this method.

__repr__()

Return a string representation of the algorithm.

Returns:

String combining algorithm name and its configuration.

Return type:

str