Priors

Priors#

Note

By default, PyVBMC expects the first argument to VBMC to return the log joint: the sum of the log likelihood and log prior. To pass a log-likelihood function instead, supply the prior separately. The log_prior argument accepts a function of one point that returns its prior log density:

vbmc = VBMC(log_likelihood, x0, lb, ub, plb, pub, log_prior=log_prior_function)

Alternatively, prior accepts:

a PyVBMC prior from pyvbmc.priors with the model dimension;
a compatible continuous scipy.stats distribution with the model dimension; or
a list of one-dimensional PyVBMC priors or continuous scipy.stats distributions, one per parameter. The list entries are treated as independent.

vbmc = VBMC(log_likelihood, x0, lb, ub, plb, pub, prior=UniformBox(0, 1, D=2))
vbmc = VBMC(log_likelihood, x0, lb, ub, plb, pub, prior=scipy.stats.multivariate_normal(mu, cov))
vbmc = VBMC(log_likelihood, x0, lb, ub, plb, pub, prior=[UniformBox(0, 1), scipy.stats.norm()])

The prior support must cover the hard bounds lb and ub; the bounds may coincide with the ends of the support. For example, UniformBox(0, 1, D=2) permits hard bounds on or inside the unit square. Within the hard bounds, VBMC uses the prior as given and does not renormalize it.

See PyVBMC Example 5: Prior distributions and the SciPy, Product and UserFunction sections below for details. PyVBMC wraps these inputs in the corresponding prior classes.

`Prior` base class#

These methods are common to all of the subclasses that follow.

class pyvbmc.priors.Prior[source]#

Abstract base class for PyVBMC prior distributions.

log_pdf(x, keepdims=True)[source]#

Compute the log-pdf of the distribution.

Parameters:

xnp.ndarray: The array of input point(s), of dimension (D,) or (n, D), where D is the distribution dimension. The point(s) are read as float64, whatever dtype the array carries.
keepdimsbool: Whether to keep the input dimensions and return an array of shape (n, 1), or discard them and return an array of shape (n,).

Returns:

log_pdfnp.ndarray: The log-density of the prior at the input point(s), of dimension (n, 1) or (n,) (depending on keepdims).

pdf(x, keepdims=True)[source]#

Compute the pdf of the distribution.

Parameters:

xnp.ndarray: The array of input point(s), of dimension (D,) or (n, D), where D is the distribution dimension.
keepdimsbool: Whether to keep the input dimensions and return an array of shape (n, 1), or discard them and return an array of shape (n,).

Returns:

pdfnp.ndarray: The density of the prior at the input point(s), of dimension (n, 1) or (n,) (depending on keepdims).

abstractmethod sample(n, rng=None)[source]#

Sample random variables from the distribution.

Parameters:

nint: The number of points to sample.
rngNone, int, SeedSequence or Generator, optional: Random generator or seed; if None a generator is derived from NumPy’s global random state.

Returns:

rvsnp.ndarray: The samples points, of shape (n, D), where D is the dimension.

support()[source]#

Returns the box that bounds the support of the distribution.

For priors that define _support, this is the smallest axis-aligned box containing the support, except that a Product reads each coordinate from its marginal, so a marginal that defines no _support (a UserFunction) spans the whole line. Otherwise, the method reports the whole space. VBMC checks that the hard bounds lie inside the reported box.

Returns:

lb, ubtuple(np.ndarray, np.ndarray): A tuple of lower and upper bounds of the support, such that [lb[i], ub[i]] bounds the support of the ith marginal.

Bounded priors#

`UniformBox`#

class pyvbmc.priors.UniformBox(a, b, D=None)[source]#

Multivariate uniform-box prior.

A prior distribution represented by box of uniform dimension, with lower bound(s) a and upper bound(s) b.

Attributes:

Dint: The dimension of the prior distribution.
anp.ndarray: The lower bound(s), shape (D,).
bnp.ndarray: The upper bound(s), shape (D,).

__init__(a, b, D=None)[source]#

Initialize a multivariate uniform-box prior.

