bilby.core.result.Result

class bilby.core.result.Result(label='no_label', outdir='.', sampler=None, search_parameter_keys=None, fixed_parameter_keys=None, constraint_parameter_keys=None, priors=None, sampler_kwargs=None, injection_parameters=None, meta_data=None, posterior=None, samples=None, nested_samples=None, log_evidence=nan, log_evidence_err=nan, information_gain=nan, log_noise_evidence=nan, log_bayes_factor=nan, log_likelihood_evaluations=None, log_prior_evaluations=None, sampling_time=None, nburn=None, num_likelihood_evaluations=None, walkers=None, max_autocorrelation_time=None, use_ratio=None, parameter_labels=None, parameter_labels_with_unit=None, version=None)

Bases: object

__init__(label='no_label', outdir='.', sampler=None, search_parameter_keys=None, fixed_parameter_keys=None, constraint_parameter_keys=None, priors=None, sampler_kwargs=None, injection_parameters=None, meta_data=None, posterior=None, samples=None, nested_samples=None, log_evidence=nan, log_evidence_err=nan, information_gain=nan, log_noise_evidence=nan, log_bayes_factor=nan, log_likelihood_evaluations=None, log_prior_evaluations=None, sampling_time=None, nburn=None, num_likelihood_evaluations=None, walkers=None, max_autocorrelation_time=None, use_ratio=None, parameter_labels=None, parameter_labels_with_unit=None, version=None)

A class to store the results of the sampling run

Parameters:

label, outdir, sampler: str

The label, output directory, and sampler used

search_parameter_keys, fixed_parameter_keys, constraint_parameter_keys: list

Lists of the search, constraint, and fixed parameter keys. Elements of the list should be of type str and match the keys of the prior

priors: dict, bilby.core.prior.PriorDict

A dictionary of the priors used in the run

sampler_kwargs: dict

Key word arguments passed to the sampler

injection_parameters: dict

A dictionary of the injection parameters

meta_data: dict

A dictionary of meta data to store about the run

posterior: pandas.DataFrame

A pandas data frame of the posterior

samples, nested_samples: array_like

An array of the output posterior samples and the unweighted samples

log_evidence, log_evidence_err, log_noise_evidence, log_bayes_factor: float

Natural log evidences

information_gain: float

The Kullback-Leibler divergence

log_likelihood_evaluations: array_like

The evaluations of the likelihood for each sample point

num_likelihood_evaluations: int

The number of times the likelihood function is called

log_prior_evaluations: array_like

The evaluations of the prior for each sample point

sampling_time: datetime.timedelta, float

The time taken to complete the sampling

nburn: int

The number of burn-in steps discarded for MCMC samplers

walkers: array_like

The samplers taken by a ensemble MCMC samplers

max_autocorrelation_time: float

The estimated maximum autocorrelation time for MCMC samplers

use_ratio: bool

A boolean stating whether the likelihood ratio, as opposed to the likelihood was used during sampling

parameter_labels, parameter_labels_with_unit: list

Lists of the latex-formatted parameter labels

version: str,

Version information for software used to generate the result. Note, this information is generated when the result object is initialized

Notes

All sampling output parameters, e.g. the samples themselves are typically not given at initialisation, but set at a later stage.

__call__(*args, **kwargs)

Call self as a function.

Methods

__init__([label, outdir, sampler, ...])	A class to store the results of the sampling run
calculate_prior_values(priors)	Evaluate prior probability for each parameter for each sample.
from_hdf5([filename, outdir, label])	Read in a saved .hdf5 data file
from_json([filename, outdir, label, gzip])	Read in a saved .json data file
from_pickle([filename, outdir, label])	Read in a saved .pickle data file
get_all_injection_credible_levels([keys, ...])	Get credible levels for all parameters
get_injection_credible_level(parameter[, ...])	Get the credible level of the injected parameter
get_latex_labels_from_parameter_keys(keys)	Returns a list of latex_labels corresponding to the given keys
get_one_dimensional_median_and_error_bar(key)	Calculate the median and error bar for a given key
get_weights_by_new_prior(old_prior, new_prior)	Calculate a list of sample weights based on the ratio of new to old priors
occam_factor(priors)	The Occam factor,
plot_corner([parameters, priors, titles, ...])	Plot a corner-plot
plot_marginals([parameters, priors, titles, ...])	Plot 1D marginal distributions
plot_single_density(key[, prior, ...])	Plot a 1D marginal density, either probability or cumulative.
plot_walkers(**kwargs)	Method to plot the trace of the walkers in an ensemble MCMC plot
plot_with_data(model, x, y[, ndraws, ...])	Generate a figure showing the data and fits to the data
posterior_probability(sample)	Calculate the posterior probability for a new sample
prior_volume(priors)	The prior volume, given a set of priors
samples_to_posterior([likelihood, priors, ...])	Convert array of samples to posterior (a Pandas data frame)
save_posterior_samples([filename, outdir, label])	Saves posterior samples to a file
save_to_file([filename, overwrite, outdir, ...])	Writes the Result to a file.
to_arviz([prior])	Convert the Result object to an ArviZ InferenceData object.

