PyCBC inference documentation (pycbc.inference)

Introduction

This page gives details on how to use the various parameter estimation executables and modules available in PyCBC. The pycbc.inference subpackage contains classes and functions for evaluating probability distributions, likelihoods, and running Bayesian samplers.

Overview

The executable pycbc_inference is designed to sample the parameter space and save the samples in an HDF file. A high-level description of the pycbc_inference algorithm is

  1. Read priors from a configuration file.

  2. Setup the model to use. If the model uses data, then:

    • Read gravitational-wave strain from a gravitational-wave model or use recolored fake strain.

    • Estimate a PSD.

  3. Run a sampler to estimate the posterior distribution of the model.

  4. Write the samples and metadata to an HDF file.

The model, data, sampler, parameters to vary and their priors are specified in one or more configuration files, which are passed to the program using the --config-file option. Other command-line options determine what parallelization settings to use. For a full listing of all options run pycbc_inference --help. Below, we give details on how to set up a configuration file and provide examples of how to run pycbc_inference.

Configuring the model, sampler, priors, and data

The configuration file(s) uses WorkflowConfigParser syntax. The required sections are: [model], [sampler], and [variable_params]. In addition, multiple [prior] sections must be provided that define the prior distribution to use for the parameters in [variable_params]. If a model uses data a [data] section must also be provided.

These sections may be split up over multiple files. In that case, all of the files should be provided as space-separated arguments to the --config-file. Providing multiple files is equivalent to providing a single file with everything across the files combined. If the same section is specified in multiple files, the all of the options will be combined.

Configuration files allow for referencing values in other sections using the syntax ${section|option}. See the examples below for an example of this. When providing multiple configuration files, sections in other files may be referenced, since in the multiple files are combined into a single file in memory when the files are loaded.

Configuring the model

See explanation of common likelihood models

The [model] section sets up what model to use for the analysis. At minimum, a name argument must be provided, specifying which model to use. For example:

[model]
name = gaussian_noise

In this case, the GaussianNoise model would be used. (Examples of using this model on a BBH injection and on GW150914 are given below.) Other arguments to configure the model may also be set in this section. The recognized arguments depend on the model. The currently available models are:

List of Models

Name

Class

'brute_lisa_sky_modes_marginalize'

pycbc.inference.models.brute_marg.BruteLISASkyModesMarginalize

'brute_parallel_gaussian_marginalize'

pycbc.inference.models.brute_marg.BruteParallelGaussianMarginalize

'gated_gaussian_margpol'

pycbc.inference.models.gated_gaussian_noise.GatedGaussianMargPol

'gated_gaussian_noise'

pycbc.inference.models.gated_gaussian_noise.GatedGaussianNoise

'gaussian_noise'

pycbc.inference.models.gaussian_noise.GaussianNoise

'hierarchical'

pycbc.inference.models.hierarchical.HierarchicalModel

'marginalized_hmpolphase'

pycbc.inference.models.marginalized_gaussian_noise.MarginalizedHMPolPhase

'marginalized_phase'

pycbc.inference.models.marginalized_gaussian_noise.MarginalizedPhaseGaussianNoise

'marginalized_polarization'

pycbc.inference.models.marginalized_gaussian_noise.MarginalizedPolarization

'marginalized_time'

pycbc.inference.models.marginalized_gaussian_noise.MarginalizedTime

'multi_signal'

pycbc.inference.models.hierarchical.MultiSignalModel

'relative'

pycbc.inference.models.relbin.Relative

'relative_time'

pycbc.inference.models.relbin.RelativeTime

'relative_time_dom'

pycbc.inference.models.relbin.RelativeTimeDom

'single_template'

pycbc.inference.models.single_template.SingleTemplate

'test_eggbox'

pycbc.inference.models.analytic.TestEggbox

'test_normal'

pycbc.inference.models.analytic.TestNormal

'test_posterior'

pycbc.inference.models.analytic.TestPosterior

'test_prior'

pycbc.inference.models.analytic.TestPrior

'test_rosenbrock'

pycbc.inference.models.analytic.TestRosenbrock

'test_volcano'

pycbc.inference.models.analytic.TestVolcano

Refer to the models’ from_config method to see what configuration arguments are available.

Any model name that starts with test_ is an analytic test distribution that requires no data or waveform generation. See the section below on running on an analytic distribution for more details.

Configuring the sampler

See example of trying different samplers

The [sampler] section sets up what sampler to use for the analysis. As with the [model] section, a name must be provided to specify which sampler to use. The currently available samplers are:

List of Supported Samplers

Configuration options for the sampler should also be specified in the [sampler] section. For example:

[sampler]
name = emcee
nwalkers = 5000
niterations = 1000
checkpoint-interval = 100

This would tell pycbc_inference to run the EmceeEnsembleSampler with 5000 walkers for 1000 iterations, checkpointing every 100th iteration. Refer to the samplers’ from_config method to see what configuration options are available.

Burn-in tests may also be configured for MCMC samplers in the config file. The options for the burn-in should be placed in [sampler-burn_in]. At minimum, a burn-in-test argument must be given in this section. This argument specifies which test(s) to apply. Multiple tests may be combined using standard python logic operators. For example:

[sampler-burn_in]
burn-in-test = nacl & max_posterior

