How to use a FIGARO reconstruction
FIGARO, despite being a stochastic sampler, does not produce a set of samples (numbers) directly, but rather a number of figaro.mixture.mixture
objects stored as .json
or .pkl
files. Each of these objects represents a probability density drawn around the probability density that generated the available data. If you need to use these realisations in a python
script (to evaluate their pdf, for example, or to draw realisations from them), here you’ll find the (few!) steps needed for doing so.
Basic usage
Let us assume to have our realisations stored in a file called draws_file.json
(they can be the product of a hierarchical inference or a DPGMM reconstruction, it does not make any difference). The first thing to do is to load the realisations via the dedicated method, figaro.load.load_density
:
from figaro.load import load_density
draws = load_density('./draws_file.json')
draws
will be a list of figaro.mixture.mixture
objects, each of them representing a probability distribution. The methods of this class are modelled after the scipy.stats
methods to facilitate users that are already familiar with the SciPy package:
d = draws[0]
X = [x, y, z]
p = d.pdf(X)
log_p = d.logpdf(X)
c = d.cdf(X)
samples = d.rvs(size = 100)
Advanced use
If you need to draw samples from the median distribution, there is a dedicated method in the figaro.utils
module:
from figaro.utils import rvs_median
samples = rvs_median(draws)
The gradient of the recovered distribution can be evaluated using the gradient()
method of individual draws:
g = d.gradient(X)
It is also possible to evaluate the gradient of the median distribution in a numerically stable way using the dedicated function:
from figaro.utils import gradient_median
g_median = gradient_median(X, draws)
Please note: these methods are painfully slow and we haven’t really found a way of optimising them. If you manage to improve it, please send us a pull request!
For multivariate distributions, it might happen that one needs to evaluate the conditional distribution or the marginal distribution.
Making use of the properties of the multivariate Gaussian distribution, we can obtain the conditional and/or marginal distribution analytically both via the methods included in the figaro.mixture.mixture
class or via the ones in the figaro.marginal
module:
from figaro.marginal import condition, marginalise
# Marginalisation over the last two dimensions of a 3D reconstruction
marg_draws = [d.marginalise((1,2)) for d in draws]
marg_draws = marginalise(draws, (1,2))
# Condition on a specific value Y = [y'] of the second dimension
cond_draws = [d.condition(Y, 2) for d in draws]
cond_draws = condition(draws, Y, 2)
Please note that in both cases the original draws
list is preserved.
Plots
The plots produced by the CLI can be easily reproduced using the methods included in the figaro.plot
module. Please refer to its documentation page for the details.