pycbc.inference.io package

Submodules

pycbc.inference.io.base_hdf module

This modules defines functions for reading and writing samples that the inference samplers generate.

class pycbc.inference.io.base_hdf.BaseInferenceFile(path, mode=None, **kwargs)

Bases: h5py._hl.files.File

Base class for all inference hdf files.

This is a subclass of the h5py.File object. It adds functions for handling reading and writing the samples from the samplers.

Parameters:

• path (str) – The path to the HDF file.
• mode ({None, str}) – The mode to open the file, eg. “w” for write and “r” for read.

cmd

Returns the (last) saved command line.

If the file was created from a run that resumed from a checkpoint, only the last command line used is returned.

Returns:cmd – The command line that created this InferenceFile. Return type:string

copy(other, ignore=None, parameters=None, parameter_names=None, read_args=None, write_args=None)

Copies metadata, info, and samples in this file to another file.

Parameters:

• other (str or InferenceFile) – The file to write to. May be either a string giving a filename, or an open hdf file. If the former, the file will be opened with the write attribute (note that if a file already exists with that name, it will be deleted).
• ignore ((list of) strings) – Don’t copy the given groups. If the samples group is included, no samples will be copied.
• parameters (list of str, optional) – List of parameters in the samples group to copy. If None, will copy all parameters.
• parameter_names (dict, optional) – Rename one or more parameters to the given name. The dictionary should map parameter -> parameter name. If None, will just use the original parameter names.
• read_args (dict, optional) – Arguments to pass to read_samples.
• write_args (dict, optional) – Arguments to pass to write_samples.

Returns:

The open file handler to other.

Return type:

InferenceFile

copy_info(other, ignore=None)

Copies “info” from this file to the other.

“Info” is defined all groups that are not the samples group.

Parameters:

• other (output file) – The output file. Must be an hdf file.
• ignore ((list of) str) – Don’t copy the given groups.

copy_metadata(other)

Copies all metadata from this file to the other file.

Metadata is defined as everything in the top-level .attrs.

Parameters:other (InferenceFile) – An open inference file to write the data to.

copy_samples(other, parameters=None, parameter_names=None, read_args=None, write_args=None)

Should copy samples to the other files.

Parameters:

• other (InferenceFile) – An open inference file to write to.
• parameters (list of str, optional) – List of parameters to copy. If None, will copy all parameters.
• parameter_names (dict, optional) – Rename one or more parameters to the given name. The dictionary should map parameter -> parameter name. If None, will just use the original parameter names.
• read_args (dict, optional) – Arguments to pass to read_samples.
• write_args (dict, optional) – Arguments to pass to write_samples.

data_group = 'data'

effective_nsamples

Returns the effective number of samples stored in the file.

static extra_args_parser(parser=None, skip_args=None, **kwargs)

Provides a parser that can be used to parse sampler-specific command line options for loading samples.

This is optional. Inheriting classes may override this if they want to implement their own options.

Parameters:

• parser (argparse.ArgumentParser, optional) – Instead of creating a parser, add arguments to the given one. If none provided, will create one.
• skip_args (list, optional) – Don’t include the given options. Options should be given as the option string, minus the ‘–’. For example, skip_args=['iteration'] would cause the --iteration argument not to be included.
• **kwargs – All other keyword arguments are passed to the parser that is created.

Returns:

• parser (argparse.ArgumentParser or None) – If this class adds extra arguments, an argument parser with the extra arguments. Otherwise, will just return whatever was passed for the parser argument (default is None).
• actions (list of argparse.Action) – List of the actions that were added.

get_slice(thin_start=None, thin_interval=None, thin_end=None)

Formats a slice using the given arguments that can be used to retrieve a thinned array from an InferenceFile.

Parameters:

• thin_start (int, optional) – The starting index to use. If None, will use the thin_start attribute.
• thin_interval (int, optional) – The interval to use. If None, will use the thin_interval attribute.
• thin_end (int, optional) – The end index to use. If None, will use the thin_end attribute.

Returns:

The slice needed.

Return type:

slice

injections_group = 'injections'

log_evidence

Returns the log of the evidence and its error, if they exist in the file. Raises a KeyError otherwise.

name = None

parse_parameters(parameters, array_class=None)

Parses a parameters arg to figure out what fields need to be loaded.

Parameters:

• parameters ((list of) strings) – The parameter(s) to retrieve. A parameter can be the name of any field in samples_group, a virtual field or method of FieldArray (as long as the file contains the necessary fields to derive the virtual field or method), and/or a function of these.
• array_class (array class, optional) – The type of array to use to parse the parameters. The class must have a parse_parameters method. Default is to use a FieldArray.

Returns:

