Multivariate Distributions

AdditionalDistributions.jl provides multivariate Gaussian and Student-t distributions with support for rectangular cumulative probabilities.

A rectangular CDF is a probability of the form

The package currently focuses on:

• MvGaussian, based on Distributions.MvNormal;

• MvTStudent, based on Distributions.MvTDist.

AdditionalDistributions.MvGaussian Type

MvGaussian(μ::AbstractVector, Σ::AbstractMatrix)

A Multivariate Gaussian (Normal) distribution equivalent in behavior to Distributions.MvNormal, but using a custom folded batch randomized quasi-Monte Carlo integrator for the cumulative distribution function (cdf).

This type preserves all the standard functionality of MvNormal — including pdf, logpdf, rand, mean, and cov — while providing its own implementation of cdf(a, b) for rectangular probabilities under a multivariate normal law.

MvGaussian(Σ)        # zero-mean version
MvGaussian(μ, Σ)     # with explicit mean and covariance
params(d)            # returns (μ, Σ)
cdf(d, a, b)         # evaluates P(a ≤ X ≤ b)

External link:

• Multivariate normal distribution - Wikipedia

source

AdditionalDistributions.MvTStudent Type

MvTStudent(ν::Real, μ::AbstractVector, Σ::AbstractMatrix)

A Multivariate Student's t distribution equivalent in behavior to Distributions.MvTDist, but using a custom pure-Julia Genz-Bretz/Richtmyer randomized QMC integrator for rectangular cumulative distribution functions.

This type preserves the standard functionality of MvTDist — including pdf, logpdf, rand, mean, and cov — while providing its own implementation of cdf(a, b) for rectangular probabilities under a multivariate t law.

MvTStudent(ν, Σ)             # zero-location version with df=ν
MvTStudent(ν, μ, Σ)          # with degrees of freedom ν, location μ, and scale Σ

params(d)                    # returns (ν, μ, Σ)
cdf(d, a, b)                 # evaluates P(a ≤ X ≤ b)
cdf_result(d, a, b)          # returns value, error, inform and algorithm metadata

source

AdditionalDistributions.CDFResult Type

CDFResult(value, error, inform, neval, algorithm)

Structured result returned by cdf_result for multivariate rectangular probabilities.

Fields

• value: estimated probability.

• error: estimated absolute integration error.

• inform: convergence/status code.

• neval: requested integration budget.

• algorithm: integration algorithm identifier.

inform codes

• 0: estimated error is within tolerance.

• 1: estimated error is above tolerance for the current budget.

• 2: invalid dimension.

• 3: matrix appears not positive semidefinite during preparation.

CDFResult can be destructured as (value, error, inform) for compatibility with the legacy full=true tuple output.

source

AdditionalDistributions.cdf_result Function

cdf_result(d::MvGaussian, a, b; m=1000*length(a), abseps=1e-6,
           releps=1e-6, pivot=true, rng=Random.default_rng(),
           antithetic=false, batchsize=0, nshifts=12)

Estimate the rectangular probability P(a ≤ X ≤ b) for a multivariate Gaussian distribution and return a CDFResult.

The Gaussian path uses MVSORT reordering, a Genz-style conditional transformation, folded randomized Richtmyer QMC points, and batch evaluation. If the covariance matrix is diagonal, the probability is evaluated exactly by factorization.

Use cdf(d, a, b) for the scalar probability, or cdf(d, a, b; full=true) for the legacy (value, error, inform) tuple.

source

cdf_result(d::MvTStudent, a, b; m=max(100_000, 10_000*length(a)),
           abseps=1e-6, releps=1e-6, pivot=true,
           rng=Random.default_rng(), antithetic=false,
           batchsize=0, nshifts=16)

Estimate the rectangular probability P(a ≤ X ≤ b) for a multivariate Student's t distribution and return a CDFResult.

The Student's t path uses the scale-mixture representation of the t law with an additional chi-square coordinate, combined with the same conditional Gaussian transformation used by MvGaussian. The Gaussian coordinates are folded; the chi-square coordinate is not folded.

Small degrees of freedom, high dimensions, strong correlations, or tail rectangles may require a larger m.

source

AdditionalDistributions.mvtcdf Function

mvtcdf(Σ, a, b; ν=0, δ=zeros, maxpts=1000n, abseps=1e-6,
       releps=1e-6, assume_correlation=false, pivot=true,
       antithetic=false, rng=Random.default_rng(), batchsize=0,
       nshifts=nothing)

Rectangular probability for multivariate Gaussian (ν <= 0) and multivariate Student t (ν > 0) distributions using MVSORT plus randomized Richtmyer quasi-Monte Carlo.