In this case, the sampler would be considered to be burned in when both the nacl and max_posterior tests were satisfied. Setting this to nacl | max_postrior would instead consider the sampler to be burned in when either the nacl or max_posterior tests were satisfied. For more information on what tests are available, see the pycbc.inference.burn_in module.

Thinning samples (MCMC only)

The default behavior for the MCMC samplers (emcee, emcee_pt) is to save every iteration of the Markov chains to the output file. This can quickly lead to very large files. For example, a BBH analysis (~15 parameters) with 200 walkers, 20 temperatures may take ~50 000 iterations to acquire ~5000 independent samples. This will lead to a file that is ~ 50 000 iterations x 200 walkers x 20 temperatures x 15 parameters x 8 bytes ~ 20GB. Quieter signals can take an order of magnitude more iterations to converge, leading to O(100GB) files. Clearly, since we only obtain 5000 independent samples from such a run, the vast majority of these samples are of little interest.

To prevent large file size growth, samples may be thinned before they are written to disk. Two thinning options are available, both of which are set in the [sampler] section of the configuration file. They are:

  • thin-interval: This will thin the samples by the given integer before writing the samples to disk. File sizes can still grow unbounded, but at a slower rate. The interval must be less than the checkpoint interval.

  • max-samples-per-chain: This will cap the maximum number of samples per walker and per temperature to the given integer. This ensures that file sizes never exceed ~ max-samples-per-chain x nwalkers x ntemps x nparameters x 8 bytes. Once the limit is reached, samples will be thinned on disk, and new samples will be thinned to match. The thinning interval will grow with longer runs as a result. To ensure that enough samples exist to determine burn in and to measure an autocorrelation length, max-samples-per-chain must be greater than or equal to 100.

The thinned interval that was used for thinning samples is saved to the output file’s thinned_by attribute (stored in the HDF file’s .attrs). Note that this is not the autocorrelation length (ACL), which is the amount that the samples need to be further thinned to obtain independent samples.

Note

In the output file creates by the MCMC samplers, we adopt the convention that “iteration” means iteration of the sampler, not index of the samples. For example, if a burn in test is used, burn_in_iteration will be stored to the sampler_info group in the output file. This gives the iteration of the sampler at which burn in occurred, not the sample on disk. To determine which samples an iteration corresponds to in the file, divide iteration by thinned_by.

Likewise, we adopt the convention that autocorrelation length (ACL) is the autocorrelation length of the thinned samples (the number of samples on disk that you need to skip to get independent samples) whereas autocorrelation time (ACT) is the autocorrelation length in terms of iteration (it is the number of iterations that you need to skip to get independent samples); i.e., ACT = thinned_by x ACL. The ACT is (up to measurement resolution) independent of the thinning used, and thus is useful for comparing the performance of the sampler.

Configuring the prior

What parameters to vary to obtain a posterior distribution are determined by [variable_params] section. For example:

[variable_params]
x =
y =

This would tell pycbc_inference to sample a posterior over two parameters called x and y.

A prior must be provided for every parameter in [variable_params]. This is done by adding sections named [prior-{param}] where {param} is the name of the parameter the prior is for. For example, to provide a prior for the x parameter in the above example, you would need to add a section called [prior-x]. If the prior couples more than one parameter together in a joint distribution, the parameters should be provided as a + separated list, e.g., [prior-x+y+z].

The prior sections specify what distribution to use for the parameter’s prior, along with any settings for that distribution. Similar to the model and sampler sections, each prior section must have a name argument that identifies the distribution to use. Distributions are defined in the pycbc.distributions module. The currently available distributions are:

List of Statistical Distributions

Static parameters

A [static_params] section may be provided to list any parameters that will remain fixed throughout the run. For example:

[static_params]
approximant = IMRPhenomPv2
f_lower = 18

In the example above, we choose the waveform model ‘IMRPhenomPv2’. PyCBC comes with access to waveforms provided by the lalsimulation package. If you’d like to use a custom waveform outside of what PyCBC currently supports, see documentation on creating a plugin for PyCBC

Setting data

Many models, such as the GaussianNoise model, require data to be provided. To do so, a [data] section must be included that provides information about what data to load, and how to condition it.

The type of data to be loaded depends on the model. For example, if you are using the GaussianNoise or MarginalizedPhaseGaussianNoise models (the typical case), one will need to load gravitational-wave data. This is accomplished using tools provided in the pycbc.strain module. The full set of options are:

Options for reading / configuring GW data

Name

Syntax

Description

instruments

INSTRUMENTS [INSTRUMENTS …]

Instruments to analyze, eg. H1 L1.

trigger-time

TRIGGER_TIME

Reference GPS time (at geocenter) from which the (anlaysis|psd)-(start|end)-time options are measured. The integer seconds will be used. Default is 0; i.e., if not provided, the analysis and psd times should be in GPS seconds.

analysis-start-time

IFO:TIME [IFO:TIME …]

The start time to use for the analysis, measured with respect to the trigger-time. If psd-inverse-length is provided, the given start time will be padded by half that length to account for wrap-around effects.

analysis-end-time

IFO:TIME [IFO:TIME …]

The end time to use for the analysis, measured with respect to the trigger-time. If psd-inverse-length is provided, the given end time will be padded by half that length to account for wrap-around effects.

psd-start-time

IFO:TIME [IFO:TIME …]

Start time to use for PSD estimation, measured with respect to the trigger-time.

psd-end-time