A list of strings giving the fields to load from the file.

Return type:

list

read_injections()

Gets injection parameters.

Returns:Array of the injection parameters. Return type:FieldArray

read_random_state(group=None)

Reads the state of the random number generator from the file.

Parameters:group (str) – Name of group to read random state from. Returns:A tuple with 5 elements that can be passed to numpy.set_state. Return type:tuple

read_raw_samples(fields, **kwargs)

Low level function for reading datasets in the samples group.

This should return a dictionary of numpy arrays.

read_samples(parameters, array_class=None, **kwargs)

Reads samples for the given parameter(s).

The parameters can be the name of any dataset in samples_group, a virtual field or method of FieldArray (as long as the file contains the necessary fields to derive the virtual field or method), and/or any numpy function of these.

The parameters are parsed to figure out what datasets are needed. Only those datasets will be loaded, and will be the base-level fields of the returned FieldArray.

The static_params are also added as attributes of the returned FieldArray.

Parameters:

• parameters ((list of) strings) – The parameter(s) to retrieve.
• array_class (FieldArray-like class, optional) – The type of array to return. The class must have from_kwargs and parse_parameters methods. If None, will return a FieldArray.
• **kwargs – All other keyword arguments are passed to read_raw_samples.

Returns:

The samples as a FieldArray.

Return type:

FieldArray

sampler_group = 'sampler_info'

samples_from_cli(opts, parameters=None, **kwargs)

Reads samples from the given command-line options.

Parameters:

• opts (argparse Namespace) – The options with the settings to use for loading samples (the sort of thing returned by ArgumentParser().parse_args).
• parameters ((list of) str, optional) – A list of the parameters to load. If none provided, will try to get the parameters to load from opts.parameters.
• **kwargs – All other keyword arguments are passed to read_samples. These will override any options with the same name.

Returns:

Array of the loaded samples.

Return type:

FieldArray

samples_group = 'samples'

static_params

Returns a dictionary of the static_params. The keys are the argument names, values are the value they were set to.

thin_end

The defaut end index to use when reading samples.

This tries to read from thin_end in the attrs. If it isn’t there, just returns None.

thin_interval

The default interval to use when reading samples.

This tries to read from thin_interval in the attrs. If it isn’t there, just returns 1.

thin_start

The default start index to use when reading samples.

This tries to read from thin_start in the attrs. If it isn’t there, just returns 0.

write_command_line()

Writes command line to attributes.

The command line is written to the file’s attrs['cmd']. If this attribute already exists in the file (this can happen when resuming from a checkpoint), attrs['cmd'] will be a list storing the current command line and all previous command lines.

write_effective_nsamples(effective_nsamples)

Writes the effective number of samples stored in the file.

write_injections(injection_file)

Writes injection parameters from the given injection file.

Everything in the injection file is copied to injections_group.

Parameters:injection_file (str) – Path to HDF injection file.

classmethod write_kwargs_to_attrs(attrs, **kwargs)

Writes the given keywords to the given attrs.

If any keyword argument points to a dict, the keyword will point to a list of the dict’s keys. Each key is then written to the attrs with its corresponding value.

Parameters:

• attrs (an HDF attrs) – The attrs of an hdf file or a group in an hdf file.
• **kwargs – The keywords to write.

write_logevidence(lnz, dlnz)

Writes the given log evidence and its error.

Results are saved to file’s ‘log_evidence’ and ‘dlog_evidence’ attributes.

Parameters:

• lnz (float) – The log of the evidence.
• dlnz (float) – The error in the estimate of the log evidence.

write_psd(psds, group=None)

Writes PSD for each IFO to file.

Parameters:

• psds ({dict, FrequencySeries}) – A dict of FrequencySeries where the key is the IFO.
• group ({None, str}) – The group to write the psd to. Default is data_group.

write_random_state(group=None, state=None)

Writes the state of the random number generator from the file.

The random state is written to sampler_group/random_state.

Parameters:

• group (str) – Name of group to write random state to.
• state (tuple, optional) – Specify the random state to write. If None, will use numpy.random.get_state().

write_samples(samples, **kwargs)

This should write all of the provided samples.

This function should be used to write both samples and model stats.

Parameters:

• samples (dict) – Samples should be provided as a dictionary of numpy arrays.
• **kwargs – Any other keyword args the sampler needs to write data.

write_stilde(stilde_dict, group=None)

Writes stilde for each IFO to file.

Parameters:

• stilde ({dict, FrequencySeries}) – A dict of FrequencySeries where the key is the IFO.
• group ({None, str}) – The group to write the strain to. If None, will write to the top level.

write_strain(strain_dict, group=None)

Writes strain for each IFO to file.

Parameters:

