bilby.gw.result.CompactBinaryCoalescenceResult

class bilby.gw.result.CompactBinaryCoalescenceResult(**kwargs)

Bases: Result

Result class with additional methods and attributes specific to analyses of compact binaries.

__init__(**kwargs)

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__(**kwargs)	A class to store the results of the sampling run
calculate_prior_values(priors)	Evaluate prior probability for each parameter for each sample.
detector_injection_properties(detector)	Returns a dictionary of the injection properties for each detector
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_calibration_posterior([level, format])	Plots the calibration amplitude and phase uncertainty.
plot_corner([parameters, priors, titles, ...])	Plot a corner-plot
plot_interferometer_waveform_posterior(...)	Plot the posterior for the waveform in the frequency domain and whitened time domain.
plot_marginals([parameters, priors, titles, ...])	Plot 1D marginal distributions
plot_single_density(key[, prior, ...])	Plot a 1D marginal density, either probability or cumulative.
plot_skymap([maxpts, trials, jobs, ...])	Generate a fits file and sky map from a result
plot_walkers(**kwargs)	Method to plot the trace of the walkers in an ensemble MCMC plot
plot_waveform_posterior([interferometers, ...])	Plot the posterior for the waveform in the frequency domain and whitened time domain for all detectors.
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
distance_marginalization	Boolean for if the likelihood used distance marginalization
duration	Duration in seconds
frequency_domain_source_model	The frequency domain source model (function)
interferometers	List of interferometer names
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
parameter_conversion	The frequency domain source model (function)
phase_marginalization	Boolean for if the likelihood used phase marginalization
posterior	A pandas data frame of the posterior
posterior_volume	The posterior volume
priors
reference_frequency	Float of the reference frequency
samples	An array of samples
sampling_frequency	Sampling frequency in Hertz
start_time	Start time in seconds
time_domain_source_model	The time domain source model (function)
time_marginalization	Boolean for if the likelihood used time marginalization
version
walkers	" An array of the ensemble walkers
waveform_approximant	String of the waveform approximant
waveform_arguments	Dict of waveform arguments
waveform_generator_class	Dict of waveform arguments

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

detector_injection_properties(detector)

Returns a dictionary of the injection properties for each detector

The injection properties include the parameters injected, and information about the signal to noise ratio (SNR) given the noise properties.

Parameters:

detector: str [H1, L1, V1]

Detector name

Returns:

injection_properties: dict

A dictionary of the injection properties

property distance_marginalization

Boolean for if the likelihood used distance marginalization

property duration

Duration in seconds

property frequency_domain_source_model

The frequency domain source model (function)

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 interferometers

List of interferometer names

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).

property parameter_conversion

The frequency domain source model (function)

property phase_marginalization

Boolean for if the likelihood used phase marginalization

plot_calibration_posterior(level=0.9, format='png')

Plots the calibration amplitude and phase uncertainty. Adapted from the LALInference version in bayespputils

Plot is saved to {self.outdir}/{self.label}_calibration.{format}

Parameters:

level: float

Quantile for confidence levels, default=0.9, i.e., 90% interval

format: str

Format to save the plot, default=png, options are png/pdf

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_interferometer_waveform_posterior(interferometer, level=0.9, n_samples=None, save=True, format='png', start_time=None, end_time=None)

Plot the posterior for the waveform in the frequency domain and whitened time domain.

If the strain data is passed that will be plotted.

If injection parameters can be found, the injection will be plotted.

Parameters:

interferometer: (str, bilby.gw.detector.interferometer.Interferometer)

detector to use, if an Interferometer object is passed the data will be overlaid on the posterior

level: float, optional

symmetric confidence interval to show, default is 90%

n_samples: int, optional

number of samples to use to calculate the median/interval default is all

save: bool, optional

whether to save the image, default=True if False, figure handle is returned

format: str, optional

format to save the figure in, default is png

start_time: float, optional

the amount of time before merger to begin the time domain plot. the merger time is defined as the mean of the geocenter time posterior. Default is - 0.4

end_time: float, optional

the amount of time before merger to end the time domain plot. the merger time is defined as the mean of the geocenter time posterior. Default is 0.2

Returns:

fig: figure-handle, only is save=False

Notes

To reduce the memory footprint we decimate the frequency domain waveforms to have ~4000 entries. This should be sufficient for decent resolution.

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_skymap(maxpts=None, trials=5, jobs=1, enable_multiresolution=True, objid=None, instruments=None, geo=False, dpi=600, transparent=False, colorbar=False, contour=[50, 90], annotate=True, cmap='cylon', load_pickle=False)

Generate a fits file and sky map from a result

Code adapted from ligo.skymap.tool.ligo_skymap_from_samples and ligo.skymap.tool.plot_skymap. Note, the use of this additionally required the installation of ligo.skymap.

Parameters:

maxpts: int

Maximum number of samples to use, if None all samples are used

trials: int

Number of trials at each clustering number

jobs: int

Number of multiple threads

enable_multiresolution: bool

Generate a multiresolution HEALPix map (default: True)

objid: str

Event ID to store in FITS header

instruments: str

Name of detectors

geo: bool

Plot in geographic coordinates (lat, lon) instead of RA, Dec

dpi: int

Resolution of figure in fots per inch

transparent: bool

Save image with transparent background

colorbar: bool

Show colorbar

contour: list

List of contour levels to use

annotate: bool

Annotate image with details

cmap: str

Name of the colormap to use

load_pickle: bool, str

If true, load the cached pickle file (default name), or the pickle-file give as a path.

plot_walkers(**kwargs)

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

plot_waveform_posterior(interferometers=None, level=0.9, n_samples=None, format='png', start_time=None, end_time=None)

Plot the posterior for the waveform in the frequency domain and whitened time domain for all detectors.

If the strain data is passed that will be plotted.

If injection parameters can be found, the injection will be plotted.

Parameters:

interferometers: (list, bilby.gw.detector.InterferometerList, optional)

level: float, optional

symmetric confidence interval to show, default is 90%

n_samples: int, optional

number of samples to use to calculate the median/interval default is all

format: str, optional

format to save the figure in, default is png

start_time: float, optional

the amount of time before merger to begin the time domain plot. the merger time is defined as the mean of the geocenter time posterior. Default is - 0.4

end_time: float, optional

the amount of time before merger to end the time domain plot. the merger time is defined as the mean of the geocenter time posterior. Default is 0.2

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 reference_frequency

Float of the reference frequency

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.

property sampling_frequency

Sampling frequency in Hertz

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.

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.

property start_time

Start time in seconds

property time_domain_source_model

The time domain source model (function)

property time_marginalization

Boolean for if the likelihood used time marginalization

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.

property walkers

“ An array of the ensemble walkers

property waveform_approximant

String of the waveform approximant

property waveform_arguments

Dict of waveform arguments

property waveform_generator_class

Dict of waveform arguments