IFO:TIME [IFO:TIME …]

End time to use for PSD estimation, measured with respect to the trigger-time.

data-conditioning-low-freq

IFO:FLOW [IFO:FLOW …]

Low frequency cutoff of the data. Needed for PSD estimation and when creating fake strain. If not provided, will use the model’s low-frequency-cutoff.

Options to select the method of PSD generation: The options psd-model, psd-file, asd-file, and psd-estimation are mutually exclusive.

psd-model

IFO:MODEL [IFO:MODEL …]

Get PSD from given analytical model. Choose from any available PSD model.

psd-extra-args

DETECTOR:PARAM:VALUE [DETECTOR:PARAM:VALUE …]

(optional) Extra arguments passed to the PSD models.

psd-file

IFO:FILE [IFO:FILE …]

Get PSD using given PSD ASCII file

asd-file

IFO:FILE [IFO:FILE …]

Get PSD using given ASD ASCII file

psd-estimation

IFO:FILE [IFO:FILE …]

Measure PSD from the data, using given average method. Choose from mean, median or median-mean.

psd-segment-length

IFO:LENGTH [IFO:LENGTH …]

(Required for psd-estimation) The segment length for PSD estimation (s)

psd-segment-stride

IFO:STRIDE [IFO:STRIDE …]

(Required for psd-estimation) The separation between consecutive segments (s)

psd-num-segments

IFO:NUM [IFO:NUM …]

(Optional, used only with psd-estimation). If given PSDs will be estimated using only this number of segments. If more data is given than needed to make this number of segments than excess data will not be used in the PSD estimate. If not enough data is given the code will fail.

psd-inverse-length

IFO:LENGTH [IFO:LENGTH …]

(Optional) The maximum length of the impulse response of the overwhitening filter (s)

invpsd-trunc-method

{hann}

(Optional) What truncation method to use when applying psd-inverse-length. If not provided, a hard truncation will be used.

psd-output

IFO:FILE [IFO:FILE …]

(Optional) Write PSD to specified file

psdvar-segment

SECONDS

Length of segment when calculating the PSD variability.

psdvar-short-segment

SECONDS

Length of short segment for outliers removal in PSD variability calculation.

psdvar-long-segment

SECONDS

Length of long segment when calculating the PSD variability.

psdvar-psd-duration

SECONDS

Duration of short segments for PSD estimation.

psdvar-psd-stride

SECONDS

Separation between PSD estimation segments.

psdvar-low-freq

HERTZ

Minimum frequency to consider in strain bandpass.

psdvar-high-freq

HERTZ

Maximum frequency to consider in strain bandpass.

Options for obtaining h(t): These options are used for generating h(t) either by reading from a file or by generating it. This is only needed if the PSD is to be estimated from the data, ie. if the psd-estimation option is given. This group supports reading from multiple ifos simultaneously.

strain-high-pass

IFO:FREQUENCY [IFO:FREQUENCY …]

High pass frequency

strain-low-pass

IFO:FREQUENCY [IFO:FREQUENCY …]

Low pass frequency

pad-data

IFO:LENGTH [IFO:LENGTH …]

Extra padding to remove highpass corruption (integer seconds, default 8)

taper-data

IFO:LENGTH [IFO:LENGTH …]

Taper ends of data to zero using the supplied length as a window (integer seconds)

sample-rate

IFO:RATE [IFO:RATE …]

The sample rate to use for h(t) generation (integer Hz).

channel-name

IFO:CHANNEL [IFO:CHANNEL …]

The channel containing the gravitational strain data

frame-cache

IFO:FRAME_CACHE [IFO:FRAME_CACHE …]

Cache file containing the frame locations.

frame-files

IFO:FRAME_FILES [IFO:FRAME_FILES …]

list of frame files

hdf-store

IFO:HDF_STORE_FILE [IFO:HDF_STORE_FILE …]

Store of time series data in hdf format

frame-type

IFO:FRAME_TYPE [IFO:FRAME_TYPE …]

(optional) Replaces frame-files. Use datafind to get the needed frame file(s) of this type.

frame-sieve

IFO:FRAME_SIEVE [IFO:FRAME_SIEVE …]

(optional), Only use frame files where the URL matches the regular expression given.

fake-strain

IFO:CHOICE [IFO:CHOICE …]

Name of model PSD for generating fake gaussian noise. Choose from any available PSD model, or zeroNoise.

fake-strain-extra-args

DETECTOR:PARAM:VALUE [DETECTOR:PARAM:VALUE …]

(optional) Extra arguments passed to the PSD models.

fake-strain-seed

IFO:SEED [IFO:SEED …]

Seed value for the generation of fake colored gaussian noise

fake-strain-from-file

IFO:FILE [IFO:FILE …]

File containing ASD for generating fake noise from it.

fake-strain-flow

FAKE_STRAIN_FLOW [FAKE_STRAIN_FLOW …]

Low frequency cutoff of the fake strain

fake-strain-filter-duration

FAKE_STRAIN_FILTER_DURATION [FAKE_STRAIN_FILTER_DURATION …]

Duration in seconds of the fake data coloring filter

fake-strain-sample-rate

FAKE_STRAIN_SAMPLE_RATE [FAKE_STRAIN_SAMPLE_RATE …]

Sample rate of the fake data generation

injection-file

IFO:FILE [IFO:FILE …]