• strain ({dict, FrequencySeries}) – A dict of FrequencySeries where the key is the IFO.
• group ({None, str}) – The group to write the strain to. If None, will write to the top level.

pycbc.inference.io.base_hdf.format_attr(val)

Formats an attr so that it can be read in either python 2 or 3.

In python 2, strings that are saved as an attribute in an hdf file default to unicode. Since unicode was removed in python 3, if you load that file in a python 3 environment, the strings will be read as bytes instead, which causes a number of issues. This attempts to fix that. If the value is a bytes string, then it will be decoded into a string. If the value is a numpy array of byte strings, it will convert the array to a list of strings.

Parameters:val (obj) – The value to format. This will try to apply decoding to the value Returns:If val was a byte string, the value as a str. If the value was a numpy array of bytes_, the value as a list of str. Otherwise, just returns the value. Return type:obj

pycbc.inference.io.base_mcmc module

Provides I/O that is specific to MCMC samplers.

class pycbc.inference.io.base_mcmc.MCMCMetadataIO

Bases: object

Provides functions for reading/writing MCMC metadata to file.

static extra_args_parser(parser=None, skip_args=None, **kwargs)

Create a parser to parse sampler-specific arguments for loading samples.

Parameters:

• parser (argparse.ArgumentParser, optional) – Instead of creating a parser, add arguments to the given one. If none provided, will create one.
• skip_args (list, optional) – Don’t parse the given options. Options should be given as the option string, minus the ‘–’. For example, skip_args=['iteration'] would cause the --iteration argument not to be included.
• **kwargs – All other keyword arguments are passed to the parser that is created.

Returns:

• parser (argparse.ArgumentParser) – An argument parser with th extra arguments added.
• actions (list of argparse.Action) – A list of the actions that were added.

iterations(parameter)

Returns the iteration each sample occurred at.

last_iteration(parameter=None, group=None)

Returns the iteration of the last sample of the given parameter.

Parameters:

• parameter (str, optional) – The name of the parameter to get the last iteration for. If None provided, will just use the first parameter in group.
• group (str, optional) – The name of the group to get the last iteration from. Default is the samples_group.

niterations

Returns the number of iterations the sampler was run for.

nwalkers

Returns the number of walkers used by the sampler.

read_acls()

Reads the acls of all the parameters.

Returns:A dictionary of the ACLs, keyed by the parameter name. Return type:dict

thin(thin_interval)

Thins the samples on disk to the given thinning interval.

The interval must be a multiple of the file’s current thinned_by.

Parameters:thin_interval (int) – The interval the samples on disk should be thinned by.

thinned_by

Returns interval samples have been thinned by on disk.

This looks for thinned_by in the samples group attrs. If none is found, will just return 1.

write_acls(acls)

Writes the given autocorrelation lengths.

The ACL of each parameter is saved to [sampler_group]/acls/{param}']. The maximum over all the parameters is saved to the file’s ‘acl’ attribute.

Parameters:acls (dict) – A dictionary of ACLs keyed by the parameter. Returns:The maximum of the acls that was written to the file. Return type:ACL

write_burn_in(burn_in)

Write the given burn-in data to the given filename.

write_niterations(niterations)

Writes the given number of iterations to the sampler group.

write_resume_point()

Keeps a list of the number of iterations that were in a file when a run was resumed from a checkpoint.

write_sampler_metadata(sampler)

Writes the sampler’s metadata.

class pycbc.inference.io.base_mcmc.SingleTempMCMCIO

Bases: object

Provides functions for reading/writing samples from an MCMC sampler.

These functions will work for samplers that have 1 or more walkers, with only a single temperature.

read_raw_samples(fields, thin_start=None, thin_interval=None, thin_end=None, iteration=None, walkers=None, flatten=True, group=None)

Base function for reading samples.

Parameters:

• fields (list) – The list of field names to retrieve.
• thin_start (int, optional) – Start reading from the given iteration. Default is to start from the first iteration.
• thin_interval (int, optional) – Only read every thin_interval -th sample. Default is 1.
• thin_end (int, optional) – Stop reading at the given iteration. Default is to end at the last iteration.
• iteration (int, optional) – Only read the given iteration. If this provided, it overrides the thin_(start|interval|end) options.
• walkers (int, optional) – Only read from the given walkers. Default is to read all.
• flatten (bool, optional) – Flatten the samples to 1D arrays before returning. Otherwise, the returned arrays will have shape (requested walkers x requested iteration(s)). Default is True.
• group (str, optional) – The name of the group to read sample datasets from. Default is the file’s samples_group.

Returns:

A dictionary of field name -> numpy array pairs.

Return type:

dict

write_samples(samples, parameters=None, last_iteration=None, samples_group=None, thin_by=None)