Parameters:

anp.ndarray | float: The lower bound(s), shape (D,) where D is the dimension (parameters of type float will be tiled to this shape).
bnp.ndarray | float: The upper bound(s), shape (D,) where D is the dimension (parameters of type float will be tiled to this shape).
Dint, optional: The distribution dimension. If given, will convert scalar a and b to this dimension.

Raises:

ValueError: If any bound is not finite, if an array argument does not agree in shape with the other arguments or with D, or if a[i] >= b[i], for any i.

`Trapezoidal`#

class pyvbmc.priors.Trapezoidal(a, u, v, b, D=None)[source]#

Multivariate trapezoidal prior.

A prior distribution represented by a density with external bounds a and b and internal points u and v. Each marginal distribution has a trapezoidal density which is uniform between u[i] and v[i] and falls off linearly to zero at a[i] and b[i]:

         ______________________
        |       ________       |
        |      /|      |\      |
p(X(i)) |     / |      | \     |
        |    /  |      |  \    |
        |___/___|______|___\___|
          a[i] u[i]  v[i] b[i]
                  X(i)

The overall density is a product of these marginals.

Attributes:

Dint: The dimension of the prior distribution.
anp.ndarray: The lower bound(s), shape (D,).
unp.ndarray: The lower pivot(s), shape (D,).
vnp.ndarray: The upper pivot(s), shape (D,).
bnp.ndarray: The upper bound(s), shape (D,).

__init__(a, u, v, b, D=None)[source]#

Initialize a multivariate trapezoidal prior.

Parameters:

anp.ndarray | float: The lower bound(s), shape (D,) where D is the dimension (parameters of type float will be tiled to this shape).
unp.ndarray | float: The lower pivot(s), shape (D,) where D is the dimension (parameters of type float will be tiled to this shape).
vnp.ndarray | float: The upper pivot(s), shape (D,) where D is the dimension (parameters of type float will be tiled to this shape).
bnp.ndarray | float: The upper bound(s), shape (D,) where D is the dimension (parameters of type float will be tiled to this shape).
Dint, optional: The distribution dimension. If given, will convert scalar a, u, v, and b to this dimension.

Raises:

ValueError: If any bound or pivot is not finite, if an array argument does not agree in shape with the other arguments or with D, or if the order a[i] < u[i] < v[i] < b[i] is not respected, for any i.

`SplineTrapezoidal`#

class pyvbmc.priors.SplineTrapezoidal(a, u, v, b, D=None)[source]#

Multivariate spline-trapezoidal prior.

A prior distribution represented by a density with external bounds a and b and internal points u and v. Each marginal distribution has a spline-trapezoidal density which is uniform between u[i] and v[i] and falls off as a cubic spline to zero at a[i] and b[i], such that the pdf is continuous and its derivatives at a[i], u[i], v[i], and b[i] are zero (so the derivatives are also continuous):

         ______________________
        |      __________      |
        |     / |      | \     |
p(X(i)) |    |  |      |  |    |
        |    |  |      |  |    |
        |___/___|______|___\___|
          a[i] u[i]  v[i] b[i]
                  X(i)

The overall density is a product of these marginals.

Attributes:

Dint: The dimension of the prior distribution.
anp.ndarray: The lower bound(s), shape (D,).
unp.ndarray: The lower pivot(s), shape (D,).
vnp.ndarray: The upper pivot(s), shape (D,).
bnp.ndarray: The upper bound(s), shape (D,).

__init__(a, u, v, b, D=None)[source]#

Initialize a multivariate trapezoidal prior.

Parameters:

anp.ndarray | float: The lower bound(s), shape (D,) where D is the dimension (parameters of type float will be tiled to this shape).
unp.ndarray | float: The lower pivot(s), shape (D,) where D is the dimension (parameters of type float will be tiled to this shape).
vnp.ndarray | float: The upper pivot(s), shape (D,) where D is the dimension (parameters of type float will be tiled to this shape).
bnp.ndarray | float: The upper bound(s), shape (D,) where D is the dimension (parameters of type float will be tiled to this shape).
Dint, optional: The distribution dimension. If given, will convert scalar a, u, v, and b to this dimension.