(optional) Injection file containing parametersof CBC signals to be added to the strain

sgburst-injection-file

IFO:FILE [IFO:FILE …]

(optional) Injection file containing parametersof sine-Gaussian burst signals to add to the strain

injection-scale-factor

IFO:VAL [IFO:VAL …]

Divide injections by this factor before adding to the strain data

injection-sample-rate

IFO:VAL [IFO:VAL …]

Sample rate to use for injections (integer Hz). Typically similar to the strain data sample rate.If not provided, the strain sample rate will be used

injection-f-ref

IFO:VALUE [IFO:VALUE …]

Reference frequency in Hz for creating CBC injections from an XML file

injection-f-final

IFO:VALUE [IFO:VALUE …]

Override the f_final field of a CBC XML injection file (frequency in Hz)

gating-file

IFO:FILE [IFO:FILE …]

(optional) Text file of gating segments to apply. Format of each line (units s) : gps_time zeros_half_width pad_half_width

autogating-threshold

IFO:SIGMA [IFO:SIGMA …]

If given, find and gate glitches producing a deviation larger than SIGMA in the whitened strain time series

autogating-max-iterations

SIGMA

If given, iteratively apply autogating

autogating-cluster

IFO:SECONDS [IFO:SECONDS …]

Length of clustering window for detecting glitches for autogating.

autogating-width

IFO:SECONDS [IFO:SECONDS …]

Half-width of the gating window.

autogating-taper

IFO:SECONDS [IFO:SECONDS …]

Taper the strain before and after each gating window over a duration of SECONDS.

autogating-pad

IFO:SECONDS [IFO:SECONDS …]

Ignore the given length of whitened strain at the ends of a segment, to avoid filters ringing.

gating-method

{hard,taper,paint} [{hard,taper,paint} …]

Choose the method for gating. Default: taper

normalize-strain

IFO:VALUE [IFO:VALUE …]

(optional) Divide frame data by constant.

zpk-z

IFO:VALUE [IFO:VALUE …]

(optional) Zero-pole-gain (zpk) filter strain. A list of zeros for transfer function

zpk-p

IFO:VALUE [IFO:VALUE …]

(optional) Zero-pole-gain (zpk) filter strain. A list of poles for transfer function

zpk-k

IFO:VALUE [IFO:VALUE …]

(optional) Zero-pole-gain (zpk) filter strain. Transfer function gain

Options for gating data:

gate

IFO:CENTRALTIME:HALFDUR:TAPERDUR [IFO:CENTRALTIME:HALFDUR:TAPERDUR …]

Apply one or more gates to the data before filtering.

gate-overwhitened

Overwhiten data first, then apply the gates specified in gate. Overwhitening allows for sharper tapers to be used, since lines are not blurred.

psd-gate

IFO:CENTRALTIME:HALFDUR:TAPERDUR [IFO:CENTRALTIME:HALFDUR:TAPERDUR …]

Apply one or more gates to the data used for computing the PSD. Gates are applied prior to FFT-ing the data for PSD estimation.

Options for quering data quality (DQ):

dq-segment-name

DQ_SEGMENT_NAME

The status flag to query for data quality. Default is “DATA”.

dq-source

{any,GWOSC,dqsegdb}

Where to look for DQ information. If “any” (the default) will first try GWOSC, then dqsegdb.

dq-server

DQ_SERVER

The server to use for dqsegdb.

veto-definer

VETO_DEFINER

Path to a veto definer file that defines groups of flags, which themselves define a set of DQ segments.

As indicated in the table, the psd-model and fake-strain options can accept an analytical PSD as an argument. The available PSD models are:

Options for reading or estimating PSDs

Name

Function

AdVBNSOptimizedSensitivityP1200087

pycbc.psd.analytical.AdVBNSOptimizedSensitivityP1200087()

AdVDesignSensitivityP1200087

pycbc.psd.analytical.AdVDesignSensitivityP1200087()

AdVEarlyHighSensitivityP1200087

pycbc.psd.analytical.AdVEarlyHighSensitivityP1200087()

AdVEarlyLowSensitivityP1200087

pycbc.psd.analytical.AdVEarlyLowSensitivityP1200087()

AdVLateHighSensitivityP1200087

pycbc.psd.analytical.AdVLateHighSensitivityP1200087()

AdVLateLowSensitivityP1200087

pycbc.psd.analytical.AdVLateLowSensitivityP1200087()

AdVMidHighSensitivityP1200087

pycbc.psd.analytical.AdVMidHighSensitivityP1200087()

AdVMidLowSensitivityP1200087

pycbc.psd.analytical.AdVMidLowSensitivityP1200087()

AdVO3LowT1800545

pycbc.psd.analytical.AdVO3LowT1800545()

AdVO4IntermediateT1800545

pycbc.psd.analytical.AdVO4IntermediateT1800545()

AdVO4T1800545

pycbc.psd.analytical.AdVO4T1800545()

AdvVirgo

pycbc.psd.analytical.AdvVirgo()

CosmicExplorerP1600143

pycbc.psd.analytical.CosmicExplorerP1600143()

CosmicExplorerPessimisticP1600143

pycbc.psd.analytical.CosmicExplorerPessimisticP1600143()

CosmicExplorerWidebandP1600143

pycbc.psd.analytical.CosmicExplorerWidebandP1600143()

EinsteinTelescopeP1600143

