bf.dist.projected_normal: Samples from a Projected Normal distribution.

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

Samples from a Projected Normal distribution.

Description

The projected normal distribution arises by taking a multivariate normal vector

\mathbf X \sim \mathcal N_n (\mu, \Sigma)

in

\mathbb R^n

and projecting it to the unit sphere. This distribution is commonly used in directional statistics (data on circles or spheres) and supports asymmetric and even multimodal behaviours depending on parameters.

Usage

bf.dist.projected_normal(
  concentration,
  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

concentration	A numeric vector representing the concentration parameter, representing the direction towards which the samples are concentrated.
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 array 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	The number of batch dimensions to reinterpret as event dimensions (used in model building).
create_obj	Logical; If 'TRUE', returns the raw BI distribution object instead of creating a sample site. This is essential for building complex distributions like 'MixtureSameFamily'.
to_jax	Boolean. Indicates whether to return a JAX array or not.

Value

- When sample=FALSE, a BI Projected Normal distribution object (for model building).

- When sample=TRUE, a JAX array of samples drawn from the Projected Normal distribution (for direct sampling).

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

See Also

https://num.pyro.ai/en/stable/distributions.html#projectednormal

Examples

library(BayesForge)
m=importBF(platform='cpu')
bf.dist.projected_normal(concentration = c(1.0, 3.0, 2.0), sample = TRUE)

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