Hazard functions

Hazard functions for Bayesian changepoint detection.

Hazard functions specify the prior probability of a changepoint occurring at each time step, given the run length (time since last changepoint).

constant_hazard(lam, r, device=None)

Constant hazard function for Bayesian online changepoint detection.

This function returns a constant probability (1/lam) for a changepoint occurring at any time step, regardless of the current run length.

Parameters:

Name	Type	Description	Default
lam	float	The expected run length (higher values = lower changepoint probability). Must be at least 1, because the hazard 1 / lam is a probability. lam = 1 puts a changepoint before every observation; inf gives hazard 0 (no changepoints).	required
r	Tensor or int	Run length tensor or shape specification. If int, creates a tensor of that size filled with the constant hazard value.	required
device	str, torch.device, or None	Device to place the output tensor on.	None

Returns:

Type	Description
Tensor	Tensor of hazard probabilities with the same shape as r.

Raises:

Type	Description
ValueError	If lam is below 1 or NaN.

Examples:

>>> import torch
>>> # Create hazard for run lengths 0 to 9
>>> hazard = constant_hazard(10.0, 10)
>>> print(hazard)  # All values will be 0.1

>>> # Use with existing run length tensor
>>> r = torch.arange(5)
>>> hazard = constant_hazard(20.0, r)
>>> print(hazard)  # All values will be 0.05

Notes

The constant hazard function assumes that the probability of a changepoint is independent of how long the current segment has been running. This is a common choice for modeling changepoints in stationary processes.

negative_binomial_hazard(k, p, r, device=None)

Hazard of a negative binomial segment-length distribution.

The online counterpart of priors.negative_binomial_prior(t, k, p): segment lengths follow P(length = t) = C(t - 1, k - 1) p^k (1 - p)^(t - k) for t >= k (mean k / p), and the hazard at run length r is the probability that a segment holding r observations ends with the next one, i.e. has length r + 1, H(r) = P(length = r + 1) / P(length >= r + 1) (Adams & MacKay 2007, section 2.1). With k = 1 the lengths are geometric and the hazard is the constant p, i.e. constant_hazard(1 / p, r). With k > 1 short segments are unlikely: H(r) = 0 for r + 1 < k, and the hazard rises towards p as the run grows.

Parameters:

Name	Type	Description	Default
k	int	Number of successes (shape); must be at least 1.	required
p	float	Success probability, in (0, 1].	required
r	Tensor or int	Run lengths (non-negative integers), or an int n for run lengths 0 .. n - 1.	required
device	str, torch.device, or None	Device for the output; defaults to the device of r.	None

Returns:

Type	Description
Tensor	Hazard probabilities, float32, same shape as r.

Raises:

Type	Description
ValueError	If k < 1, p is outside (0, 1], or a run length is negative.

Examples:

>>> from functools import partial
>>> hazard = partial(negative_binomial_hazard, 3, 0.02)  # mean length 150
>>> R, _ = online_changepoint_detection(data, hazard, StudentT())