Raises:

ValueError: If any bound or pivot is not finite, if an array argument does not agree in shape with the other arguments or with D, or if the order a[i] < u[i] < v[i] < b[i] is not respected, for any i.

Unbounded priors#

`SmoothBox`#

class pyvbmc.priors.SmoothBox(a, b, scale=1, D=None)[source]#

Multivariate smooth-box prior.

For each dimension i, the univariate smooth-box pdf is defined as a uniform distribution between pivots a[i], b[i] with Gaussian tails that fall starting from p(a[i]) to the left (resp., p(b[i]) to the right) with standard deviation scale[i].

Attributes:

Dint: The dimension of the prior distribution.
anp.ndarray: The lower pivot(s), shape (D,).
bnp.ndarray: The upper pivot(s), shape (D,).
scalenp.ndarray: The standard deviation of the Gaussian tails, shape (D,).

__init__(a, b, scale=1, D=None)[source]#

Initialize a multivariate smooth-box prior.

Parameters:

anp.ndarray | float: The lower pivot(s), shape (D,) where D is the dimension (parameters of type float will be tiled to this shape).
bnp.ndarray | float: The upper pivot(s), shape (D,) where D is the dimension (parameters of type float will be tiled to this shape).
scalenp.ndarray | float, optional: The standard deviation of the Gaussian tails, shape (D,) where D is the dimension (parameters of type float will be tiled to this shape). Default 1.
Dint, optional: The distribution dimension. If given, will convert scalar a, b, and scale to this dimension.

Raises:

ValueError: If any pivot or scale is not finite, if an array argument does not agree in shape with the other arguments or with D, if scale[i] <= 0, or if a[i] >= b[i], for any i.

Other priors and functions#

`Product` priors#

When a user passes a list of Prior instances or scipy.stats distributions, PyVBMC converts it to a Product prior with one marginal distribution per item.

class pyvbmc.priors.Product(marginals)[source]#

A product of independent univariate priors.

Attributes:

Dint: The dimension of the product distribution.
marginalspyvbmc.priors.Prior: The underlying marginal prior distribution(s).
anp.ndarray: np.ndarray: The lower bound(s) of the support, shape (D,).
bnp.ndarray: np.ndarray: The upper bound(s) of the support, shape (D,).

__init__(marginals)[source]#

Initialize a Product prior from a list of marginal priors.

Parameters:

marginalslist of pyvbmc.priors.Prior: The underlying marginal prior distribution(s). Each must have dimension 1.

Raises:

TypeError: If the provided marginals are not a list, or if they are not all PyVBMC priors or appropriate SciPy distributions.
ValueError: If the provided marginals are not all univariate.

property a#: np.ndarray: The lower bound(s) of the support, shape (D,).

property b#: np.ndarray: The upper bound(s) of the support, shape (D,).

`SciPy` priors#

When a user provides a scipy.stats distribution as a prior, PyVBMC wraps it in a SciPy prior.

class pyvbmc.priors.SciPy(distribution)[source]#

Wrapper class for scipy.stats distributions.

Attributes:

Dint: The dimension of the prior distribution.
distributionfrozen scipy.stats distribution: The underlying continuous univariate, multivariate normal, or multivariate t distribution.
anp.ndarray: np.ndarray: The lower bound(s) of the support, shape (D,).
bnp.ndarray: np.ndarray: The upper bound(s) of the support, shape (D,).

__init__(distribution)[source]#

Initialize pyvbmc.priors.Prior from scipy.stats distribution(s).

Parameters:

distributionscipy.stats.multivariate_normal or scipy.stats.multivariate_t or scipy.stats.rv_continuous The underlying scipy.stats distributions. Should be a: multivariate normal distribution, a multivariate t distribution, or a univariate continuous distribution (for 1-D models).

Raises:

TypeError: If the provided distribution is not of the appropriate type.
ValueError: If a univariate distribution carries a parameter which is not a scalar, so that it stands for more than one variable.