Writes samples to the given file.

Results are written to samples_group/{vararg}, where {vararg} is the name of a model params. The samples are written as an nwalkers x niterations array. If samples already exist, the new samples are appended to the current.

If the current samples on disk have been thinned (determined by the thinned_by attribute in the samples group), then the samples will be thinned by the same amount before being written. The thinning is started at the sample in samples that occured at the iteration equal to the last iteration on disk plus the thinned_by interval. If this iteration is larger than the iteration of the last given sample, then none of the samples will be written.

Parameters:

• samples (dict) – The samples to write. Each array in the dictionary should have shape nwalkers x niterations.
• parameters (list, optional) – Only write the specified parameters to the file. If None, will write all of the keys in the samples dict.
• last_iteration (int, optional) – The iteration of the last sample. If the file’s thinned_by attribute is > 1, this is needed to determine where to start thinning the samples such that the interval between the last sample currently on disk and the first new sample is the same as all of the other samples.
• samples_group (str, optional) – Which group to write the samples to. Default (None) will result in writing to “samples”.
• thin_by (int, optional) – Override the thinned_by attribute in the file with the given value. Only set this if you are using this function to write something other than inference samples!

pycbc.inference.io.base_mcmc.thin_samples_for_writing(fp, samples, parameters, last_iteration, group, thin_by=None)

Thins samples for writing to disk.

The thinning interval to use is determined by the given file handler’s thinned_by attribute. If that attribute is 1, just returns the samples.

Parameters:

• fp (MCMCMetadataIO instance) – The file the sampels will be written to. Needed to determine the thin interval used on disk.
• samples (dict) – Dictionary mapping parameter names to arrays of (unthinned) samples. The arrays are thinned along their last dimension.
• parameters (list of str) – The parameters to thin in samples before writing. All listed parameters must be in samples.
• last_iteration (int) – The iteration that the last sample in samples occurred at. This is needed to figure out where to start the thinning in samples, such that the interval between the last sample on disk and the first new sample is the same as all of the other samples.
• group (str) – The name of the group that the samples will be written to. This is needed to determine what the last iteration saved on disk was.
• thin_by (int, optional) – Override the thinned_by attribute in the file for with the given value. Only do this if you are thinning something other than inference samples!

Returns:

Dictionary of the thinned samples to write.

Return type:

dict

pycbc.inference.io.base_multitemper module

Provides I/O support for multi-tempered sampler.

class pycbc.inference.io.base_multitemper.MultiTemperedMCMCIO

Bases: object

Provides functions for reading/writing samples from a parallel-tempered MCMC sampler.

read_raw_samples(fields, thin_start=None, thin_interval=None, thin_end=None, iteration=None, temps='all', walkers=None, flatten=True, group=None)

Base function for reading samples.

Parameters:

• fields (list) – The list of field names to retrieve.
• thin_start (int, optional) – Start reading from the given iteration. Default is to start from the first iteration.
• thin_interval (int, optional) – Only read every thin_interval -th sample. Default is 1.
• thin_end (int, optional) – Stop reading at the given iteration. Default is to end at the last iteration.
• iteration (int, optional) – Only read the given iteration. If this provided, it overrides the thin_(start|interval|end) options.
• temps ('all' or (list of) int, optional) – The temperature index (or list of indices) to retrieve. To retrieve all temperates pass ‘all’, or a list of all of the temperatures. Default is ‘all’.
• walkers ((list of) int, optional) – Only read from the given walkers. Default is to read all.
• flatten (bool, optional) – Flatten the samples to 1D arrays before returning. Otherwise, the returned arrays will have shape (requested temps x requested walkers x requested iteration(s)). Default is True.
• group (str, optional) – The name of the group to read sample datasets from. Default is the file’s samples_group.

Returns:

An instance of the given array class populated with values retrieved from the fields.

Return type:

array_class

write_samples(samples, parameters=None, last_iteration=None, samples_group=None, thin_by=None)

Writes samples to the given file.

Results are written to samples_group/{vararg}, where {vararg} is the name of a model params. The samples are written as an ntemps x nwalkers x niterations array.

Parameters:

• samples (dict) – The samples to write. Each array in the dictionary should have shape ntemps x nwalkers x niterations.
• parameters (list, optional) – Only write the specified parameters to the file. If None, will write all of the keys in the samples dict.
• last_iteration (int, optional) – The iteration of the last sample. If the file’s thinned_by attribute is > 1, this is needed to determine where to start thinning the samples to match what has already been stored on disk.
• samples_group (str, optional) – Which group to write the samples to. Default (None) will result in writing to “samples”.
• thin_by (int, optional) – Override the thinned_by attribute in the file with the given value. Only set this if you are using this function to write something other than inference samples!