pycbc.psd.analytical.EinsteinTelescopeP1600143()

GEOHF

pycbc.psd.analytical.GEOHF()

GEO

pycbc.psd.analytical.GEO()

KAGRA128MpcT1800545

pycbc.psd.analytical.KAGRA128MpcT1800545()

KAGRA25MpcT1800545

pycbc.psd.analytical.KAGRA25MpcT1800545()

KAGRA80MpcT1800545

pycbc.psd.analytical.KAGRA80MpcT1800545()

KAGRADesignSensitivityT1600593

pycbc.psd.analytical.KAGRADesignSensitivityT1600593()

KAGRAEarlySensitivityT1600593

pycbc.psd.analytical.KAGRAEarlySensitivityT1600593()

KAGRALateSensitivityT1600593

pycbc.psd.analytical.KAGRALateSensitivityT1600593()

KAGRAMidSensitivityT1600593

pycbc.psd.analytical.KAGRAMidSensitivityT1600593()

KAGRAOpeningSensitivityT1600593

pycbc.psd.analytical.KAGRAOpeningSensitivityT1600593()

KAGRA

pycbc.psd.analytical.KAGRA()

TAMA

pycbc.psd.analytical.TAMA()

Virgo

pycbc.psd.analytical.Virgo()

aLIGO140MpcT1800545

pycbc.psd.analytical.aLIGO140MpcT1800545()

aLIGO175MpcT1800545

pycbc.psd.analytical.aLIGO175MpcT1800545()

aLIGOAPlusDesignSensitivityT1800042

pycbc.psd.analytical.aLIGOAPlusDesignSensitivityT1800042()

aLIGOAdVO3LowT1800545

pycbc.psd.analytical.aLIGOAdVO3LowT1800545()

aLIGOAdVO4IntermediateT1800545

pycbc.psd.analytical.aLIGOAdVO4IntermediateT1800545()

aLIGOAdVO4T1800545

pycbc.psd.analytical.aLIGOAdVO4T1800545()

aLIGOBHBH20DegGWINC

pycbc.psd.analytical.aLIGOBHBH20DegGWINC()

aLIGOBHBH20Deg

pycbc.psd.analytical.aLIGOBHBH20Deg()

aLIGOBNSOptimizedSensitivityP1200087

pycbc.psd.analytical.aLIGOBNSOptimizedSensitivityP1200087()

aLIGODesignSensitivityP1200087

pycbc.psd.analytical.aLIGODesignSensitivityP1200087()

aLIGODesignSensitivityT1800044

pycbc.psd.analytical.aLIGODesignSensitivityT1800044()

aLIGOEarlyHighSensitivityP1200087

pycbc.psd.analytical.aLIGOEarlyHighSensitivityP1200087()

aLIGOEarlyLowSensitivityP1200087

pycbc.psd.analytical.aLIGOEarlyLowSensitivityP1200087()

aLIGOHighFrequencyGWINC

pycbc.psd.analytical.aLIGOHighFrequencyGWINC()

aLIGOHighFrequency

pycbc.psd.analytical.aLIGOHighFrequency()

aLIGOKAGRA128MpcT1800545

pycbc.psd.analytical.aLIGOKAGRA128MpcT1800545()

aLIGOKAGRA25MpcT1800545

pycbc.psd.analytical.aLIGOKAGRA25MpcT1800545()

aLIGOKAGRA80MpcT1800545

pycbc.psd.analytical.aLIGOKAGRA80MpcT1800545()

aLIGOLateHighSensitivityP1200087

pycbc.psd.analytical.aLIGOLateHighSensitivityP1200087()

aLIGOLateLowSensitivityP1200087

pycbc.psd.analytical.aLIGOLateLowSensitivityP1200087()

aLIGOMidHighSensitivityP1200087

pycbc.psd.analytical.aLIGOMidHighSensitivityP1200087()

aLIGOMidLowSensitivityP1200087

pycbc.psd.analytical.aLIGOMidLowSensitivityP1200087()

aLIGONSNSOptGWINC

pycbc.psd.analytical.aLIGONSNSOptGWINC()

aLIGONSNSOpt

pycbc.psd.analytical.aLIGONSNSOpt()

aLIGONoSRMHighPower

pycbc.psd.analytical.aLIGONoSRMHighPower()

aLIGONoSRMLowPowerGWINC

pycbc.psd.analytical.aLIGONoSRMLowPowerGWINC()

aLIGONoSRMLowPower

pycbc.psd.analytical.aLIGONoSRMLowPower()

aLIGOO3LowT1800545

pycbc.psd.analytical.aLIGOO3LowT1800545()

aLIGOQuantumBHBH20Deg

pycbc.psd.analytical.aLIGOQuantumBHBH20Deg()

aLIGOQuantumHighFrequency

pycbc.psd.analytical.aLIGOQuantumHighFrequency()

aLIGOQuantumNSNSOpt

pycbc.psd.analytical.aLIGOQuantumNSNSOpt()

aLIGOQuantumNoSRMHighPower

pycbc.psd.analytical.aLIGOQuantumNoSRMHighPower()

aLIGOQuantumNoSRMLowPower

pycbc.psd.analytical.aLIGOQuantumNoSRMLowPower()

aLIGOQuantumZeroDetHighPower

pycbc.psd.analytical.aLIGOQuantumZeroDetHighPower()