Attributes

bayesian_model_dimensionality	Characterises how many parameters are effectively constraint by the data
covariance_matrix	The covariance matrix of the samples the posterior
kde	Kernel density estimate built from the stored posterior
log_10_bayes_factor
log_10_evidence
log_10_evidence_err
log_10_noise_evidence
meta_data
nburn	" An array of the ensemble walkers
nested_samples	" An array of unweighted samples
num_likelihood_evaluations	number of likelihood evaluations
posterior	A pandas data frame of the posterior
posterior_volume	The posterior volume
priors
samples	An array of samples
version
walkers	" An array of the ensemble walkers

property bayesian_model_dimensionality

Characterises how many parameters are effectively constraint by the data

See <https://arxiv.org/abs/1903.06682>

Returns:

float: The model dimensionality

calculate_prior_values(priors)

Evaluate prior probability for each parameter for each sample.

Parameters:

priors: dict, PriorDict

Prior distributions

property covariance_matrix

The covariance matrix of the samples the posterior

classmethod from_hdf5(filename=None, outdir=None, label=None)

Read in a saved .hdf5 data file

Parameters:

filename: str

If given, try to load from this filename

outdir, label: str

If given, use the default naming convention for saved results file

Returns:

result: bilby.core.result.Result

Raises:

ValueError: If no filename is given and either outdir or label is None

If no bilby.core.result.Result is found in the path

classmethod from_json(filename=None, outdir=None, label=None, gzip=False)

Read in a saved .json data file

Parameters:

filename: str

If given, try to load from this filename

outdir, label: str

If given, use the default naming convention for saved results file

Returns:

result: bilby.core.result.Result

Raises:

ValueError: If no filename is given and either outdir or label is None

If no bilby.core.result.Result is found in the path

static from_pickle(filename=None, outdir=None, label=None)

Read in a saved .pickle data file

Parameters:

filename: str

If given, try to load from this filename

outdir, label: str

If given, use the default naming convention for saved results file

Returns:

result: bilby.core.result.Result

Raises:

ValueError: If no filename is given and either outdir or label is None

If no bilby.core.result.Result is found in the path

get_all_injection_credible_levels(keys=None, weights=None)

Get credible levels for all parameters

Parameters:

keys: list, optional

A list of keys for which return the credible levels, if None, defaults to search_parameter_keys

weights: array, optional

A list of weights for the posterior samples to calculate a set of weighted credible intervals. If None, assumes equal weights between samples.

Returns:

credible_levels: dict

The credible levels at which the injected parameters are found.

get_injection_credible_level(parameter, weights=None)

Get the credible level of the injected parameter

Calculated as CDF(injection value)

Parameters:

parameter: str

Parameter to get credible level for

weights: array, optional

A list of weights for the posterior samples to calculate a weighted credible interval. If None, assumes equal weights between samples.

Returns:

float: credible level

get_latex_labels_from_parameter_keys(keys)

Returns a list of latex_labels corresponding to the given keys

Parameters:

keys: list

List of strings corresponding to the desired latex_labels

Returns:

list: The desired latex_labels

get_one_dimensional_median_and_error_bar(key, fmt='.2f', quantiles=(0.16, 0.84))

Calculate the median and error bar for a given key

Parameters:

key: str

The parameter key for which to calculate the median and error bar

fmt: str, (‘.2f’)

A format string

quantiles: list, tuple

A length-2 tuple of the lower and upper-quantiles to calculate the errors bars for.

Returns:

summary: namedtuple

