Online likelihoods¶

Online likelihood functions for Bayesian changepoint detection.

This module provides likelihood functions for online (sequential) changepoint detection using PyTorch for efficient computation and GPU acceleration.

`BaseLikelihood` ¶

Bases: ABC

Abstract base class for online likelihood functions.

This class provides a template for implementing likelihood functions for online Bayesian changepoint detection. Subclasses must implement the pdf and update_theta methods.

Parameters:

Name	Type	Description	Default
`device`	`str, torch.device, or None`	Device to place tensors on (CPU or GPU).	`None`

`prune(n)` ¶

Keep the posterior parameters of run lengths 0 .. n-1 only.

Used by OnlineChangepointDetector(max_run_length=...) to bound memory on an unbounded stream: after pruning, pdf returns n densities.

Raises:

Type	Description
`NotImplementedError`	If the subclass does not declare `_run_length_state`.

`to(device)` ¶

Move the likelihood model (and all its tensor state) to a device.

Returns self, mirroring torch.nn.Module.to.

`pdf(data)` `abstractmethod` ¶

Compute the probability density function for the observed data.

Parameters:

Name	Type	Description	Default
`data`	`Tensor`	The data point to evaluate (shape: [1] for univariate, [D] for multivariate).	required

Returns:

Type	Description
`Tensor`	Log probability densities for all run lengths.

`update_theta(data, **kwargs)` `abstractmethod` ¶

Update the posterior parameters given new data.

Parameters:

Name	Type	Description	Default
`data`	`Tensor`	The new data point to incorporate.	required
`**kwargs`		Additional arguments (e.g., timestep t).	`{}`

`StudentT` ¶

Bases: BaseLikelihood

Univariate Student's t-distribution likelihood for online changepoint detection.

Uses a Normal-Gamma conjugate prior, resulting in a Student's t predictive distribution. This is suitable for univariate data with unknown mean and variance.

Parameters:

Name	Type	Description	Default
`alpha`	`float`	Shape parameter of the Gamma prior on precision (default: 0.1).	`0.1`
`beta`	`float`	Rate parameter of the Gamma prior on precision (default: 0.1).	`0.1`
`kappa`	`float`	Precision parameter of the Normal prior on mean (default: 1.0).	`1.0`
`mu`	`float`	Mean parameter of the Normal prior on mean (default: 0.0).	`0.0`
`device`	`str, torch.device, or None`	Device to place tensors on.	`None`

Examples:

>>> import torch
>>> likelihood = StudentT(alpha=0.1, beta=0.01, kappa=1, mu=0)
>>> data = torch.tensor(1.5)
>>> log_probs = likelihood.pdf(data)
>>> likelihood.update_theta(data)

Notes

The Student's t-distribution arises naturally as the predictive distribution when using Normal-Gamma conjugate priors for Gaussian data with unknown mean and variance.

`mu` `property` ¶

Posterior mean for every run length (float32, for inspection).

`pdf(data)` ¶

Compute log probability density under Student's t-distribution.

Parameters:

Name	Type	Description	Default
`data`	`Tensor`	Scalar data point to evaluate.	required

Returns:

Type	Description
`Tensor`	Log probability densities for all current run lengths.

`update_theta(data, **kwargs)` ¶

Update posterior parameters using conjugate prior updates.

Parameters:

Name	Type	Description	Default
`data`	`Tensor`	New data point to incorporate.	required

`MultivariateT` ¶

Bases: BaseLikelihood

Multivariate Student's t-distribution likelihood for online changepoint detection.

Uses a Normal-Wishart conjugate prior, resulting in a multivariate Student's t predictive distribution. Suitable for multivariate data with unknown mean and covariance.

Parameters:

Name	Type	Description	Default
`dims`	`int`	Dimensionality of the data.	required
`dof`	`int`	Initial degrees of freedom for Wishart prior (default: dims + 1).	`None`
`kappa`	`float`	Precision parameter for Normal prior on mean (default: 1.0).	`1.0`
`mu`	`Tensor or None`	Prior mean vector (default: zero vector).	`None`
`scale`	`Tensor or None`	Prior scale matrix `W` of the Wishart distribution on the precision (default: `I / dof`, which gives a prior mean precision of `I`, i.e. unit prior covariance). Note this is a precision-side quantity: the posterior predictive covariance is proportional to `W^{-1}`, so to encode a prior covariance `C` pass `scale = inv(C) / dof`.	`None`
`device`	`str, torch.device, or None`	Device to place tensors on.	`None`

Attributes:

Name	Type	Description
`scale_inv`	`Tensor`	The state actually maintained: `T = W^{-1}` for every run length, shape `[t, dims, dims]` (Murphy 2007, eq. 255). The update is the rank-one sum `T + kappa/(kappa+1) (x-mu)(x-mu)^T`; the predictive uses a Cholesky factor of `T`. No matrix is inverted per step.
`scale`	`Tensor`	`W = inv(scale_inv)` per run length, computed on access for compatibility; not used internally.

Notes

All state is float32. The predictive's lgamma terms lose accuracy as the degrees of freedom grow with the run length: about 1e-6 nats at nu = 100, 1e-3 at nu = 3000, 6e-3 at nu = 50000. Runs that long are rare in practice, but that is the accuracy ceiling.

Examples:

>>> import torch
>>> likelihood = MultivariateT(dims=3)
>>> data = torch.randn(3)
>>> log_probs = likelihood.pdf(data)
>>> likelihood.update_theta(data)

Notes

The multivariate Student's t-distribution generalizes the univariate case to multiple dimensions, naturally handling correlations between variables.

