Priors

Prior probability distributions for Bayesian changepoint detection.

This module provides various prior distributions for modeling the probability of changepoints in time series data.

const_prior(t, p=0.25, device=None)

Constant prior on segment length.

Returns log(p) for every length. This is not a probability mass function on its own; it is the conventional choice of the original library, used as partial(const_prior, p=1 / (n + 1)) for a series of n observations. offline_changepoint_detection needs the prior mass on lengths 1 .. n - 1 to stay below 1, i.e. p * (n - 1) < 1, and raises otherwise.

Parameters:

Name	Type	Description	Default
t	int or Tensor	Time index or tensor of time indices.	required
p	float	Constant probability value (default: 0.25). Must be between 0 and 1.	0.25
device	str, torch.device, or None	Device to place the output tensor on.	None

Returns:

Type	Description
float or Tensor	Log probability value(s).

Examples:

>>> # Single time point
>>> log_prob = const_prior(5, p=0.1)
>>> print(log_prob)  # log(0.1)

>>> # Multiple time points
>>> t = torch.arange(10)
>>> log_probs = const_prior(t, p=0.2)
>>> print(log_probs.shape)  # torch.Size([10])

Notes

Under this prior every segmentation with the same number of changepoints has the same prior probability, regardless of where the changepoints fall.

geometric_prior(t, p=0.25, device=None)

Geometric prior on segment length.

P(length = t) = (1 - p)^(t - 1) p for t >= 1: the number of trials up to and including the first success when each observation ends the segment with probability p. The mean segment length is 1 / p. Lengths t <= 0 are impossible and get log probability -inf.

Parameters:

Name	Type	Description	Default
t	int or Tensor	Segment length(s).	required
p	float	Probability that a segment ends at each observation (default: 0.25). Must be in (0, 1].	0.25
device	str, torch.device, or None	Device to place the output tensor on.	None

Returns:

Type	Description
float or Tensor	Log probability value(s).

Examples:

>>> import math
>>> math.isclose(geometric_prior(1, p=0.1), math.log(0.1), rel_tol=1e-6)
True
>>> math.isclose(geometric_prior(3, p=0.1), math.log(0.9 * 0.9 * 0.1), rel_tol=1e-6)
True
>>> geometric_prior(torch.arange(1, 11), p=0.2).shape
torch.Size([10])

Notes

torch.distributions.Geometric counts failures before the first success (support 0, 1, 2, ...), so it is evaluated at t - 1. The pre-PyTorch versions of this library used the same (1 - p)^(t - 1) p form.

negative_binomial_prior(t, k=1, p=0.25, device=None)

Negative binomial prior on segment length.

P(length = t) = C(t - 1, k - 1) p^k (1 - p)^(t - k) for t >= k: the number of trials needed to obtain k successes when each trial succeeds with probability p. The mean segment length is k / p. Lengths t < k are impossible and get log probability -inf. With k = 1 this is exactly geometric_prior.

Parameters:

Name	Type	Description	Default
t	int or Tensor	Segment length(s).	required
k	int	Number of successes required (default: 1). Must be positive.	1
p	float	Success probability of each trial (default: 0.25). Must be in (0, 1].	0.25
device	str, torch.device, or None	Device to place the output tensor on.	None

Returns:

Type	Description
float or Tensor	Log probability value(s).

Examples:

>>> import math
>>> math.isclose(negative_binomial_prior(3, k=2, p=0.5), math.log(2 * 0.25 * 0.5), rel_tol=1e-6)
True
>>> negative_binomial_prior(1, k=2, p=0.5)
-inf
>>> negative_binomial_prior(torch.arange(1, 11), k=3, p=0.2).shape
torch.Size([10])

Notes

Computed in closed form with lgamma rather than through torch.distributions.NegativeBinomial, whose probs is the probability of the counted outcome (the complement of p here); versions 1.0.x used that class with probs=p and therefore had p and 1 - p swapped. Equivalent to scipy.stats.nbinom(k, p).pmf(t - k).