property a#: np.ndarray: The lower bound(s) of the support, shape (D,).

property b#: np.ndarray: The upper bound(s) of the support, shape (D,).

`UserFunction` priors#

To standardize the interface, when a user provides a function as a log-prior it is wrapped in a UserFunction prior.

class pyvbmc.priors.UserFunction(log_prior, sample_prior=None, D=None)[source]#

Lightweight wrapper for user-defined priors.

An instance’s log_pdf is the user-provided function for the log-density of the prior, and its sample is the user-provided function for sampling from the prior, or None if none was provided; both are set at initialization, in place of the methods of the same names.

Attributes:

Dint or None: The dimension of the prior, if provided.

__init__(log_prior, sample_prior=None, D=None)[source]#

Initialize a user-specified prior from a function.

Parameters:

log_priorcallable, optional: The user-provided function. Should take a one-dimensional array as a single argument, and return the log-density of the prior evaluated at that point as one value: a float, or an array of one element.
sample_priorcallable, optional: An optional user-provided function for sampling from the prior. Should take an integer n as a single argument, and return n samples from the prior distribution as an (n, D) array.
Dint, optional: Specified dimension of the prior (optional).

Utility functions#

pyvbmc.priors.convert_to_prior(prior=None, log_prior=None, sample_prior=None, D=None)[source]#

Convert an object to a pyvbmc Prior instance.

Parameters:

prior, optional

The object to convert to a PyVBMC Prior. May be one of:

a PyVBMC prior, which will remain unchanged,
a frozen SciPy multivariate normal, multivariate t, or one-dimensional continuous distribution, which will be converted to a PyVBMC SciPy prior, or
a list of one-dimensional continuous SciPy distributions and/or PyVBMC Prior objects, which will be treated as independent marginals of a Product prior.
None, in which case log_prior (and optionally sample_prior) are used to build a user-defined Prior.

log_priorcallable, optional

A function of a single argument x which returns the log-density of the prior at x. Optional, should agree with prior.log_pdf if both are provided.

sample_priorcallable, optional

A function of a single argument n which returns n samples from the prior distribution. Optional, should agree with prior.sample if both are provided.

Dint, optional

The dimension of the prior distribution. Optional, used only for user-defined priors.

Returns:

priorPyVBMC.priors.Prior

pyvbmc.priors.tile_inputs(*args, size=None, squeeze=False)[source]#

Tile scalar inputs to have the same dimension as array inputs.

If all inputs are given as scalars, returned arrays will have shape size if size is a tuple, or shape (size,) if size is an integer.

An argument agrees with size when the two hold the same lengths once their axes of length one are dropped, so that a row, a column and a flat array of D elements all agree with size=D while an array of another layout, such as (2, 2) against size=4, does not.

Parameters:

*args[Union[float, np.ndarray]]: The inputs to tile.
sizeUnion[int, tuple], optional: The desired size/shape of the output. By default the shape of the non-scalar inputs, or (1,) when every input is a scalar.
squeezebool: If True, then drop 1-d axes from inputs. Default False.

Returns:

argslist of np.ndarray: The inputs, in their order, each of shape size.

Raises:

ValueError: If the non-scalar arguments do not have the same shape, or if they do not agree with size.

pyvbmc.priors.is_valid_scipy_dist(obj)[source]#

Assess whether obj is a valid SciPy distribution for a PyVBMC prior.

A valid SciPy distribution is a frozen multivariate normal, multivariate t, or continuous univariate distribution.

Parameters:

objany: The object to type-check.

Returns:

is_validbool

Priors

Contents

Priors#

Prior base class#

Bounded priors#

UniformBox#

Trapezoidal#

SplineTrapezoidal#

Unbounded priors#

SmoothBox#

Other priors and functions#

Product priors#

SciPy priors#

UserFunction priors#

Utility functions#

`Prior` base class#

`UniformBox`#

`Trapezoidal`#

`SplineTrapezoidal`#

`SmoothBox`#

`Product` priors#

`SciPy` priors#

`UserFunction` priors#