Prior

Instances of Prior are called by worker sampling processes for evaluation of a joint prior distribution.

class xpsi.Prior.Prior(parameters=None, *hyperparameters)

The joint prior distribution of parameters (including hyperparameters).

Methods to both evaluate the distribution (required by MCMC) and draw uniformly from the distribution (required for nested sampling, and by default is used to initialise an ensemble of MCMC chains).

The distribution must be integrable (proper) and is thus usually bounded (compactly supported on a space).

In the __call__() method the parameter values are checked against the hard parameter bounds of the prior support.

Note

If you wish to check bounds manually, implement the __init__() and __call__() methods, and do not access the default code (e.g., via super()) or only use the default code for some parameters.

Parameters:

• parameters (obj) – An optional instance of ParameterSubspace.

• hyperparameters (obj) – Positional arguments that are hyperparameters (parameters of the prior distribution), or iterables of hyperparameters.

abstract __call__(p=None)

Evaluate distribution at p and store it as a property.

Parameters:

p (list) – Vector of model parameter values, but typically unused. If you use it, handle it in a custom implementation of this method.

draw(ndraws, transform=False)

Draw samples uniformly from the prior via inverse sampling.

Parameters:

ndraws (int) – Number of draws.

Returns:

(samples, acceptance fraction)

Return type:

(ndarray[ndraws, len(self)], float)

estimate_hypercube_frac(ndraws=5)

Estimate using Monte Carlo integration the fractional hypervolume within a unit hypercube at which prior density is finite.

Parameters:

ndraws (optional[int]) – Base-10 logarithm of number of draws from the prior to require at which the density is finite.

abstract inverse_sample(hypercube=None)

Draw sample uniformly from the distribution via inverse sampling.

By default, implements a flat density between bounds. If None is in a tuple of bounds, None is assigned to the corresponding coordinate and the user must handle in a custom subclass.

Parameters:

hypercube (iterable) – A pseudorandom point in an n-dimensional hypercube.

Returns:

A parameter list.

Note

If you call this base method via the super() built-in, the current parameter values will be cached when new values are assigned. If you then assign to a parameter again, the current value will be automatically cached, thus overwriting the cache established in the body of this present method. If you want to call this present method and then assign again to a parameter, you can restore the cached value so that it is pushed to the cache when you reassign.

inverse_sample_and_transform(hypercube=None)

Inverse sample and then transform.

This method is useful for drawing from the prior when overplotting posterior and prior density functions.

static transform(p, **kwargs)

A transformation for post-processing.

A subclass can implement this attribute as an instance method: it does not need to be a static method.

Parameters:

p (list) – Parameter vector.

Kwargs:

A key sometimes passed is old_API, which flags whether a transformation needs to account for a parameter vector written to file by an older software version, which might be different in due to transformations of parameters defined in the current software version.

Note

As an example, the Riley et al. 2019 samples are in inclination \(i\) instead of \(\cos(i)\) which is the current inclination parameter in the API. Therefore the transformation needed depends on the source of the parameter vector. If the vector is from the original sample files, then it needs to be transformed to have the same parameter definitions as the current API. However, when drawing samples from the prior in the current API, no such transformation needs to be performed because these are the definitions we need to match. Refer to the dummy example code in the method body.

Returns:

Transformed vector p where len(p) > len(self).

Return type:

list

property unit_hypercube_frac

Get the fractional hypervolume with finite prior density.