class pycbc.inference.io.base_multitemper.MultiTemperedMetadataIO

Bases: pycbc.inference.io.base_mcmc.MCMCMetadataIO

Adds support for reading/writing multi-tempered metadata to MCMCMetadatIO.

static extra_args_parser(parser=None, skip_args=None, **kwargs)

Adds –temps to MCMCIO parser.

ntemps

Returns the number of temperatures used by the sampler.

write_sampler_metadata(sampler)

Adds writing ntemps to file.

class pycbc.inference.io.base_multitemper.ParseTempsArg(type=<type 'str'>, **kwargs)

Bases: argparse.Action

Argparse action that will parse temps argument.

If the provided argument is ‘all’, sets ‘all’ in the namespace dest. If a a sequence of numbers are provided, converts those numbers to ints before saving to the namespace.

pycbc.inference.io.base_nested_sampler module

Provides IO for the dynesty sampler.

class pycbc.inference.io.base_nested_sampler.BaseNestedSamplerFile(path, mode=None, **kwargs)

Bases: pycbc.inference.io.base_sampler.BaseSamplerFile

Class to handle file IO for the nested samplers cpnest and dynesty.

name = 'base_nest_file'

read_raw_samples(fields, **kwargs)

Low level function for reading datasets in the samples group.

This should return a dictionary of numpy arrays.

write_niterations(niterations)

Writes the given number of iterations to the sampler group.

write_resume_point()

Should write the point that a sampler starts up.

How the resume point is indexed is up to the sampler. For example, MCMC samplers use the number of iterations that are stored in the checkpoint file.

write_sampler_metadata(sampler)

Adds writing betas to MultiTemperedMCMCIO.

write_samples(samples, parameters=None)

Writes samples to the given file.

Results are written to samples_group/{vararg}, where {vararg} is the name of a model params. The samples are written as an array of length niterations.

Parameters:

• samples (dict) – The samples to write. Each array in the dictionary should have length niterations.
• parameters (list, optional) – Only write the specified parameters to the file. If None, will write all of the keys in the samples dict.

pycbc.inference.io.base_sampler module

Provides abstract base class for all samplers.

class pycbc.inference.io.base_sampler.BaseSamplerFile(path, mode=None, **kwargs)

Bases: pycbc.inference.io.base_hdf.BaseInferenceFile

Base HDF class for all samplers.

This adds abstract methods write_resume_point and write_sampler_metadata to BaseInferenceFile.

validate()

Runs a validation test.

This checks that a samples group exist, and that there are more than one sample stored to it.

Returns:Whether or not the file is valid as a checkpoint file. Return type:bool

write_resume_point()

Should write the point that a sampler starts up.

How the resume point is indexed is up to the sampler. For example, MCMC samplers use the number of iterations that are stored in the checkpoint file.

write_sampler_metadata(sampler)

This should write the given sampler’s metadata to the file.

This should also include the model’s metadata.

pycbc.inference.io.dynesty module

Provides IO for the dynesty sampler.

class pycbc.inference.io.dynesty.DynestyFile(path, mode=None, **kwargs)

Bases: pycbc.inference.io.base_nested_sampler.BaseNestedSamplerFile

Class to handle file IO for the dynesty sampler.

name = 'dynesty_file'

pycbc.inference.io.emcee module

Provides IO for the emcee sampler.

class pycbc.inference.io.emcee.EmceeFile(path, mode=None, **kwargs)

Bases: pycbc.inference.io.base_mcmc.SingleTempMCMCIO, pycbc.inference.io.base_mcmc.MCMCMetadataIO, pycbc.inference.io.base_sampler.BaseSamplerFile

Class to handle file IO for the emcee sampler.

name = 'emcee_file'

read_acceptance_fraction(walkers=None)

Reads the acceptance fraction.

Parameters:walkers ((list of) int, optional) – The walker index (or a list of indices) to retrieve. If None, samples from all walkers will be obtained. Returns:Array of acceptance fractions with shape (requested walkers,). Return type:array

write_acceptance_fraction(acceptance_fraction)

Write acceptance_fraction data to file. Results are written to the [sampler_group]/acceptance_fraction.

Parameters:acceptance_fraction (numpy.ndarray) – Array of acceptance fractions to write.

pycbc.inference.io.emcee_pt module

Provides I/O support for emcee_pt.

class pycbc.inference.io.emcee_pt.EmceePTFile(path, mode=None, **kwargs)

Bases: pycbc.inference.io.base_multitemper.MultiTemperedMCMCIO, pycbc.inference.io.base_multitemper.MultiTemperedMetadataIO, pycbc.inference.io.base_sampler.BaseSamplerFile

