Lucid3.0
class

LKJCholesky

extendsDistribution
LKJCholesky(dim: int, concentration: Tensor | float = 1.0, validate_args: bool | None = None)
source

LKJ distribution over Cholesky factors of correlation matrices.

Generative prior for the lower-triangular Cholesky factor LL of a correlation matrix R=LL⊤R = L L^\top of size D×DD \times D. Density is proportional to det⁡(R)η−1\det(R)^{\eta - 1} so the η\eta parameter ("concentration") controls how concentrated the prior is around the identity (uncorrelated). Widely used as a weakly-informative prior on correlation structure in Bayesian hierarchical models — replacing an inverse-Wishart prior (which couples scale and correlation) with a clean separation.

Parameters

dimint
Size DD of the correlation matrix (must be ≥2\geq 2).
concentrationTensor or float= 1.0
Shape parameter η>0\eta > 0. Default 1.0 (uniform over the space of correlation matrices). η>1\eta > 1 concentrates mass near the identity (low correlation), η<1\eta < 1 favours high-correlation factors.
validate_argsbool= None
If True, validate parameter constraints at construction.

Notes

Probability density on the manifold of valid Cholesky factors LL:

p(L;η)∝∣det⁡R(L)∣η−1=∏i=1D−1LiiD−i+2(η−1)p(L; \eta) \propto |\det R(L)|^{\eta - 1} = \prod_{i=1}^{D-1} L_{ii}^{D - i + 2(\eta - 1)}

where the second equality follows from the Jacobian of the transformation between RR and its Cholesky factor.

Sampling uses the vectorised Onion method (Lewandowski, Kurowicka & Joe, 2009, §3) — row ii is built incrementally so that its squared norm equals one, with off-diagonal magnitude drawn from a Beta and angular components from a uniform on the sphere. The full sampler runs in O(D2)\mathcal{O}(D^2) per draw with no rejections.

For η=1\eta = 1 the distribution is uniform over valid correlation matrices (specifically, over the set of valid Cholesky factors).

Examples

>>> import lucid
>>> from lucid.distributions import LKJCholesky
>>> dist = LKJCholesky(dim=4, concentration=2.0)
>>> L = dist.sample()           # (4, 4) lower-triangular Cholesky factor
>>> R = L @ L.T                 # implied correlation matrix
>>> R.diagonal()                # diagonal of R is all 1's
Tensor([1., 1., 1., 1.])
Use as a Bayesian prior over correlation structure:
>>> prior = LKJCholesky(dim=8, concentration=1.5)
>>> # ... pair with marginal scales / standard deviations to form a
>>> #     covariance prior: Σ = diag(σ) · R · diag(σ)

Methods (4)

dunder

__init__

→None
__init__(dim: int, concentration: Tensor | float = 1.0, validate_args: bool | None = None)
source

Initialise an LKJ distribution over Cholesky factors.

Pre-computes the Beta distribution parameters used by the vectorised Onion sampler (Lewandowski et al. 2009, §3).

Parameters

dimint
Dimension D≥2D \geq 2 of the correlation matrix.
concentrationTensor | float= 1.0
Shape parameter η>0\eta > 0. Default is 1.0 (uniform distribution over correlation matrices). Larger values concentrate mass near the identity (near-zero correlations).
validate_argsbool | None= None
If True, validate parameter constraints at construction time.
prop

support

→Constraint
support: Constraint
source

Constraint: positive-definite matrices (proxy for correlation-Cholesky support).

fn

sample

→Tensor
sample(sample_shape: tuple[int, ...] = ())
source

Draw a sample via the vectorised Onion method (Lewandowski 2009 §3).

Returns the lower Cholesky factor L of a random correlation matrix.

fn

log_prob

→Tensor
log_prob(value: Tensor)
source

Log-density of the LKJ distribution on a Cholesky factor.

The density is proportional to ∏_{i=2}^{d} L_{ii}^{order_i} where order_i = 2(η − 1) + (d − i).

The normaliser follows Eq. (15) of Lewandowski et al. (2009).