`multivariate_distributions`

This library provides sampling, density, and log-density predicates for multivariate normal and Student’s t distributions, Mahalanobis distance predicates, additive-log-ratio logistic-normal sampling predicates, Dirichlet sampling, density, and log-density predicates, and multinomial sampling, probability mass, and log-probability mass predicates. Batch predicates return samples as lists of row vectors.

API documentation

Open the ../../apis/library_index.html#multivariate-distributions link in a web browser.

Loading

To load all entities in this library, load the loader.lgt file:

| ?- logtalk_load(multivariate_distributions(loader)).

Testing

To test this library predicates, load the tester.lgt file:

| ?- logtalk_load(multivariate_distributions(tester)).

Scope

The multivariate_distributions(Random) parametric object accepts a random source implementing the sampling_protocol protocol. Common choices are random(xoshiro128pp) and fast_random(xoshiro128pp).

Covariance and scale matrices may be singular positive-semidefinite matrices. The predicates use eigendecomposition to operate on their affine support and do not add diagonal jitter. Density predicates return 0.0 outside singular support and log-density predicates return negative_infinity. Mahalanobis distance predicates throw an error for points outside support.

For the multivariate Student’s t distribution, the matrix argument is a scale matrix. When the degrees of freedom are greater than two, the covariance is the scale matrix multiplied by DegreesOfFreedom / (DegreesOfFreedom - 2).

The logistic-normal predicates use the additive log-ratio representation. A latent vector of length d maps to a simplex vector of length d+1, with the last simplex component used as the fixed reference component.

Dirichlet densities support simplex boundary points. Depending on the alpha parameters, boundary density and log-density values may be represented by the atoms positive_infinity and negative_infinity. When zero components have both alphas smaller than one and alphas greater than one, the boundary limit is path-dependent and both predicates return undefined.

Multinomial probability lists must be nonempty and sum to one within a tolerance of 1.0e-12. Multinomial quantiles order count vectors by decreasing probability mass and use increasing lexicographic order to break log-probability ties within a relative tolerance of 1.0e-12.

Multinomial sampling performs one linear category selection and one count-vector update per trial, requiring time proportional to the product of the trial and category counts. Multinomial quantiles enumerate and sort the complete count-vector state space. For Trials trials and Categories categories, this space contains binomial(Trials + Categories - 1, Categories - 1) vectors; the implementation therefore requires combinatorial time and memory and rejects queries exceeding 100000 vectors. Inputs near that limit can still require substantial runtime and memory.

Normal, Student’s t, and logistic-normal sampling requires an eigendecomposition of the covariance or scale matrix. Batch sampling predicates factorize the matrix once and should be preferred when generating multiple samples.

Examples

Generate one multivariate normal sample using a portable pseudo-random source:

| ?- multivariate_distributions(random(xoshiro128pp))::multivariate_normal(
         [0.0, 0.0], [[1.0, 0.5], [0.5, 1.0]], Sample
     ).

Generate a batch of five samples, factorizing the covariance matrix only once:

| ?- multivariate_distributions(random(xoshiro128pp))::multivariate_normal_samples(
         5, [0.0, 0.0], [[1.0, 0.5], [0.5, 1.0]], Samples
     ).

Compute a density and a Mahalanobis distance (these predicates do not consume random values):

| ?- multivariate_distributions(random(xoshiro128pp))::multivariate_normal_density(
         [1.0, 0.0], [0.0, 0.0], [[1.0, 0.0], [0.0, 1.0]], Density
     ).
Density = 0.09653235263005393.

| ?- multivariate_distributions(random(xoshiro128pp))::mahalanobis_distance(
         [2.0, 0.0], [0.0, 0.0], [[4.0, 0.0], [0.0, 1.0]], Distance
     ).
Distance = 1.0.

For a singular covariance matrix, density is evaluated on its affine support and is zero outside it:

| ?- multivariate_distributions(random(xoshiro128pp))::multivariate_normal_density(
         [1.0, 1.0], [0.0, 0.0], [[1.0, 0.0], [0.0, 0.0]], Density
     ).
Density = 0.0.

Generate a multivariate Student’s t sample with five degrees of freedom:

| ?- multivariate_distributions(random(xoshiro128pp))::multivariate_t(
         5.0, [0.0, 0.0], [[1.0, 0.0], [0.0, 1.0]], Sample
     ).

Generate a logistic-normal probability vector. A two-dimensional latent normal distribution produces three simplex components:

| ?- multivariate_distributions(random(xoshiro128pp))::logistic_normal(
         [0.0, 0.0], [[1.0, 0.0], [0.0, 1.0]], Probabilities
     ).

multivariate_distributions