Class to handle file IO for the emcee sampler.

betas

The betas that were used.

name = 'emcee_pt_file'

read_acceptance_fraction(temps=None, walkers=None)

Reads the acceptance fraction.

Parameters:

• temps ((list of) int, optional) – The temperature index (or a list of indices) to retrieve. If None, acfs from all temperatures and all walkers will be retrieved.
• walkers ((list of) int, optional) – The walker index (or a list of indices) to retrieve. If None, samples from all walkers will be obtained.

Returns:

Array of acceptance fractions with shape (requested temps, requested walkers).

Return type:

array

write_acceptance_fraction(acceptance_fraction)

Write acceptance_fraction data to file.

Results are written to [sampler_group]/acceptance_fraction; the resulting dataset has shape (ntemps, nwalkers).

Parameters:acceptance_fraction (numpy.ndarray) – Array of acceptance fractions to write. Must have shape ntemps x nwalkers.

write_sampler_metadata(sampler)

Adds writing betas to MultiTemperedMCMCIO.

pycbc.inference.io.epsie module

This module provides IO classes for epsie samplers.

class pycbc.inference.io.epsie.EpsieFile(path, mode=None, **kwargs)

Bases: pycbc.inference.io.base_multitemper.MultiTemperedMCMCIO, pycbc.inference.io.base_multitemper.MultiTemperedMetadataIO, pycbc.inference.io.base_sampler.BaseSamplerFile

Class to handle IO for Epsie’s parallel-tempered sampler.

betas

The betas that were used.

name = 'epsie_file'

swap_interval

The interval that temperature swaps occurred at.

thin(thin_interval)

Thins the samples on disk to the given thinning interval.

Also thins the acceptance ratio and the temperature data, both of which are stored in the sampler_info group.

validate()

Adds attemp to load checkpoint to validation test.

write_acceptance_ratio(acceptance_ratio, last_iteration=None)

Writes the acceptance ratios to the sampler info group.

Parameters:acceptance_ratio (array) – The acceptance ratios to write. Should have shape ntemps x nchains x niterations.

write_sampler_metadata(sampler)

Adds writing seed and betas to MultiTemperedMCMCIO.

write_temperature_data(swap_index, acceptance_ratio, swap_interval, last_iteration)

Writes temperature swaps and acceptance ratios.

Parameters:

• swap_index (array) – The indices indicating which temperatures were swapped. Should have shape ntemps x nchains x (niterations/swap_interval).
• acceptance_ratio (array) – The array of acceptance ratios between temperatures. Should have shape (ntemps-1) x nchains x (niterations/swap_interval). arrays.
• swap_interval (int) – The number of iterations between temperature swaps.
• last_iteration (int) – The iteration of the last sample.

pycbc.inference.io.multinest module

Provides I/O support for multinest.

class pycbc.inference.io.multinest.MultinestFile(path, mode=None, **kwargs)

Bases: pycbc.inference.io.base_sampler.BaseSamplerFile

Class to handle file IO for the multinest sampler.

name = 'multinest_file'

niterations

Returns the number of iterations the sampler was run for.

read_raw_samples(fields, iteration=None)

Low level function for reading datasets in the samples group.

This should return a dictionary of numpy arrays.

write_logevidence(lnz, dlnz, importance_lnz, importance_dlnz)

Writes the given log evidence and its error.

Results are saved to file’s ‘log_evidence’ and ‘dlog_evidence’ attributes, as well as the importance-weighted versions of these stats if they exist.

Parameters:

• lnz (float) – The log of the evidence.
• dlnz (float) – The error in the estimate of the log evidence.
• importance_lnz (float, optional) – The importance-weighted log of the evidence.
• importance_dlnz (float, optional) – The error in the importance-weighted estimate of the log evidence.

write_niterations(niterations)

Writes the given number of iterations to the sampler group.

write_resume_point()

Keeps a list of the number of iterations that were in a file when a run was resumed from a checkpoint.

write_sampler_metadata(sampler)

Writes the sampler’s metadata.

write_samples(samples, parameters=None)

Writes samples to the given file.

Results are written to samples_group/{vararg}, where {vararg} is the name of a model params. The samples are written as an array of length niterations.

Parameters:

• samples (dict) – The samples to write. Each array in the dictionary should have length niterations.
• parameters (list, optional) – Only write the specified parameters to the file. If None, will write all of the keys in the samples dict.

pycbc.inference.io.posterior module

Provides simplified standard format just for posterior data

class pycbc.inference.io.posterior.PosteriorFile(path, mode=None, **kwargs)

Bases: pycbc.inference.io.base_hdf.BaseInferenceFile

Class to handle file IO for the simplified Posterior file.