An object with attributes, median, lower, upper and string

get_weights_by_new_prior(old_prior, new_prior, prior_names=None)

Calculate a list of sample weights based on the ratio of new to old priors

Parameters:

old_prior: PriorDict,

The prior used in the generation of the original samples.

new_prior: PriorDict,

The prior to use to reweight the samples.

prior_names: list

A list of the priors to include in the ratio during reweighting.

Returns:

weights: array-like,

A list of sample weights.

property kde

Kernel density estimate built from the stored posterior

Uses scipy.stats.gaussian_kde to generate the kernel density

property nburn

“ An array of the ensemble walkers

property nested_samples

“ An array of unweighted samples

property num_likelihood_evaluations

number of likelihood evaluations

occam_factor(priors)

The Occam factor,

See Chapter 28, Mackay “Information Theory, Inference, and Learning Algorithms” Cambridge University Press (2003).

plot_corner(parameters=None, priors=None, titles=True, save=True, filename=None, dpi=300, **kwargs)

Plot a corner-plot

Parameters:

parameters: (list, dict), optional

If given, either a list of the parameter names to include, or a dictionary of parameter names and their “true” values to plot.

priors: {bool (False), bilby.core.prior.PriorDict}

If true, add the stored prior probability density functions to the one-dimensional marginal distributions. If instead a PriorDict is provided, this will be plotted.

titles: bool

If true, add 1D titles of the median and (by default 1-sigma) error bars. To change the error bars, pass in the quantiles kwarg. See method get_one_dimensional_median_and_error_bar for further details). If quantiles=None is passed in, no title is added.

save: bool, optional

If true, save the image using the given label and outdir

filename: str, optional

If given, overwrite the default filename

dpi: int, optional

Dots per inch resolution of the plot

**kwargs:

Other keyword arguments are passed to corner.corner. We set some defaults to improve the basic look and feel, but these can all be overridden. Also optional an ‘outdir’ argument which can be used to override the outdir set by the absolute path of the result object.

Returns:

fig:

A matplotlib figure instance

Notes

The generation of the corner plot themselves is done by the corner python module, see https://corner.readthedocs.io for more information.

Truth-lines can be passed in in several ways. Either as the values of the parameters dict, or a list via the truths kwarg. If injection_parameters where given to run_sampler, these will auto- matically be added to the plot. This behaviour can be stopped by adding truths=False.

plot_marginals(parameters=None, priors=None, titles=True, file_base_name=None, bins=50, label_fontsize=16, title_fontsize=16, quantiles=(0.16, 0.84), dpi=300, outdir=None)

Plot 1D marginal distributions

Parameters:

parameters: (list, dict), optional

If given, either a list of the parameter names to include, or a dictionary of parameter names and their “true” values to plot.

priors: {bool (False), bilby.core.prior.PriorDict}

If true, add the stored prior probability density functions to the one-dimensional marginal distributions. If instead a PriorDict is provided, this will be plotted.

titles: bool

If true, add 1D titles of the median and (by default 1-sigma) error bars. To change the error bars, pass in the quantiles kwarg. See method get_one_dimensional_median_and_error_bar for further details). If quantiles=None is passed in, no title is added.

file_base_name: str, optional

If given, the base file name to use (by default outdir/label_ is used)

bins: int

The number of histogram bins

label_fontsize, title_fontsize: int

The font sizes for the labels and titles

quantiles: tuple

A length-2 tuple of the lower and upper-quantiles to calculate the errors bars for.

dpi: int

Dots per inch resolution of the plot

outdir: str, optional

Path to the outdir. Default is the one store in the result object.

Returns:

plot_single_density(key, prior=None, cumulative=False, title=None, truth=None, save=True, file_base_name=None, bins=50, label_fontsize=16, title_fontsize=16, quantiles=(0.16, 0.84), dpi=300)

Plot a 1D marginal density, either probability or cumulative.

Parameters:

key: str

Name of the parameter to plot

prior: {bool (True), bilby.core.prior.Prior}

If true, add the stored prior probability density function to the one-dimensional marginal distributions. If instead a Prior is provided, this will be plotted.

cumulative: bool

If true plot the CDF

title: bool

If true, add 1D title of the median and (by default 1-sigma) error bars. To change the error bars, pass in the quantiles kwarg. See method get_one_dimensional_median_and_error_bar for further details). If quantiles=None is passed in, no title is added.

