Priors

Priors#

Note

By default, PyVBMC assumes that the first argument to VBMC is a function which returns the log-joint (i.e., the sum of log-likelihood and log-prior). However, you may instead pass a function which returns the log-likelihood as a first argument, and supply the prior separately. Using the keyword log_prior, you may pass a function (of a single argument) which returns the log-density of the prior given a point:

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

Alternatively, using the keyword prior, you may pass one of the following:

a PyVBMC prior imported from pyvbmc.priors that matches the dimension of the model,
an appropriate continuous scipy.stats distribution that matches the dimension of the model, or
a list of univariate (i.e., one-dimensional) PyVBMC priors and/or continuous scipy.stats distributions, which are treated as independent priors for each parameter $theta_{i}$. In this case the length of the list should equal the dimension of the model.

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()])

For more details on (1), see the documentation below as well as PyVBMC Example 5: Prior distributions. For more details on (2), (3), and using a function as a log_prior, see the documentation on SciPy priors, Product priors, and UserFunction priors below. (keyword arguments of these types will be converted to instances of these 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.
keepdimsbool: Whether to keep the input dimensions and return an array of shape (1, D), or discard them and return an array of shape (D,).

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 (1, D), or discard them and return an array of shape (D,).

Returns:

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

abstract sample(n)[source]#

Sample random variables from the distribution.

Parameters:

nint: The number of points to sample.

Returns:

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

support()[source]#

Returns the support of the distribution.

Used to test that the distribution integrates to one, so it is also acceptable to return a box which bounds the support of the distribution.

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 (1, D).
bnp.ndarray: The upper bound(s), shape (1, 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).

Raises:

ValueError: 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 of 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 (1, D).
unp.ndarray: The lower pivot(s), shape (1, D).
vnp.ndarray: The upper pivot(s), shape (1, D).
bnp.ndarray: The upper bound(s), shape (1, 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 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-trapezoidalal density which is uniform between u[i] and v[i] and falls of as a cubic spline to zero 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 (1, D).
unp.ndarray: The lower pivot(s), shape (1, D).
vnp.ndarray: The upper pivot(s), shape (1, D).
bnp.ndarray: The upper bound(s), shape (1, 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 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 (1, D).
bnp.ndarray: The upper pivot(s), shape (1, D).
scalenp.ndarray: The standard deviation of the Gaussian tails, shape (1, 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: The standard deviation of the Gaussian tails, shape (D,) where D is the dimension (parameters of type float will be tiled to this shape).

Raises:

ValueError: 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, they are converted to a Product prior with a corresponding marginal distributions for each item in the list.

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

A prior which is an product of independent univariate priors.

Attributes:

Dint: The dimension of the product distribution.
marginalspyvbmc.priors.Prior: The underlying marginal prior distribution(s).

__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.

`SciPy` priors#

To standardize the interface, when a user provides a scipy.stats distribution as a prior, it is wrapped in a SciPy prior distribution

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

Wrapper class for scipy.stats distributions.

Attributes:

Dint: The dimension of the prior distribution.
distributionscipy.stats._multivariate.multivariate_normal_frozen or scipy.stats._multivariate.multivariate_t_frozen or scipy.stats._distn_infrastructure.rv_continuous_frozen: The underlying scipy.stats distributions.

__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.

`UserFunction` priors#

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

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

Lightweight wrapper for user-defined priors.

Attributes:

log_pdfcallable: Compute the log-pdf of the distribution.
samplecallable or None: Unused
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.
sample_priorcallable, optional: An optional user-provided function for sampling form 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.

sample_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.

Parameters:

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

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#