aLIGOQuantumZeroDetLowPower

pycbc.psd.analytical.aLIGOQuantumZeroDetLowPower()

aLIGOThermal

pycbc.psd.analytical.aLIGOThermal()

aLIGOZeroDetHighPowerGWINC

pycbc.psd.analytical.aLIGOZeroDetHighPowerGWINC()

aLIGOZeroDetHighPower

pycbc.psd.analytical.aLIGOZeroDetHighPower()

aLIGOZeroDetLowPowerGWINC

pycbc.psd.analytical.aLIGOZeroDetLowPowerGWINC()

aLIGOZeroDetLowPower

pycbc.psd.analytical.aLIGOZeroDetLowPower()

aLIGOaLIGO140MpcT1800545

pycbc.psd.analytical.aLIGOaLIGO140MpcT1800545()

aLIGOaLIGO175MpcT1800545

pycbc.psd.analytical.aLIGOaLIGO175MpcT1800545()

aLIGOaLIGODesignSensitivityT1800044

pycbc.psd.analytical.aLIGOaLIGODesignSensitivityT1800044()

aLIGOaLIGOO3LowT1800545

pycbc.psd.analytical.aLIGOaLIGOO3LowT1800545()

analytical_psd_lisa_tdi_1p5_AE

pycbc.psd.analytical_space.analytical_psd_lisa_tdi_1p5_AE()

analytical_psd_lisa_tdi_1p5_T

pycbc.psd.analytical_space.analytical_psd_lisa_tdi_1p5_T()

analytical_psd_lisa_tdi_1p5_XYZ

pycbc.psd.analytical_space.analytical_psd_lisa_tdi_1p5_XYZ()

analytical_psd_lisa_tdi_2p0_XYZ

pycbc.psd.analytical_space.analytical_psd_lisa_tdi_2p0_XYZ()

analytical_psd_lisa_tdi_AE_confusion

pycbc.psd.analytical_space.analytical_psd_lisa_tdi_AE_confusion()

eLIGOModel

pycbc.psd.analytical.eLIGOModel()

eLIGOShot

pycbc.psd.analytical.eLIGOShot()

flat_unity

pycbc.psd.analytical.flat_unity()

iLIGOModel

pycbc.psd.analytical.iLIGOModel()

iLIGOSRD

pycbc.psd.analytical.iLIGOSRD()

iLIGOSeismic

pycbc.psd.analytical.iLIGOSeismic()

iLIGOShot

pycbc.psd.analytical.iLIGOShot()

iLIGOThermal

pycbc.psd.analytical.iLIGOThermal()

sh_transformed_psd_lisa_tdi_XYZ

pycbc.psd.analytical_space.sh_transformed_psd_lisa_tdi_XYZ()

Advanced configuration settings

The following are additional settings that may be provided in the configuration file, in order to do more sophisticated analyses.

Sampling transform (for MCMC samplers)

One or more of the variable_params may be transformed to a different parameter space for purposes of sampling. This is done by specifying a [sampling_params] section. This section specifies which variable_params to replace with which parameters for sampling. This must be followed by one or more [sampling_transforms-{sampling_params}] sections that provide the transform class to use. For example, the following would cause the sampler to sample in chirp mass (mchirp) and mass ratio (q) instead of mass1 and mass2:

[sampling_params]
mass1, mass2: mchirp, q

[sampling_transforms-mchirp+q]
name = mass1_mass2_to_mchirp_q

Transforms are provided by the pycbc.transforms module. The currently available transforms are:

List of Sampling Transformations

Name

Class

'align_total_spin'

pycbc.transforms.AlignTotalSpin

'aligned_mass_spin_to_cartesian_spin'

pycbc.transforms.AlignedMassSpinToCartesianSpin

'cartesian_spin_1_to_spherical_spin_1'

pycbc.transforms.CartesianSpin1ToSphericalSpin1

'cartesian_spin_2_to_spherical_spin_2'

pycbc.transforms.CartesianSpin2ToSphericalSpin2

'cartesian_spin_to_aligned_mass_spin'

pycbc.transforms.CartesianSpinToAlignedMassSpin

'cartesian_spin_to_chi_p'

pycbc.transforms.CartesianSpinToChiP

'cartesian_spin_to_precession_mass_spin'

pycbc.transforms.CartesianSpinToPrecessionMassSpin

'cartesian_to_spherical'

pycbc.transforms.CartesianToSpherical

'chirp_distance_to_distance'

pycbc.transforms.ChirpDistanceToDistance

'custom'

pycbc.transforms.CustomTransform

'custom_multi'

pycbc.transforms.CustomTransformMultiOutputs

'distance_to_chirp_distance'

pycbc.transforms.DistanceToChirpDistance

'distance_to_redshift'

pycbc.transforms.DistanceToRedshift

'exponent'

pycbc.transforms.Exponent

'geo_to_lisa'

pycbc.transforms.GEOToLISA

'geo_to_ssb'

pycbc.transforms.GEOToSSB

'lambda_from_multiple_tov_files'

pycbc.transforms.LambdaFromMultipleTOVFiles

'lambda_from_tov_file'

pycbc.transforms.LambdaFromTOVFile

'lisa_to_geo'

pycbc.transforms.LISAToGEO

'lisa_to_ssb'

pycbc.transforms.LISAToSSB

'log'

pycbc.transforms.Log

'logistic'