`mu` `property` ¶

Posterior mean for every run length, [t, dims] (float32).

`scale` `property` ¶

Wishart scale W per run length (inv(scale_inv)), for inspection.

`pdf(data)` ¶

Compute log probability density under multivariate Student's t-distribution.

Parameters:

Name	Type	Description	Default
`data`	`Tensor`	Data vector to evaluate (shape: [dims]).	required

Returns:

Type	Description
`Tensor`	Log probability densities for all current run lengths.

`update_theta(data, **kwargs)` ¶

Update posterior parameters using Normal-Wishart conjugate updates.

Parameters:

Name	Type	Description	Default
`data`	`Tensor`	New data vector to incorporate.	required

`Poisson` ¶

Bases: BaseLikelihood

Poisson likelihood with a conjugate Gamma prior, for online detection of changes in the rate of count data.

For each run length the rate has a Gamma(alpha, beta) posterior (shape, rate); the predictive of the next count is negative binomial:

p(x) = Gamma(alpha + x) / (Gamma(alpha) x!) (beta / (beta + 1))^alpha (1 / (beta + 1))^x,

and after observing x the posterior becomes Gamma(alpha + x, beta + 1) (Gelman et al., Bayesian Data Analysis, 3rd ed., section 2.6).

Parameters:

Name	Type	Description	Default
`alpha`	`float`	Prior shape (default 1.0).	`1.0`
`beta`	`float`	Prior rate (default 1.0). The prior mean rate is `alpha / beta`; a small `beta` makes the prior vague.	`1.0`
`device`	`str, torch.device, or None`	Device to place tensors on.	`None`

Raises:

Type	Description
`ValueError`	From `pdf` if an observation is not a single non-negative integer.

Examples:

>>> import torch
>>> likelihood = Poisson(alpha=1.0, beta=0.1)
>>> log_probs = likelihood.pdf(torch.tensor(3.0))
>>> likelihood.update_theta(torch.tensor(3.0))

`pdf(data)` ¶

Log negative-binomial predictive of one count for every run length.

Parameters:

Name	Type	Description	Default
`data`	`Tensor`	A single non-negative integer count.	required

Returns:

Type	Description
`Tensor`	Log predictive probabilities, one per current run length.

`update_theta(data, **kwargs)` ¶

Conjugate update alpha += x, beta += 1 for every run length, with the prior prepended for run length 0.

Parameters:

Name	Type	Description	Default
`data`	`Tensor`	The count just observed.	required

`NormalKnownVariance` ¶

Bases: BaseLikelihood

Normal likelihood with known variance and a conjugate Normal prior on the mean, for online detection of changes in the mean when the noise level is known.

For each run length the segment mean has a N(mu_r, v_r) posterior; the predictive of the next observation is N(mu_r, v_r + variance), and after observing x (Murphy, "Conjugate Bayesian analysis of the Gaussian distribution", 2007, section 2):

v' = 1 / (1 / v_r + 1 / variance), mu' = v' (mu_r / v_r + x / variance).

Parameters:

Name	Type	Description	Default
`variance`	`float`	The known observation variance (default 1.0).	`1.0`
`mu`	`float`	Prior mean of the segment mean (default 0.0).	`0.0`
`prior_variance`	`float`	Prior variance of the segment mean (default 1.0).	`1.0`
`device`	`str, torch.device, or None`	Device to place tensors on.	`None`

Examples:

>>> import torch
>>> likelihood = NormalKnownVariance(variance=0.25, prior_variance=100.0)
>>> log_probs = likelihood.pdf(torch.tensor(0.3))
>>> likelihood.update_theta(torch.tensor(0.3))

`mu` `property` ¶

Posterior mean for every run length (float32, for inspection).

`pdf(data)` ¶

Log Normal predictive of one observation for every run length.

Parameters:

Name	Type	Description	Default
`data`	`Tensor`	Scalar observation.	required

Returns:

Type	Description
`Tensor`	Log predictive densities, one per current run length.

`update_theta(data, **kwargs)` ¶

Conjugate update of the mean's posterior for every run length, with the prior prepended for run length 0.

Parameters:

Name	Type	Description	Default
`data`	`Tensor`	The observation just seen.	required

Online likelihoods¶

BaseLikelihood ¶

prune(n) ¶

to(device) ¶

pdf(data) abstractmethod ¶

update_theta(data, **kwargs) abstractmethod ¶

StudentT ¶

mu property ¶

pdf(data) ¶

update_theta(data, **kwargs) ¶

MultivariateT ¶

mu property ¶

scale property ¶

pdf(data) ¶

update_theta(data, **kwargs) ¶

Poisson ¶

pdf(data) ¶

update_theta(data, **kwargs) ¶

NormalKnownVariance ¶

mu property ¶

pdf(data) ¶

update_theta(data, **kwargs) ¶

`BaseLikelihood` ¶

`prune(n)` ¶

`to(device)` ¶

`pdf(data)` `abstractmethod` ¶

`update_theta(data, **kwargs)` `abstractmethod` ¶

`StudentT` ¶

`mu` `property` ¶

`pdf(data)` ¶

`update_theta(data, **kwargs)` ¶

`MultivariateT` ¶

`mu` `property` ¶

`scale` `property` ¶

`pdf(data)` ¶

`update_theta(data, **kwargs)` ¶

`Poisson` ¶

`pdf(data)` ¶

`update_theta(data, **kwargs)` ¶

`NormalKnownVariance` ¶

`mu` `property` ¶

`pdf(data)` ¶

`update_theta(data, **kwargs)` ¶