Bilby output

In this document, we will describe what bilby outputs, where it is stored, and how you can access it. When you call run_sampler, there are two arguments outdir and label which are used in generating all the file names for saved data. In the rest of these documents, we’ll assume the defaults where used (which are outdir and label).

The result file

First off, the primary data dump of bilby goes into outdir/label_result.json. This is a JSON file, so it is human readable. Note, older version of bilby used a H5 file, the use of H5 files is still possible in bilby, but we recommend using the default JSON format.

Here is an example of the first 10 lines of a result file

(base) 15:49 outdir [master]: $ head gaussian_example_result.json
{
  "label": "gaussian_example",
  "outdir": "/home/user1/bilby/examples/other_examples/outdir",
  "sampler": "dynesty",
  "log_evidence": -278.8659756143005,
  "log_evidence_err": 0.06169580559443693,
  "log_noise_evidence": NaN,
  "log_bayes_factor": NaN,
  "priors": {
    "mu": "Uniform(minimum=0, maximum=5, name='mu', latex_label='mu', unit=None, boundary=None)",
  ...
  ...

At its core, the JSON file is a nested set of dictionaries. JSON is a cross platform and language agnostic data format. In python, you can read in a JSON file like this

import json
with open(filename, "r") as f:
    data = json.load(f)

print(In [5]: data.keys())
dict_keys(['label', 'outdir', 'sampler', 'log_evidence', 'log_evidence_err', 'log_noise_evidence', 'log_bayes_factor', 'priors', 'posterior', 'injection_parameters', 'meta_data', 'search_parameter_keys', 'fixed_parameter_keys', 'constraint_parameter_keys', 'sampling_time', 'sampler_kwargs', 'use_ratio', 'log_likelihood_evaluations', 'log_prior_evaluations', 'samples', 'nested_samples', 'parameter_labels', 'parameter_labels_with_unit', 'version']))

This will read in any properly formatted JSON file. However, JSON by default only understands simple data types (str, int, dict, etc). So, complicated things like the posterior (which is a pandas dataframe) will exist, but won’t be easy to use.

Reading in a result file

Rather than reading in the raw json file, you will find it more convenient to instead load the data using bilby. To do this:

>>> import bilby
>>> result = bilby.result.read_in_result(outdir=outdir, label=label)  # OR
>>> result = bilby.result.read_in_result(filename='outdir/label_result.json')

Note, these two lines are equivalent, but show two different ways to read in the data. Using this method, result is now a bilby.result.Result instance and has all the methods and attributes. So, for example, you could call result.plot_corner() to generate a corner plot. This method will also read in a h5 file.

Accessing samples directly

To get the samples for a particular parameter, use:

>>> result.posterior[key]

where key is a string of the parameter name you are interested in. The posterior attribute is a pandas.DataFrame, so if you want to return just a numpy array, use:

>>> result.posterior.[key].values

Saving to ASCII text

You may wish to get hold of the samples in a simple text file, this can be done via:

result.save_posterior_samples()

which will generate a file outdir/label_posterior.txt.

Visualising the results

Bilby also provides some useful built-in plotting tools. Some examples on how to visualise results using these tools (and how to extend them) are shown in one of the tutorials at visualising_the_results.ipynb.