pycbc.transforms.Logistic

'logit'

pycbc.transforms.Logit

'mass1_mass2_to_mchirp_eta'

pycbc.transforms.Mass1Mass2ToMchirpEta

'mass1_mass2_to_mchirp_q'

pycbc.transforms.Mass1Mass2ToMchirpQ

'mchirp_eta_to_mass1_mass2'

pycbc.transforms.MchirpEtaToMass1Mass2

'mchirp_q_to_mass1_mass2'

pycbc.transforms.MchirpQToMass1Mass2

'precession_mass_spin_to_cartesian_spin'

pycbc.transforms.PrecessionMassSpinToCartesianSpin

'spherical_spin_1_to_cartesian_spin_1'

pycbc.transforms.SphericalSpin1ToCartesianSpin1

'spherical_spin_2_to_cartesian_spin_2'

pycbc.transforms.SphericalSpin2ToCartesianSpin2

'spherical_to_cartesian'

pycbc.transforms.SphericalToCartesian

'ssb_to_geo'

pycbc.transforms.SSBToGEO

'ssb_to_lisa'

pycbc.transforms.SSBToLISA

Note

Both a jacobian and inverse_jacobian must be defined in order to use a transform class for a sampling transform. Not all transform classes in pycbc.transforms have these defined. Check the class documentation to see if a Jacobian is defined.

Waveform transforms

There can be any number of variable_params with any name. No parameter name is special (with the exception of parameters that start with calib_; see below).

However, when doing parameter estimation with CBC waveforms, certain parameter names must be provided for waveform generation. The parameter names recognized by the CBC waveform generators are:

List of CBCs signal parameters

Parameter

Description

'mass1'

The mass of the first component object in the binary (in solar masses).

'mass2'

The mass of the second component object in the binary (in solar masses).

'spin1x'

The x component of the first binary component’s dimensionless spin.

'spin1y'

The y component of the first binary component’s dimensionless spin.

'spin1z'

The z component of the first binary component’s dimensionless spin.

'spin2x'

The x component of the second binary component’s dimensionless spin.

'spin2y'

The y component of the second binary component’s dimensionless spin.

'spin2z'

The z component of the second binary component’s dimensionless spin.

'eccentricity'

Eccentricity.

'lambda1'

The dimensionless tidal deformability parameter of object 1.

'lambda2'

The dimensionless tidal deformability parameter of object 2.

'dquad_mon1'

Quadrupole-monopole parameter / m_1^5 -1.

'dquad_mon2'

Quadrupole-monopole parameter / m_2^5 -1.

'lambda_octu1'

The octupolar tidal deformability parameter of object 1.

'lambda_octu2'

The octupolar tidal deformability parameter of object 2.

'quadfmode1'

The quadrupolar f-mode angular frequency of object 1.

'quadfmode2'

The quadrupolar f-mode angular frequency of object 2.

'octufmode1'

The octupolar f-mode angular frequency of object 1.

'octufmode2'

The octupolar f-mode angular frequency of object 2.

'dchi0'

0PN testingGR parameter.

'dchi1'

0.5PN testingGR parameter.

'dchi2'

1PN testingGR parameter.

'dchi3'

1.5PN testingGR parameter.

'dchi4'

2PN testingGR parameter.

'dchi5'

2.5PN testingGR parameter.

'dchi5l'

2.5PN logrithm testingGR parameter.

'dchi6'

3PN testingGR parameter.

'dchi6l'

3PN logrithm testingGR parameter.

'dchi7'

3.5PN testingGR parameter.

'dalpha1'

Merger-ringdown testingGR parameter.

'dalpha2'

Merger-ringdown testingGR parameter.

'dalpha3'

Merger-ringdown testingGR parameter.

'dalpha4'

Merger-ringdown testingGR parameter.

'dalpha5'

Merger-ringdown testingGR parameter.

'dbeta1'

Intermediate testingGR parameter.

'dbeta2'

Intermediate testingGR parameter.

'dbeta3'

Intermediate testingGR parameter.

'distance'

Luminosity distance to the binary (in Mpc).

'coa_phase'

Coalesence phase of the binary (in rad).

'inclination'

Inclination (rad), defined as the angle between the orbital angular momentum L and the line-of-sight at the reference frequency.

'long_asc_nodes'

Longitude of ascending nodes axis (rad).

'mean_per_ano'

Mean anomaly of the periastron (rad).

'delta_t'

The time step used to generate the waveform (in s).

'f_lower'

The starting frequency of the waveform (in Hz).

'approximant'

A string that indicates the chosen approximant.

'f_ref'

The reference frequency.

'phase_order'

The pN order of the orbital phase. The default of -1 indicates that all implemented orders are used.

'spin_order'

The pN order of the spin corrections. The default of -1 indicates that all implemented orders are used.

'tidal_order'

The pN order of the tidal corrections. The default of -1 indicates that all implemented orders are used.

'amplitude_order'

The pN order of the amplitude. The default of -1 indicates that all implemented orders are used.

'eccentricity_order'

The pN order of the eccentricity corrections.The default of -1 indicates that all implemented orders are used.

'frame_axis'

Allow to choose among orbital_l, view and total_j

'modes_choice'

Allow to turn on among orbital_l, view and total_j

'side_bands'

Flag for generating sidebands

'mode_array'

