Multivariate distributions
Vectors are LIST(DOUBLE); matrices (covariance, scale) are LIST(DOUBLE) in row-major
flattened form. A 2x2 identity matrix is written [1.0, 0.0, 0.0, 1.0].
sr_multivariate_normal_pdf(x, mean, covariance)
Signature: sr_multivariate_normal_pdf(x DOUBLE[], mean DOUBLE[], covariance DOUBLE[]) -> DOUBLE
Probability density of x under a multivariate normal distribution with the given mean vector
and covariance matrix.
The size of covariance must equal len(mean)². A mismatch is a query error (statrs' internal
panic is caught at the SQL boundary).
SELECT sr_multivariate_normal_pdf([0.0, 0.0], [0.0, 0.0], [1.0, 0.0, 0.0, 1.0])
-- 0.15915494309189535
The value is 1 / (2π) — the density of a standard bivariate normal at the origin.
sr_multivariate_normal_ln_pdf(x, mean, cov)
Signature: sr_multivariate_normal_ln_pdf(x DOUBLE[], mean DOUBLE[], covariance DOUBLE[]) -> DOUBLE
Log probability density of x — equivalent to ln(sr_multivariate_normal_pdf(...)) but computed
without the intermediate exponential, so it stays finite far into the tails where the density
underflows to 0.
SELECT sr_multivariate_normal_ln_pdf([1.0, 1.0], [0.0, 0.0], [1.0, 0.0, 0.0, 1.0])
-- -2.8378770664093453
sr_multivariate_normal_min(mean, cov)
Signature: sr_multivariate_normal_min(mean DOUBLE[], cov DOUBLE[]) -> DOUBLE[]
Lower bound of the support: a vector of -inf with the dimension of the mean.
SELECT sr_multivariate_normal_min([0.0, 0.0], [1.0, 0.0, 0.0, 1.0])
-- [-inf, -inf]
sr_multivariate_normal_max(mean, cov)
Signature: sr_multivariate_normal_max(mean DOUBLE[], cov DOUBLE[]) -> DOUBLE[]
Upper bound of the support: a vector of +inf with the dimension of the mean.
SELECT sr_multivariate_normal_max([0.0, 0.0], [1.0, 0.0, 0.0, 1.0])
-- [inf, inf]
sr_multivariate_normal_entropy(mean, cov)
Signature: sr_multivariate_normal_entropy(mean DOUBLE[], cov DOUBLE[]) -> DOUBLE
Differential entropy of the multivariate normal distribution given the mean and a row-major flattened covariance matrix.
SELECT sr_multivariate_normal_entropy([0.0, 0.0], [1.0, 0.0, 0.0, 1.0])
-- 2.8378770664093453
sr_multivariate_normal_mean(mean, cov)
Signature: sr_multivariate_normal_mean(mean DOUBLE[], cov DOUBLE[]) -> DOUBLE[]
Mean vector of the multivariate normal distribution given the mean and a row-major flattened covariance matrix.
SELECT sr_multivariate_normal_mean([0.0, 0.0], [1.0, 0.0, 0.0, 1.0])
-- [0.0, 0.0]
sr_multivariate_normal_mode(mean, cov)
Signature: sr_multivariate_normal_mode(mean DOUBLE[], cov DOUBLE[]) -> DOUBLE[]
Mode vector of the multivariate normal distribution given the mean and a row-major flattened covariance matrix.
SELECT sr_multivariate_normal_mode([0.0, 0.0], [1.0, 0.0, 0.0, 1.0])
-- [0.0, 0.0]
sr_multivariate_normal_variance(mean, cov)
Signature: sr_multivariate_normal_variance(mean DOUBLE[], cov DOUBLE[]) -> DOUBLE[]
Covariance matrix of the multivariate normal distribution (row-major flattened LIST) given the mean and a row-major flattened covariance matrix.
SELECT sr_multivariate_normal_variance([0.0, 0.0], [1.0, 0.0, 0.0, 1.0])
-- [1.0, 0.0, 0.0, 1.0]
sr_multivariate_normal_precision(mean, cov)
Signature: sr_multivariate_normal_precision(mean DOUBLE[], cov DOUBLE[]) -> DOUBLE[]
The precision matrix Σ⁻¹ — the inverse of the covariance matrix, row-major flattened.
Unlike variance, which returns the covariance you passed in, this returns a matrix statrs
actually computes (from the Cholesky factorisation at construction time) — it is the Σ⁻¹ in
the density's exponent term -(1/2)·(x-μ)ᵀ·Σ⁻¹·(x-μ). DuckDB has no matrix inverse, so there
is no way to derive it on the SQL side.
SELECT sr_multivariate_normal_precision([0.0, 0.0], [1.0, 0.0, 0.0, 1.0])
-- [1.0, 0.0, 0.0, 1.0]
For the identity covariance the inverse is the identity again. A diagonal case shows the
inversion directly: diag(2, 4)⁻¹ = diag(1/2, 1/4) — 1/2 prints as 0.49999999999999994
in binary floating point.
SELECT sr_multivariate_normal_precision([0.0, 0.0], [2.0, 0.0, 0.0, 4.0])
-- [0.49999999999999994, 0.0, 0.0, 0.25]
sr_multivariate_students_t_pdf(x, location, scale, freedom)
Signature: sr_multivariate_students_t_pdf(x DOUBLE[], location DOUBLE[], scale DOUBLE[], freedom DOUBLE) -> DOUBLE
Density under a multivariate Student's t distribution. At location = 0, scale = I and
symmetric x = 0, the density matches the multivariate normal at the origin.
SELECT sr_multivariate_students_t_pdf([0.0, 0.0], [0.0, 0.0], [1.0, 0.0, 0.0, 1.0], 3.0)
-- 0.1591549430918955
sr_multivariate_students_t_ln_pdf(x, location, scale, freedom)
Signature: sr_multivariate_students_t_ln_pdf(x DOUBLE[], location DOUBLE[], scale DOUBLE[], freedom DOUBLE) -> DOUBLE
Log probability density under a multivariate Student's t distribution. As freedom grows the
values converge to the multivariate normal's ln_pdf.
SELECT sr_multivariate_students_t_ln_pdf([1.0, 1.0], [0.0, 0.0], [1.0, 0.0, 0.0, 1.0], 4.0)
-- -3.0542723907338383
sr_multivariate_students_t_mean(location, scale, freedom)
Signature: sr_multivariate_students_t_mean(location DOUBLE[], scale DOUBLE[], freedom DOUBLE) -> DOUBLE[]
Mean vector of the multivariate Student's t distribution (equal to location). Only defined for
freedom > 1; otherwise the result is NULL.
SELECT sr_multivariate_students_t_mean([-1.0, 1.0, 3.0], [1.0, 0.0, 0.5, 0.0, 2.0, 0.0, 0.5, 0.0, 3.0], 2.0)
-- [-1.0, 1.0, 3.0]
sr_multivariate_students_t_variance(location, scale, freedom)
Signature: sr_multivariate_students_t_variance(location DOUBLE[], scale DOUBLE[], freedom DOUBLE) -> DOUBLE[]
Covariance matrix scale · ν / (ν − 2) as a row-major flattened LIST. Only defined for
freedom > 2; otherwise the result is NULL.
SELECT sr_multivariate_students_t_variance([0.0, 0.0], [1.0, 0.0, 0.0, 1.0], 3.0)
-- [3.0, 0.0, 0.0, 3.0]
sr_multivariate_students_t_precision(location, scale, freedom)
Signature: sr_multivariate_students_t_precision(location DOUBLE[], scale DOUBLE[], freedom DOUBLE) -> DOUBLE[]
The precision matrix scale⁻¹ — the inverse of the scale matrix, row-major flattened.
Do not confuse it with variance: that one is scale · ν / (ν − 2) (a genuine covariance that
scales with the degrees of freedom), this one is exactly scale⁻¹ and does not depend on
freedom at all — only scale matters. statrs computes it at construction time from the
Cholesky factorisation, and DuckDB has no matrix inverse, so it is not derivable on the SQL side.
SELECT sr_multivariate_students_t_precision([0.0, 0.0], [1.0, 0.0, 0.0, 1.0], 3.0)
-- [1.0, 0.0, 0.0, 1.0]
SELECT sr_multivariate_students_t_precision([0.0, 0.0], [2.0, 0.0, 0.0, 4.0], 3.0)
-- [0.49999999999999994, 0.0, 0.0, 0.25]
sr_multivariate_students_t_min(location, scale, freedom)
Signature: sr_multivariate_students_t_min(location DOUBLE[], scale DOUBLE[], freedom DOUBLE) -> DOUBLE[]
Lower bound of the support: a vector of -inf with the dimension of location.
SELECT sr_multivariate_students_t_min([0.0, 0.0], [1.0, 0.0, 0.0, 1.0], 3.0)
-- [-inf, -inf]
sr_multivariate_students_t_max(location, scale, freedom)
Signature: sr_multivariate_students_t_max(location DOUBLE[], scale DOUBLE[], freedom DOUBLE) -> DOUBLE[]
Upper bound of the support: a vector of +inf with the dimension of location.
SELECT sr_multivariate_students_t_max([0.0, 0.0], [1.0, 0.0, 0.0, 1.0], 3.0)
-- [inf, inf]
sr_multivariate_students_t_mode(location, scale, freedom)
Signature: sr_multivariate_students_t_mode(location DOUBLE[], scale DOUBLE[], freedom DOUBLE) -> DOUBLE[]
Mode vector of the multivariate Student's t distribution given location, a row-major flattened scale matrix and the degrees of freedom.
SELECT sr_multivariate_students_t_mode([0.0, 0.0], [1.0, 0.0, 0.0, 1.0], 3.0)
-- [0.0, 0.0]
sr_dirichlet_pdf(x, alpha)
Signature: sr_dirichlet_pdf(x DOUBLE[], alpha DOUBLE[]) -> DOUBLE
Density of x on the simplex under a Dirichlet distribution with concentration vector alpha.
x and alpha must have the same length.
SELECT sr_dirichlet_pdf([0.5, 0.5], [1.0, 1.0])
-- 1.0000000000000009
For alpha = (1, 1) the Dirichlet is uniform on the simplex, so the density is 1 everywhere
on {(x1, x2) : x1 + x2 = 1, xi >= 0}.
sr_dirichlet_ln_pdf(x, alpha)
Signature: sr_dirichlet_ln_pdf(x DOUBLE[], alpha DOUBLE[]) -> DOUBLE
Log density of x on the simplex. Every component of x must lie in (0, 1) and the components
must sum to 1 (within 1e-4) — violations are statrs assertion failures, which surface as query
errors.
SELECT sr_dirichlet_ln_pdf([0.1, 0.2, 0.3, 0.4], [0.1, 0.3, 0.5, 0.8])
-- -0.18456529434757482
sr_dirichlet_mean(alpha)
Signature: sr_dirichlet_mean(alpha DOUBLE[]) -> DOUBLE[]
Mean vector of the Dirichlet distribution: alpha_i / alpha_0 where alpha_0 is the sum of the
concentration parameters.
SELECT sr_dirichlet_mean([1.0, 2.0, 3.0, 4.0])
-- [0.1, 0.2, 0.3, 0.4]
sr_dirichlet_variance(alpha)
Signature: sr_dirichlet_variance(alpha DOUBLE[]) -> DOUBLE[]
Covariance matrix of the Dirichlet distribution as a row-major flattened LIST of length
len(alpha)².
SELECT sr_dirichlet_variance([1.0, 2.0])
-- [0.05555555555555556, -0.05555555555555556, -0.05555555555555556, 0.05555555555555556]
sr_dirichlet_entropy(alpha)
Signature: sr_dirichlet_entropy(alpha DOUBLE[]) -> DOUBLE
Differential entropy of Dir(alpha).
SELECT sr_dirichlet_entropy([1.0, 1.0])
-- -8.881784197001252e-16
For alpha = (1, 1) the entropy is 0; the tiny negative value is floating-point noise.
sr_multinomial_pmf(probs, trials, counts)
Signature: sr_multinomial_pmf(probs DOUBLE[], trials UBIGINT, counts UBIGINT[]) -> DOUBLE
Probability mass of a count vector under a multinomial distribution.
probs: category probabilities (must sum to 1 in effect; statrs normalises internally)trials: total number of trials, a UBIGINTcounts: observations per category,LIST(BIGINT)
The counts must sum to trials. A non-integer trials is a query error.
SELECT sr_multinomial_pmf([0.5, 0.5], 4, [2::UBIGINT, 2::UBIGINT])
-- 0.3750000000000001
SELECT sr_multinomial_pmf([0.5, 0.5], 4.5, [2::UBIGINT, 2::UBIGINT])
-- error: no matching signature: trials is UBIGINT, so 4.5 does not bind
sr_multinomial_ln_pmf(probs, trials, counts)
Signature: sr_multinomial_ln_pmf(probs DOUBLE[], trials UBIGINT, counts UBIGINT[]) -> DOUBLE
Log probability mass of a count vector. Unlike pmf, a count vector that does not sum to
trials is not an error but a legitimate -inf (the log of probability 0). For large trials
the log form stays finite where the mass itself would underflow.
SELECT sr_multinomial_ln_pmf([0.5, 0.5], 2000, [1000::UBIGINT, 1000::UBIGINT])
-- -4.026367582410558
sr_multinomial_mean(probs, trials)
Signature: sr_multinomial_mean(probs DOUBLE[], trials UBIGINT) -> DOUBLE[]
Mean vector of the multinomial distribution: n · p_i per category.
SELECT sr_multinomial_mean([0.3, 0.7], 5)
-- [1.5, 3.5]
sr_multinomial_variance(probs, trials)
Signature: sr_multinomial_variance(probs DOUBLE[], trials UBIGINT) -> DOUBLE[]
Covariance matrix of the multinomial distribution as a row-major flattened LIST of length
len(probs)²: diagonal n · p_i · (1 − p_i), off-diagonal −n · p_i · p_j.
SELECT sr_multinomial_variance([0.1, 0.3, 0.6], 10)
-- [0.9, -0.3, -0.6, -0.3, 2.1, -1.8, -0.6, -1.8, 2.4]
Shape validation
A matrix argument is validated against the vector length:
SELECT sr_multivariate_normal_pdf([0.0, 0.0], [0.0, 0.0], [1.0, 0.0])
-- error: sr_multivariate_normal_pdf: expected 4 entries for a 2x2 covariance matrix (row-major), got 2