truth: {bool, float}

If true, plot self.injection_parameters[parameter]. If float, plot this value.

save: bool:

If true, save plot to disk.

file_base_name: str, optional

If given, the base file name to use (by default outdir/label_ is used)

bins: int

The number of histogram bins

label_fontsize, title_fontsize: int

The fontsizes for the labels and titles

quantiles: tuple

A length-2 tuple of the lower and upper-quantiles to calculate the errors bars for.

dpi: int

Dots per inch resolution of the plot

Returns:

figure: matplotlib.pyplot.figure

A matplotlib figure object

plot_walkers(**kwargs)

Method to plot the trace of the walkers in an ensemble MCMC plot

plot_with_data(model, x, y, ndraws=1000, npoints=1000, xlabel=None, ylabel=None, data_label='data', data_fmt='o', draws_label=None, filename=None, maxl_label='max likelihood', dpi=300, outdir=None)

Generate a figure showing the data and fits to the data

Parameters:

model: function

A python function which when called as model(x, **kwargs) returns the model prediction (here kwargs is a dictionary of key-value pairs of the model parameters.

x, y: np.ndarray

The independent and dependent data to plot

ndraws: int

Number of draws from the posterior to plot

npoints: int

Number of points used to plot the smoothed fit to the data

xlabel, ylabel: str

Labels for the axes

data_label, draws_label, maxl_label: str

Label for the data, draws, and max likelihood legend

data_fmt: str

Matpltolib fmt code, defaults to ‘-o’

dpi: int

Passed to plt.savefig

filename: str

If given, the filename to use. Otherwise, the filename is generated from the outdir and label attributes.

outdir: str, optional

Path to the outdir. Default is the one store in the result object.

property posterior

A pandas data frame of the posterior

posterior_probability(sample)

Calculate the posterior probability for a new sample

This queries a Kernel Density Estimate of the posterior to calculate the posterior probability density for the new sample.

Parameters:

sample: dict, or list of dictionaries

A dictionary containing all the keys from self.search_parameter_keys and corresponding values at which to calculate the posterior probability

Returns:

p: array-like,

The posterior probability of the sample

property posterior_volume

The posterior volume

static prior_volume(priors)

The prior volume, given a set of priors

property samples

An array of samples

samples_to_posterior(likelihood=None, priors=None, conversion_function=None, npool=1)

Convert array of samples to posterior (a Pandas data frame)

Also applies the conversion function to any stored posterior

Parameters:

likelihood: bilby.likelihood.GravitationalWaveTransient, optional

GravitationalWaveTransient likelihood used for sampling.

priors: bilby.prior.PriorDict, optional

Dictionary of prior object, used to fill in delta function priors.

conversion_function: function, optional

Function which adds in extra parameters to the data frame, should take the data_frame, likelihood and prior as arguments.

save_posterior_samples(filename=None, outdir=None, label=None)

Saves posterior samples to a file

Generates a .dat file containing the posterior samples and auxiliary data saved in the posterior. Note, strings in the posterior are removed while complex numbers will be given as absolute values with abs appended to the column name

Parameters:

filename: str

Alternative filename to use. Defaults to outdir/label_posterior_samples.dat

outdir, label: str

Alternative outdir and label to use

save_to_file(filename=None, overwrite=False, outdir=None, extension='json', gzip=False)

Writes the Result to a file.

Supported formats are: json, hdf5, pickle

Parameters:

filename: optional,

Filename to write to (overwrites the default)

overwrite: bool, optional

Whether or not to overwrite an existing result file. default=False

outdir: str, optional

Path to the outdir. Default is the one stored in the result object. If given, overwrite path prefix in ‘filename’.

extension: str, optional {json, hdf5, pkl, pickle, True}

Determines the method to use to store the data (if True defaults to json)

gzip: bool, optional

If true, and outputting to a json file, this will gzip the resulting file and add ‘.gz’ to the file extension.

to_arviz(prior=None)

Convert the Result object to an ArviZ InferenceData object.

Parameters:

prior: int

If a positive integer is given then that number of prior samples will be drawn and stored in the ArviZ InferenceData object.

Returns:

azdata: InferenceData

The ArviZ InferenceData object.

Raises:

RuntimeError: If ArviZ is not installed.

property walkers

“ An array of the ensemble walkers