bf.dist.lkj: Samples from an LKJ (Lewandowski, Kurowicka, Joe)...

In BayesForge: Bayesian Inference using 'numpyro' and 'XLA'

Samples from an LKJ (Lewandowski, Kurowicka, Joe) distribution for correlation matrices.

Description

The LKJ distribution is controlled by the concentration parameter

\eta

to make the probability of the correlation matrix M proportional to

\det(M)^{\eta - 1}

. When

\eta = 1

, the distribution is uniform over correlation matrices. When

\eta > 1

, the distribution favors samples with large determinants. When

\eta < 1

, the distribution favors samples with small determinants.

Usage

bf.dist.lkj(
  dimension,
  concentration = 1,
  sample_method = "onion",
  validate_args = py_none(),
  name = "x",
  obs = py_none(),
  mask = py_none(),
  sample = FALSE,
  seed = py_none(),
  shape = c(),
  event = 0,
  create_obj = FALSE,
  to_jax = TRUE
)

Arguments

dimension	An integer representing the dimension of the correlation matrices.
concentration	A numeric vector representing the concentration/shape parameter of the distribution (often referred to as eta). Must be positive.
sample_method	(str): Either "cvine" or "onion". Methods proposed offer the same distribution over correlation matrices. But they are different in how to generate samples. Defaults to "onion".
validate_args	Logical: Whether to validate parameter values. Defaults to 'reticulate::py_none()'.
name	A character string representing the name of the random variable within a model. This is used to uniquely identify the variable. Defaults to 'x'.
obs	A numeric vector or array of observed values. If provided, the random variable is conditioned on these values. If 'NULL', the variable is treated as a latent (unobserved) variable. Defaults to 'NULL'.
mask	An optional boolean vector to mask observations.
sample	A logical value that controls the function's behavior. If 'TRUE', the function will directly draw samples from the distribution. If 'FALSE', it will create a random variable within a model. Defaults to 'FALSE'.
seed	An integer used to set the random seed for reproducibility when 'sample = TRUE'. This argument has no effect when 'sample = FALSE', as randomness is handled by the model's inference engine. Defaults to 0.
shape	A numeric vector used for shaping. When 'sample=False' (model building), this is used with ‘.expand(shape)' to set the distribution’s batch shape. When 'sample=True' (direct sampling), this is used as 'sample_shape' to draw a raw JAX array of the given shape.
event	An integer representing the number of batch dimensions to reinterpret as event dimensions (used in model building).
create_obj	A logical value. If 'TRUE', returns the raw BI distribution object instead of creating a sample site.
to_jax	Boolean. Indicates whether to return a JAX array or not.

Value

- When sample=FALSE: A BI LKJ distribution object (for model building).

- When sample=TRUE: A JAX array of samples drawn from the LKJ distribution (for direct sampling).

- When create_obj=TRUE: The raw BI distribution object (for advanced use cases).

See Also

This is a wrapper of https://num.pyro.ai/en/stable/distributions.html#lkj

Examples

library(BayesForge)
m=importBF(platform='cpu')
bf.dist.lkj( dimension = 2, concentration=1.0, shape = c(1), sample = TRUE)

BayesForge documentation built on June 9, 2026, 1:09 a.m.