Choose which (l,m) modes to include when generating a waveform. Only if approximant supports this feature.By default pass None and let lalsimulation use it’s default behaviour.Example: mode_array = [ [2,2], [2,-2] ]

'numrel_data'

Sets the NR flags; only needed for NR waveforms.

'delta_f'

The frequency step used to generate the waveform (in Hz).

'f_final'

The ending frequency of the waveform. The default (0) indicates that the choice is made by the respective approximant.

'f_final_func'

Use the given frequency function to compute f_final based on the parameters of the waveform.

'tc'

Coalescence time (s) is the time when a GW reaches the origin of a certain coordinate system.

'ra'

Right ascension (rad).

'dec'

Declination (rad).

'polarization'

Polarization angle (rad) in a certain coordinate system.

'eclipticlatitude'

eclipticlatitude in SSB/LISA coords.

'eclipticlongitude'

eclipticlongitude in SSB/LISA coords.

It is possible to specify a variable_param that is not one of these parameters. To do so, you must provide one or more [waveforms_transforms-{param}] section(s) that define transform(s) from the arbitrary variable_params to the needed waveform parameter(s) {param}. For example, in the following we provide a prior on chirp_distance. Since distance, not chirp_distance, is recognized by the CBC waveforms module, we provide a transform to go from chirp_distance to distance:

[variable_params]
chirp_distance =

[prior-chirp_distance]
name = uniform
min-chirp_distance = 1
max-chirp_distance = 200

[waveform_transforms-distance]
name = chirp_distance_to_distance

A useful transform for these purposes is the CustomTransform, which allows for arbitrary transforms using any function in the pycbc.conversions, pycbc.coordinates, or pycbc.cosmology modules, along with numpy math functions. For example, the following would use the I-Love-Q relationship pycbc.conversions.dquadmon_from_lambda() to relate the quadrupole moment of a neutron star dquad_mon1 to its tidal deformation lambda1:

[variable_params]
lambda1 =

[waveform_transforms-dquad_mon1]
name = custom
inputs = lambda1
dquad_mon1 = dquadmon_from_lambda(lambda1)

Note

A Jacobian is not necessary for waveform transforms, since the transforms are only being used to convert a set of parameters into something that the waveform generator understands. This is why in the above example we are able to use a custom transform without needing to provide a Jacobian.

Calibration parameters

If any calibration parameters are used (prefix calib_), a [calibration] section must be included. This section must have a name option that identifies what calibration model to use. The models are described in pycbc.calibration. The [calibration] section must also include reference values fc0, fs0, and qinv0, as well as paths to ASCII transfer function files for the test mass actuation, penultimate mass actuation, sensing function, and digital filter for each IFO being used in the analysis. E.g. for an analysis using H1 only, the required options would be h1-fc0, h1-fs0, h1-qinv0, h1-transfer-function-a-tst, h1-transfer-function-a-pu, h1-transfer-function-c, h1-transfer-function-d.

Constraints

One or more constraints may be applied to the parameters; these are specified by the [constraint] section(s). Additional constraints may be supplied by adding more [constraint-{tag}] sections. Any tag may be used; the only requirement is that they be unique. If multiple constraint sections are provided, the union of all constraints is applied. Alternatively, multiple constraints may be joined in a single argument using numpy’s logical operators.

The parameter that constraints are applied to may be any parameter in variable_params or any output parameter of the transforms. Functions may be applied to these parameters to obtain constraints on derived parameters. Any function in the conversions, coordinates, or cosmology module may be used, along with any numpy ufunc. So, in the following example, the mass ratio (q) is constrained to be <= 4 by using a function from the conversions module.

[variable_params]
mass1 =
mass2 =

[prior-mass1]
name = uniform
min-mass1 = 3
max-mass1 = 12

[prior-mass2]
name = uniform
min-mass2 = 1
min-mass2 = 3

[constraint-1]
name = custom
constraint_arg = q_from_mass1_mass2(mass1, mass2) <= 4

Checkpointing and output files

While pycbc_inference is running it will create a checkpoint file which is named {output-file}.checkpoint, where {output-file} was the name of the file you specified with the --output-file command. When it checkpoints it will dump results to this file; when finished, the file is renamed to {output-file}. A {output-file}.bkup is also created, which is a copy of the checkpoint file. This is kept in case the checkpoint file gets corrupted during writing. The .bkup file is deleted at the end of the run, unless --save-backup is turned on.

When pycbc_inference starts, it checks if either {output-file}.checkpoint or {output-file}.bkup exist (in that order). If at least one of them exists, pycbc_inference will attempt to load them and continue to run from the last checkpoint state they were in.

The output/checkpoint file are HDF files. To peruse the structure of the file you can use the h5ls command-line utility. More advanced utilities for reading and writing from/to them are provided by the sampler IO classes in pycbc.inference.io. To load one of these files in python do:

from pycbc.inference import io
fp = io.loadfile(filename, "r")

Here, fp is an instance of a sampler IO class. Basically, this is an instance of an h5py.File handler, with additional convenience functions added on top. For example, if you want all of the samples of all of the variable parameters in the file, you can do:

samples = fp.read_samples(fp.variable_params)

This will return a FieldArray of all of the samples.

Each sampler has it’s own sampler IO class that adds different convenience functions, depending on the sampler that was used. For more details on these classes, see the pycbc.inference.io module.

Examples

Visualizing the Posteriors

Workflows

For Developers