When nshifts is not specified, the core uses 12 randomized shifts for the Gaussian case and 16 randomized shifts for the Student t case.

Returns a named tuple (value, error, inform).

inform codes:

• 0: requested tolerance reached according to the internal error estimate.

• 1: tolerance not reached with maxpts.

• 2: invalid dimension.

• 3: covariance/correlation matrix appears non positive semidefinite.

source

Basic usage

Gaussian rectangular probabilities

using AdditionalDistributions
using LinearAlgebra
using Random

d = 5
Σ = fill(0.5, d, d)
Σ[diagind(Σ)] .= 1.0

mvnormal = MvGaussian(zeros(d), Σ)
lower = fill(-1.0, d)
upper = fill(1.0, d)

res = cdf_result(mvnormal, lower, upper;
    m = 100_000,
    rng = MersenneTwister(1234),
)

res.value
res.error
res.inform

cdf(mvnormal, lower, upper) returns only the probability estimate. Use cdf_result for diagnostics.

Student-t rectangular probabilities

ν = 4.0
mvt = MvTStudent(ν, zeros(d), Σ)

res = cdf_result(mvt, lower, upper;
    m = 1_000_000,
    abseps = 1e-8,
    releps = 1e-8,
    nshifts = 16,
    rng = MersenneTwister(1234),
)

The Student-t CDF is usually harder than the Gaussian CDF because it uses the normal-scale-mixture representation and an additional chi-square coordinate. Small degrees of freedom, high dimension, strong dependence, and tail rectangles may require larger m.

API summary

cdf(dist, lower, upper; kwargs...)

returns only the probability estimate.

cdf_result(dist, lower, upper; kwargs...)

returns a structured result:

res.value
res.error
res.inform
res.neval
res.algorithm

Keywords

Keyword	Meaning
m	Integration budget.
abseps	Absolute error tolerance.
releps	Relative error tolerance.
rng	Random number generator for randomized shifts.
nshifts	Number of randomized QMC shifts. Defaults: 12 for Gaussian, 16 for Student-t.
batchsize	Internal batch size. Automatic settings are usually appropriate.
pivot	Enable or disable MVSORT reordering.
antithetic	Optional antithetic reflection when available.

Typical advanced usage:

res = cdf_result(mvt, lower, upper;
    m = 1_000_000,
    abseps = 1e-8,
    releps = 1e-8,
    nshifts = 16,
    rng = MersenneTwister(1234),
)

inform codes

Code	Meaning
0	Estimated error reached the requested tolerance.
1	Estimated error is above tolerance for the current budget.
2	Invalid dimension or integration setup.
3	Matrix appears not positive semidefinite.

inform = 1 is common for difficult high-dimensional or heavy-tailed cases. It means the estimated integration error did not reach the requested tolerance with the current budget. Increase m, adjust tolerances, or compare against an external reference if the result seems suspicious.

Algorithm summary

Gaussian path

The Gaussian rectangular CDF uses:

1. MVSORT variable reordering;

2. Genz-style conditional transformation;

3. folded randomized Richtmyer quasi-Monte Carlo points;

4. batched evaluation to reduce per-point overhead.

Diagonal Gaussian covariance/correlation matrices are handled by an exact product shortcut.

The default number of randomized shifts is:

nshifts = 12

Student-t path

The Student-t implementation uses the scale-mixture representation. If

then

has a multivariate Student-t distribution.

The algorithm uses the same conditional Gaussian core together with one radial chi-square coordinate. The Gaussian coordinates are folded; the chi-square radial coordinate is not folded.

The default settings for MvTStudent are more conservative:

m = max(100_000, 10_000*d)
nshifts = 16

Important: a diagonal Student-t scale matrix does not imply independent components. The components share a common radial scale, so diagonal Student-t rectangular probabilities are not computed as products of univariate Student-t probabilities.

Reproducibility

Randomized QMC methods depend on random shifts. Use a fixed RNG to obtain reproducible output:

rng = MersenneTwister(1234)
res = cdf_result(mvnormal, lower, upper; rng=rng)

When comparing with another implementation, always report:

• m;

• nshifts;

• abseps;

• releps;

• random seed;

• full CDFResult;

• distribution parameters;

• lower and upper bounds.

Reference comparisons

Gaussian reference tests include Genz-style cases and comparisons with MvNormalCDF.jl.

Student-t reference checks can be performed with R's mvtnorm::pmvt using GenzBretz.

See Benchmarks and Accuracy and Reproducibility for more details.