Online Detectors

Streaming change-point detectors that process one observation at a time.

Bocpd

Bayesian Online Changepoint Detection.

Constructor

cpd.Bocpd(
    model: str = "gaussian_nig",
    hazard: float | dict[str, Any] | None = None,
    max_run_length: int = 2000,
    alert_policy: dict[str, Any] | None = None,
    late_data_policy: str | dict[str, Any] | None = None,
)

Parameter	Type	Default	Description
model	str	"gaussian_nig"	Conjugate observation model family
hazard	float | dict | None	None	Constant hazard rate (1/expected_run_length) or custom config
max_run_length	int	2000	Truncation limit for the run-length posterior
alert_policy	dict | None	None	Alert firing rules (see below)
late_data_policy	str | dict | None	None	Late-data handling strategy

Alert policy shape:

{
    "threshold": 0.35,       # p_change must exceed this to fire
    "cooldown": 5,           # minimum steps between consecutive alerts
    "min_run_length": 10,    # suppress alerts during initial transient
}

Methods

update(x_t, t_ns=None) -> OnlineStepResult

Process a single scalar observation.

• x_t: float – Observation value

• t_ns: int | None – Optional nanosecond timestamp

• Returns: OnlineStepResult

update_many(x_batch) -> list[OnlineStepResult]

Process a batch of observations. Uses GIL-release optimization for batches >= 16 elements.

• x_batch: array-like of float64

• Returns: List of OnlineStepResult

reset() -> None

Clear internal state and start fresh.

save_state(*, format="bytes", path=None) -> bytes | dict | None

Checkpoint the detector state.

• format: str – "bytes" (compact binary) or "dict" (Python dict)

• path: str | Path | None – If provided, writes state to this file path and returns None

• Returns: State in the requested format, or None if path is provided

load_state(state=None, *, format=None, path=None) -> None

Restore detector state from a checkpoint.

• state: bytes | dict | _BocpdState | None – State object to load

• format: str | None – Required when loading from state bytes/dict

• path: str | Path | None – Load from file instead of state parameter

---

Cusum

Cumulative Sum detector for mean-shift monitoring.

Constructor

cpd.Cusum(
    drift: float = 0.0,
    threshold: float = 8.0,
    target_mean: float = 0.0,
    alert_policy: dict[str, Any] | None = None,
    late_data_policy: str | dict[str, Any] | None = None,
)

Parameter	Type	Default	Description
drift	float	0.0	Allowance parameter (slack before accumulation)
threshold	float	8.0	Decision threshold for cumulative sum
target_mean	float	0.0	Expected mean under null hypothesis
alert_policy	dict | None	None	Alert policy (same shape as BOCPD)
late_data_policy	str | dict | None	None	Late-data handling

Methods

Same interface as Bocpd: update(), update_many(), reset(), save_state(), load_state().

---

PageHinkley

Page-Hinkley drift/change monitor.

Constructor

cpd.PageHinkley(
    delta: float = 0.01,
    threshold: float = 8.0,
    initial_mean: float = 0.0,
    alert_policy: dict[str, Any] | None = None,
    late_data_policy: str | dict[str, Any] | None = None,
)

Parameter	Type	Default	Description
delta	float	0.01	Magnitude tolerance parameter
threshold	float	8.0	Decision threshold
initial_mean	float	0.0	Initial mean estimate
alert_policy	dict | None	None	Alert policy (same shape as BOCPD)
late_data_policy	str | dict | None	None	Late-data handling

Methods

Same interface as Bocpd: update(), update_many(), reset(), save_state(), load_state().