Prior
Instances of Prior
are called by worker sampling processes for
evaluation of a joint prior distribution.
- class xpsi.Prior.Prior(parameters=None, *hyperparameters)[source]
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., viasuper()
) 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)[source]
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)[source]
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)[source]
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)[source]
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)[source]
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)[source]
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
wherelen(p) > len(self)
.- Return type:
list
- property unit_hypercube_frac
Get the fractional hypervolume with finite prior density.