name = 'posterior_file'

read_raw_samples(fields, **kwargs)

Low level function for reading datasets in the samples group.

This should return a dictionary of numpy arrays.

write_samples(samples, parameters=None)

This should write all of the provided samples.

This function should be used to write both samples and model stats.

Parameters:

• samples (dict) – Samples should be provided as a dictionary of numpy arrays.
• **kwargs – Any other keyword args the sampler needs to write data.

pycbc.inference.io.posterior.read_raw_samples_from_file(fp, fields, **kwargs)

pycbc.inference.io.posterior.write_samples_to_file(fp, samples, parameters=None)

Writes samples to the given file.

Results are written to samples_group/{vararg}, where {vararg} is the name of a model params. The samples are written as an array of length niterations.

Parameters:

• fp (self) – Pass the ‘self’ from BaseInferenceFile class.
• samples (dict) – The samples to write. Each array in the dictionary should have length niterations.
• parameters (list, optional) – Only write the specified parameters to the file. If None, will write all of the keys in the samples dict.

pycbc.inference.io.txt module

This modules defines functions for reading and samples that the inference samplers generate and are stored in an ASCII TXT file.

class pycbc.inference.io.txt.InferenceTXTFile(path, mode=None, delimiter=None)

Bases: object

A class that has extra functions for handling reading the samples from posterior-only TXT files.

Parameters:

• path (str) – The path to the TXT file.
• mode ({None, str}) – The mode to open the file. Only accepts “r” or “rb” for reading.
• delimiter (str) – Delimiter to use for TXT file. Default is space-delimited.

comments = ''

delimiter = ' '

name = 'txt'

classmethod write(output_file, samples, labels, delimiter=None)

Writes a text file with samples.

Parameters:

• output_file (str) – The path of the file to write.
• samples (FieldArray) – Samples to write to file.
• labels (list) – A list of strings to include as header in TXT file.
• delimiter (str) – Delimiter to use in TXT file.

pycbc.inference.io.ultranest module

Provides IO for the ultranest sampler.

class pycbc.inference.io.ultranest.UltranestFile(path, mode=None, **kwargs)

Bases: pycbc.inference.io.base_nested_sampler.BaseNestedSamplerFile

Class to handle file IO for the ultranest sampler.

name = 'ultranest_file'

Module contents

I/O utilities for pycbc inference

exception pycbc.inference.io.NoInputFileError

Bases: exceptions.Exception

Raised in custom argparse Actions by arguments needing input-files when no file(s) were provided.

class pycbc.inference.io.PrintFileParams(skip_args=None, nargs=0, **kwargs)

Bases: argparse.Action

Argparse action that will load input files and print possible parameters to screen. Once this is done, the program is forced to exit immediately.

The behvior is similar to –help, except that the input-file is read.

Note

The input_file attribute must be set in the parser namespace before this action is called. Otherwise, a NoInputFileError is raised.

class pycbc.inference.io.ResultsArgumentParser(skip_args=None, defaultparams=None, autoparamlabels=True, **kwargs)

Bases: argparse.ArgumentParser

Wraps argument parser, and preloads arguments needed for loading samples from a file.

This parser class should be used by any program that wishes to use the standard arguments for loading samples. It provides functionality to parse file specific options. These file-specific arguments are not included in the standard --help (since they depend on what input files are given), but can be seen by running --file-help/-H. The --file-help will also print off information about what parameters may be used given the input files.

As with the standard ArgumentParser, running this class’s parse_args will result in an error if arguments are provided that are not recognized by the parser, nor by any of the file-specific arguments. For example, parse_args would work on the command --input-file results.hdf --walker 0 if results.hdf was created by a sampler that recognizes a --walker argument, but would raise an error if results.hdf was created by a sampler that does not recognize a --walker argument. The extra arguments that are recognized are determined by the sampler IO class’s extra_args_parser.

Some arguments may be excluded from the parser using the skip_args optional parameter.

Parameters:

• skip_args (list of str, optional) – Do not add the given arguments to the parser. Arguments should be specified as the option string minus the leading ‘–’; e.g., skip_args=['thin-start'] would cause the thin-start argument to not be included. May also specify sampler-specific arguments. Note that input-file, file-help, and parameters are always added.
• defaultparams ({'variable_params', 'all'}, optional) – If no --parameters provided, which collection of parameters to load. If ‘all’ will load all parameters in the file’s samples_group. If ‘variable_params’ or None (the default) will load the variable parameters.
• autoparamlabels (bool, optional) – Passed to add_results_option_group; see that function for details.
• **kwargs – All other keyword arguments are passed to argparse.ArgumentParser.

actions

Exposes the actions this parser can do as a dictionary.

The dictionary maps the dest to actions.

add_results_option_group(autoparamlabels=True)

Adds the options used to call pycbc.inference.io.results_from_cli function to the parser.

These are options releated to loading the results from a run of pycbc_inference, for purposes of plotting and/or creating tables.

Any argument strings included in the skip_args attribute will not be added.

Parameters:autoparamlabels (bool, optional) – If True, the --parameters option will use labels from waveform.parameters if a parameter name is the same as a parameter there. Otherwise, will just use whatever label is provided. Default is True.

parse_known_args(args=None, namespace=None)

Parse args method to handle input-file dependent arguments.

pycbc.inference.io.check_integrity(filename)

Checks the integrity of an InferenceFile.

Checks done are:

• can the file open?
• do all of the datasets in the samples group have the same shape?
• can the first and last sample in all of the datasets in the samples group be read?

If any of these checks fail, an IOError is raised.

Parameters:

filename (str) – Name of an InferenceFile to check.

Raises:

• ValueError – If the given file does not exist.
• KeyError – If the samples group does not exist.
• IOError – If any of the checks fail.

pycbc.inference.io.get_common_parameters(input_files, collection=None)

Gets a list of variable params that are common across all input files.

If no common parameters are found, a ValueError is raised.

Parameters:

• input_files (list of str) – List of input files to load.
• collection (str, optional) – What group of parameters to load. Can be the name of a list of parameters stored in the files’ attrs (e.g., “variable_params”), or “all”. If “all”, will load all of the parameters in the files’ samples group. Default is to load all.

Returns:

List of the parameter names.

Return type:

list

pycbc.inference.io.get_file_type(filename)

Returns I/O object to use for file.

Parameters:filename (str) – Name of file. Returns:file_type – The type of inference file object to use. Return type:{InferenceFile, InferenceTXTFile}

pycbc.inference.io.injections_from_cli(opts)

Gets injection parameters from the inference file(s).

If the opts have a injection_samples_map option, the injection parameters will be remapped accordingly. See pycbc.inference.option_utils.add_injsamples_map_opt() for details.

Parameters:opts (argparser) – Argparser object that has the command-line objects to parse. Returns:Array of the injection parameters from all of the input files given by opts.input_file. Return type:FieldArray

pycbc.inference.io.loadfile(path, mode=None, filetype=None, **kwargs)

Loads the given file using the appropriate InferenceFile class.

If filetype is not provided, this will try to retreive the filetype from the file’s attrs. If the file does not exist yet, an IOError will be raised if filetype is not provided.

Parameters:

• path (str) – The filename to load.
• mode (str, optional) – What mode to load the file with, e.g., ‘w’ for write, ‘r’ for read, ‘a’ for append. Default will default to h5py.File’s mode, which is ‘a’.
• filetype (str, optional) – Force the file to be loaded with the given class name. This must be provided if creating a new file.

Returns:

An open file handler to the file. The class used for IO with the file is determined by the filetype keyword (if provided) or the filetype stored in the file (if not provided).

Return type:

filetype instance

pycbc.inference.io.results_from_cli(opts, load_samples=True, **kwargs)

Loads an inference result file along with any labels associated with it from the command line options.

Parameters:

• opts (ArgumentParser options) – The options from the command line.
• load_samples (bool, optional) – Load the samples from the file.

Returns:

• fp_all ((list of) BaseInferenceFile type) – The result file as an hdf file. If more than one input file, then it returns a list.
• parameters (list of str) – List of the parameters to use, parsed from the parameters option.
• labels (dict) – Dictionary of labels to associate with the parameters.
• samples_all ((list of) FieldArray(s) or None) – If load_samples, the samples as a FieldArray; otherwise, None. If more than one input file, then it returns a list.
• **kwargs – Any other keyword arguments that are passed to read samples using samples_from_cli

pycbc.inference.io.validate_checkpoint_files(checkpoint_file, backup_file)

Checks if the given checkpoint and/or backup files are valid.

The checkpoint file is considered valid if:

• it passes all tests run by check_integrity;
• it has at least one sample written to it (indicating at least one checkpoint has happened).

The same applies to the backup file. The backup file must also have the same number of samples as the checkpoint file, otherwise, the backup is considered invalid.

If the checkpoint (backup) file is found to be valid, but the backup (checkpoint) file is not valid, then the checkpoint (backup) is copied to the backup (checkpoint). Thus, this function ensures that checkpoint and backup files are either both valid or both invalid.

Parameters:

• checkpoint_file (string) – Name of the checkpoint file.
• backup_file (string) – Name of the backup file.

Returns:

checkpoint_valid – Whether or not the checkpoint (and backup) file may be used for loading samples.

Return type:

bool