Examples

In this page we list some example ini files are explain their particularities.

Trigger time

The trigger-time data-generation method is the easiest way to run on an event or particular time of interest. Simply specify the GPS trigger time in the ini file, for example here is an ini file for running on GW150914

accounting = ligo.dev.o4.cbc.pe.bilby

trigger-time = GW150914
label = GW150914
outdir = outdir_GW150914
detectors = [H1, L1]
coherence-test = True
duration = 4

sampler = dynesty
sampler-kwargs = {'nlive': 1000}

channel-dict = {H1:GWOSC, L1:GWOSC}

create-summary = True
n-parallel = 4

prior-dict = {
mass_1 = Constraint(name='mass_1', minimum=10, maximum=80),
mass_2 = Constraint(name='mass_2', minimum=10, maximum=80),
mass_ratio =  Uniform(name='mass_ratio', minimum=0.125, maximum=1, latex_label="$q$"),
chirp_mass =  Uniform(name='chirp_mass', minimum=25, maximum=40, latex_label="$M_{c}$"),
a_1 = Uniform(name='a_1', minimum=0, maximum=0.99),
a_2 = Uniform(name='a_2', minimum=0, maximum=0.99),
tilt_1 = Sine(name='tilt_1'),
tilt_2 = Sine(name='tilt_2'),
phi_12 = Uniform(name='phi_12', minimum=0, maximum=2 * np.pi, boundary='periodic'),
phi_jl = Uniform(name='phi_jl', minimum=0, maximum=2 * np.pi, boundary='periodic'),
luminosity_distance = PowerLaw(alpha=2, name='luminosity_distance', minimum=50, maximum=2000, unit='Mpc', latex_label='$d_L$'),
dec = Cosine(name='dec'),
ra = Uniform(name='ra', minimum=0, maximum=2 * np.pi, boundary='periodic'),
theta_jn = Sine(name='theta_jn'),
psi =  Uniform(name='psi', minimum=0, maximum=np.pi, boundary='periodic'),
phase =  Uniform(name='phase', minimum=0, maximum=2 * np.pi, boundary='periodic'),
}

Running on GPS times

To run on a list of GPS times, we use gps-file. Here is an example ini file pointing to a gps file:

accounting = ligo.dev.o4.cbc.pe.bilby

label = gps_times
outdir = outdir_gps_times

detectors = [H1, L1]
duration = 4
local-generation = True

prior-file = 4s
sampler = dynesty
injection = False
sampler-kwargs = {nlive: 1000}

channel-dict = {H1:GWOSC, L1:GWOSC}
gps-file = gps_times.txt

The ini file argument gps-file points to a file gps_times.txt which is a simple list of the GPS start times to use. Here are its contents:

1186909218
1186909222
1186909226

The gps-file is a list of GPS start times for each segment. In the example above, a single column of data is used. Multi-column files are also allowed, provided the first column is the gps start times to use (the other columns are ignored).

Alternatively, on can specify the gps start times using a tuple. This is done by passing a tuple of start,step,number. As an example:

accounting = ligo.dev.o4.cbc.pe.bilby

label = gps_times
outdir = outdir_gps_times

detectors = [H1, L1]
duration = 4
local-generation = True

prior-file = 4s
sampler = dynesty
injection = False
sampler-kwargs = {nlive: 1000}

channel-dict = {H1:GWOSC, L1:GWOSC}
gps-file = gps_times.txt

Running on injections in Gaussian noise

bilby_pipe provides a set of tools for creating and analysing an injection set. Here is an example of an ini file for generating and analysing three injections. The injections are generated by drawing n-injection samples from the prior.

################################################################################
## Calibration arguments
################################################################################

calibration-model=None
calibration-correction-type=None
spline-calibration-envelope-dict=None
spline-calibration-nodes=10
spline-calibration-amplitude-uncertainty-dict=None
spline-calibration-phase-uncertainty-dict=None
calibration-prior-boundary=reflective

################################################################################
## Data generation arguments
################################################################################

ignore-gwpy-data-quality-check=True
gps-tuple=None
gps-file=None
timeslide-file=None
timeslide-dict=None
trigger-time=None
n-simulation=1
data-dict=None
data-format=None
allow-tape=True
channel-dict=None
frame-type-dict=None
data-find-url=None
data-find-urltype=osdf
gaussian-noise=True
zero-noise=False

################################################################################
## Detector arguments
################################################################################

coherence-test=False
detectors=[H1, L1]
duration=4.0
generation-seed=None
psd-dict=None
psd-fractional-overlap=0.5
post-trigger-duration=2.0
sampling-frequency=4096
psd-length=32
psd-maximum-duration=1024
psd-method=median
psd-start-time=None
maximum-frequency=None
minimum-frequency=20
tukey-roll-off=0.4
resampling-method=lal

################################################################################
## Injection arguments
################################################################################

injection=True
injection_dict = {
    chirp_mass=35.0,
    mass_ratio=0.5,
    chi_1=0.0,
    chi_2=0.0,
    luminosity_distance=100.0,
    theta_jn=1.4,
    psi_mod_pib2=1.4,
    phase=1.3,
    geocent_time=1126259642.413,
    ra=1.375,
    dec=-1.2108,
}
injection-file=None
injection-numbers=None
injection-waveform-approximant=None
injection-frequency-domain-source-model=None
injection-waveform-arguments=None
injection-waveform-generator-constructor-dict=None

################################################################################
## Job submission arguments
################################################################################

accounting=ligo.dev.o4.cbc.pe.bilby
accounting-user=None
label=bbh_injection
local=False
local-generation=False
generation-pool=local-pool
local-plot=False
outdir=outdir_bbh_injection
overwrite-outdir=False
periodic-restart-time=28800
request-disk=5
request-memory=8.0
request-memory-generation=None
request-cpus=4
conda-env=None
scheduler=condor
scheduler-args=None
scheduler-module=None
scheduler-env=None
scheduler-analysis-time=7-00:00:00
submit=False
condor-job-priority=0
transfer-files=True
additional-transfer-paths=None
environment-variables=None
getenv=None
disable-hdf5-locking=False
log-directory=None
osg=True
desired-sites=None
analysis-executable=None
analysis-executable-parser=None
scitoken-issuer=None
container=None

################################################################################
## Likelihood arguments
################################################################################

calibration-marginalization=False
distance-marginalization=False
distance-marginalization-lookup-table=None
phase-marginalization=False
time-marginalization=False
jitter-time=True
reference-frame=sky
time-reference=geocent
likelihood-type=GravitationalWaveTransient
calibration-lookup-table=None
number-of-response-curves=1000
roq-folder=None
roq-linear-matrix=None
roq-quadratic-matrix=None
roq-weights=None
roq-weight-format=hdf5
roq-scale-factor=1
fiducial-parameters=None
update-fiducial-parameters=False
epsilon=0.025
extra-likelihood-kwargs=None

################################################################################
## Output arguments
################################################################################

plot-trace=False
plot-data=False
plot-injection=False
plot-spectrogram=False
plot-calibration=False
plot-corner=False
plot-marginal=False
plot-skymap=False
plot-waveform=False
plot-format=png
create-summary=False
email=None
notification=Never
queue=None
existing-dir=None
webdir=None
summarypages-arguments=None
result-format=hdf5
final-result=True
final-result-nsamples=20000

################################################################################
## Prior arguments
################################################################################

default-prior=BBHPriorDict
deltaT=0.2
prior-file=bbh_injection.prior
prior-dict=None
enforce-signal-duration=True

################################################################################
## Post processing arguments
################################################################################

postprocessing-executable=None
postprocessing-arguments=None
single-postprocessing-executable=None
single-postprocessing-arguments=None

################################################################################
## Sampler arguments
################################################################################

sampler=dynesty
sampling-seed=None
n-parallel=1
sampler-kwargs={'nlive': 1000, 'naccept': 60, 'check_point_plot': True, 'check_point_delta_t': 1800, 'print_method': 'interval-60', 'sample': 'acceptance-walk', 'npool': 4}
reweighting-configuration=None
reweight-nested-samples=True

################################################################################
## Waveform arguments
################################################################################

waveform-generator=bilby.gw.waveform_generator.LALCBCWaveformGenerator
waveform-generator-constructor-dict=None
reference-frequency=20
waveform-approximant=IMRPhenomPv2
catch-waveform-errors=True
pn-spin-order=-1
pn-tidal-order=-1
pn-phase-order=-1
pn-amplitude-order=0
numerical-relativity-file=None
waveform-arguments-dict=None
mode-array=None
frequency-domain-source-model=lal_binary_black_hole
conversion-function=None
generation-function=None

################################################################################
## Global settings
################################################################################

cosmology=Planck15

Note you need to set the argument gaussian-noise = True if you want to run on an injection. The prior is specified by a bilby prior file bbh_injection.prior:

mass_1 = 50.0
mass_2 = 45.0
a_1 = 0.0
a_2 = 0.0
tilt_1 = 0.0
tilt_2 = 0.0
phi_12 = 0.0
phi_jl = 0.0
luminosity_distance =  bilby.gw.prior.UniformComovingVolume(name='luminosity_distance', minimum=1e2, maximum=5e3, unit='Mpc')
dec = -0.2
ra = 1.4
theta_jn = Sine(name='theta_jn')
psi = 0.0
phase = 0.0
geocent_time = 0.0

Running bilby_pipe with this ini file

$ bilby_pipe bbh_injection.ini

will produce a bilby_pipe injection_file. This can be found in the data directory of the output. It is a simple pandas dataframe stored in the json format containing the parameters of the injection(s).

Running on GraceDB events

The bilby_pipe code itself does not run directly on GraceDB event IDs. Instead, we provide a command line tool bilby_pipe_gracedb which generates ini files and automates the process of determining the relevant prior (the output ini file can subsequently be edited as the user wants).

This command line program automates the retrieval of the trigger time and chirp mass of the event and writes an appropriate ini and prior file based on these parameters.

Using GraceDB ID vs GraceDB event file

The user can pass either a GraceDB ID --gracedb or a json file with the information of a GraceDB event --json of an event to obtain to generate an appropriate ini file (note, the json file should contain the same information that is retrieved from GraceDB using the event ID).

For example, running bilby_pipe_gracedb with the following GraceDB ID

$ bilby_pipe_gracedb --gracedb G298936

will produce an output directory outdir_G298936 with json file G298936.json containing information of the event, an ini file bilby_config.ini with settings appropriate for that event, a prior file, and a complete configuration file G298936_complete_config.ini. By default, this will produce all the subdirectories and submission files required to submit jobs to condor.

If you have a coinc json file for an event with the following format,

{
  "graceid": "G298936",
  "gpstime": 1187529256.517903,
  "pipeline": "gstlal",
  "group": "CBC",
  "extra_attributes": {
    "SingleInspiral": [
      {
        "cont_chisq": 0.0,
        "kappa": 0.0,
        "bank_chisq": 0.0,
        "chisq_dof": 1,
        "end_time_gmst": 40604.9195330854,
        "event_duration": 0.0,
        "chisq": 0.847794,
        "spin1y": 0.0,
        "spin1x": 0.0,
        "spin1z": -0.29820532,
        "coa_phase": -1.6268145,
        "alpha2": 0.0,
        "mchirp": 32.742481,
        "alpha1": 0.0,
        "alpha6": 0.0,
        "alpha4": 0.0,
        "alpha5": 0.0,
        "chi": 0.0,
        "f_final": 542.53412,
        "tau2": 0.0,
        "tau3": 0.55269659,
        "tau0": 1.4108641,
        "tau4": 0.0,
        "tau5": 0.0,
        "template_duration": 2.37429233741786,
        "alpha3": 0.0,
        "impulse_time": 0,
        "impulse_time_ns": 0,
        "rsqveto_duration": 0.0,
        "channel": "GDS-CALIB_STRAIN",
        "mtotal": 83.942345,
        "cont_chisq_dof": 0,
        "search": "",
        "spin2x": 0.0,
        "spin2y": 0.0,
        "beta": 0.0,
        "snr": 6.3536797,
        "bank_chisq_dof": 0,
        "alpha": 0.0,
        "eff_distance": 1296.4589,
        "Gamma7": 0.0,
        "Gamma6": 0.0,
        "Gamma5": 0.0,
        "Gamma4": 0.0,
        "mass1": 59.126324,
        "Gamma2": 0.0,
        "Gamma1": 1269.0,
        "mass2": 24.816019,
        "ttotal": 0.0,
        "Gamma0": 306735.0,
        "spin2z": 0.89852035,
        "Gamma9": 0.0,
        "Gamma8": 0.0,
        "Gamma3": 0.0,
        "eta": 0.20823361,
        "psi0": 0.0,
        "end_time": 1187529256,
        "amplitude": 0.0,
        "psi3": 0.0,
        "end_time_ns": 517029981,
        "ifo": "H1",
        "sigmasq": 67852850.4183298
      },
      {
        "cont_chisq": 0.0,
        "kappa": 0.0,
        "bank_chisq": 0.0,
        "chisq_dof": 1,
        "end_time_gmst": 40604.9195331491,
        "event_duration": 0.0,
        "chisq": 0.76802683,
        "spin1y": 0.0,
        "spin1x": 0.0,
        "spin1z": -0.29820532,
        "coa_phase": 2.179539,
        "alpha2": 0.0,
        "mchirp": 32.742481,
        "alpha1": 0.0,
        "alpha6": 0.0,
        "alpha4": 0.0,
        "alpha5": 0.0,
        "chi": 0.0,
        "f_final": 542.53412,
        "tau2": 0.0,
        "tau3": 0.55269659,
        "tau0": 1.4108641,
        "tau4": 0.0,
        "tau5": 0.0,
        "template_duration": 2.37429233741786,
        "alpha3": 0.0,
        "impulse_time": 0,
        "impulse_time_ns": 0,
        "rsqveto_duration": 0.0,
        "channel": "GDS-CALIB_STRAIN",
        "mtotal": 83.942345,
        "cont_chisq_dof": 0,
        "search": "",
        "spin2x": 0.0,
        "spin2y": 0.0,
        "beta": 0.0,
        "snr": 9.339757,
        "bank_chisq_dof": 0,
        "alpha": 0.0,
        "eff_distance": 1173.8541,
        "Gamma7": 0.0,
        "Gamma6": 0.0,
        "Gamma5": 0.0,
        "Gamma4": 0.0,
        "mass1": 59.126324,
        "Gamma2": 0.0,
        "Gamma1": 1269.0,
        "mass2": 24.816019,
        "ttotal": 0.0,
        "Gamma0": 306735.0,
        "spin2z": 0.89852035,
        "Gamma9": 0.0,
        "Gamma8": 0.0,
        "Gamma3": 0.0,
        "eta": 0.20823361,
        "psi0": 0.0,
        "end_time": 1187529256,
        "amplitude": 0.0,
        "psi3": 0.0,
        "end_time_ns": 517903266,
        "ifo": "L1",
        "sigmasq": 120198605.249805
      }
    ],
    "CoincInspiral": {
      "false_alarm_rate": 0.000263312013118758,
      "mchirp": 32.7424812316895,
      "minimum_duration": 29.4820966720581,
      "mass": 83.9423427581787,
      "end_time": 1187529256,
      "snr": 11.2960305134468,
      "end_time_ns": 517903266,
      "combined_far": 1.73853319852316e-11,
      "ifos": "H1,L1"
    }
  },
  "links": {
    "neighbors": "https://gracedb.ligo.org/api/events/G298936/neighbors/",
    "files": "https://gracedb.ligo.org/api/events/G298936/files/",
    "log": "https://gracedb.ligo.org/api/events/G298936/log/",
    "tags": "https://gracedb.ligo.org/api/events/G298936/tag/",
    "self": "https://gracedb.ligo.org/api/events/G298936",
    "labels": "https://gracedb.ligo.org/api/events/G298936/labels/",
    "emobservations": "https://gracedb.ligo.org/api/events/G298936/emobservation/"
  },
  "created": "2017-08-23 13:14:31 UTC",
  "far": 1.73853319852316e-11,
  "instruments": "H1,L1",
  "labels": [
    "EM_Selected",
    "ADVOK",
    "L1OK",
    "H1OK"
  ],
  "search": "O2VirgoTest",
  "nevents": 2,
  "superevent": null,
  "submitter": "gstlalcbc",
  "offline": false,
  "likelihood": 30.8655826263015,
  "far_is_upper_limit": false
}

by running bilby_pipe_gracedb with the path to the coinc file,

$ bilby_pipe_gracedb --json G298936.json

will also generate an ini file.

Both of the above commands will produce the following ini,

# Configuration ini file generated from GraceDB superevent None
label=G298936
outdir=outdir_G298936
accounting=ligo.dev.o4.cbc.pe.bilby
maximum_frequency=1024.0
minimum_frequency=20.0
sampling_frequency=16384
reference_frequency=100
trigger_time=1187529256.517903
detectors=['H1', 'L1']
channel_dict={'H1': 'GDS-CALIB_STRAIN_CLEAN', 'L1': 'GDS-CALIB_STRAIN_CLEAN', 'V1': 'Hrec_hoft_16384Hz'}
deltaT=0.2
prior_file=outdir_G298936/online.prior
duration=4.0
roq_scale_factor=1.0
sampler=dynesty
sampler_kwargs={nlive: 1000, walks: 390, check_point_plot=True, n_check_point: 10000}
local_generation=True
local_plot=True
transfer_files=False
time_marginalization=True
distance_marginalization=True
phase_marginalization=True
distance_marginalization_lookup_table=PATH/TO/bilby_pipe/data_files/4s_distance_marginalization_lookup.npz
n_parallel=4
create_summary=True
spline_calibration_nodes=10

given we have generated the ini file based on the same event, G298936.

Selecting GraceDB-url

To access GraceDB events the user needs to select the correct service url to retrieve the event details. The service url will point to either the main GraceDB page OR the GraceDB-playground page.

GraceDB url:              "https://gracedb.ligo.org/api/"
GraceDB-playground url:   "https://gracedb-playground.ligo.org/api/"

If a --gracedb-url is not specified the default url is set to https://gracedb.ligo.org/api/

Output methods

There is a flag --output that gives the user four different output options, these include:

ini:         to generate the ini
full:        to generate ini and dag submission files
full-local:  to generate ini and dag submission files and run locally
full-submit: to generate ini and dag submission files and submit to condor

If an --output is not specified the default option is full This will generate an output directory with all the submission files.

Running with specific waveform generator

bilby_pipe provides configuration entries to specify your own waveform generator, for analysis and injection.

The example of the ini file follows the one of injections with gaussian noise, with the addition of the waveform-generator entry. The waveform-generator specifies the class responsible for generating the waveforms for the data generation and analysis steps.

Further instantiation parameters of the class are passed through waveform-generator-constructor-dict and injection-waveform-generator-constructor-dict:

################################################################################
## Calibration arguments
################################################################################

calibration-model=None
calibration-correction-type=None
spline-calibration-envelope-dict=None
spline-calibration-nodes=10
spline-calibration-amplitude-uncertainty-dict=None
spline-calibration-phase-uncertainty-dict=None
calibration-prior-boundary=reflective

################################################################################
## Data generation arguments
################################################################################

ignore-gwpy-data-quality-check=True
gps-tuple=None
gps-file=None
timeslide-file=None
timeslide-dict=None
trigger-time=None
n-simulation=1
data-dict=None
data-format=None
allow-tape=True
channel-dict=None
frame-type-dict=None
data-find-url=None
data-find-urltype=osdf
gaussian-noise=True
zero-noise=False

################################################################################
## Detector arguments
################################################################################

coherence-test=False
detectors=[H1, L1]
duration=4.0
generation-seed=None
psd-dict=None
psd-fractional-overlap=0.5
post-trigger-duration=2.0
sampling-frequency=4096
psd-length=32
psd-maximum-duration=1024
psd-method=median
psd-start-time=None
maximum-frequency=None
minimum-frequency=20
tukey-roll-off=0.4
resampling-method=lal

################################################################################
## Injection arguments
################################################################################

injection=True
injection_dict = {
    chirp_mass=35.0,
    mass_ratio=0.5,
    chi_1=0.0,
    chi_2=0.0,
    luminosity_distance=100.0,
    theta_jn=1.4,
    psi_mod_pib2=1.4,
    phase=1.3,
    geocent_time=1126259642.413,
    ra=1.375,
    dec=-1.2108,
}
injection-file=None
injection-numbers=None
injection-waveform-approximant=None
injection-frequency-domain-source-model=None
injection-waveform-arguments=None
injection-waveform-generator-constructor-dict=None

################################################################################
## Job submission arguments
################################################################################

accounting=ligo.dev.o4.cbc.pe.bilby
accounting-user=None
label=bbh_injection
local=False
local-generation=False
generation-pool=local-pool
local-plot=False
outdir=outdir_bbh_injection_with_wg_constructor
overwrite-outdir=False
periodic-restart-time=28800
request-disk=5
request-memory=8.0
request-memory-generation=None
request-cpus=4
conda-env=None
scheduler=condor
scheduler-args=None
scheduler-module=None
scheduler-env=None
scheduler-analysis-time=7-00:00:00
submit=False
condor-job-priority=0
transfer-files=True
additional-transfer-paths=None
environment-variables=None
getenv=None
disable-hdf5-locking=False
log-directory=None
osg=True
desired-sites=None
analysis-executable=None
analysis-executable-parser=None
scitoken-issuer=None
container=None

################################################################################
## Likelihood arguments
################################################################################

calibration-marginalization=False
distance-marginalization=False
distance-marginalization-lookup-table=None
phase-marginalization=False
time-marginalization=False
jitter-time=True
reference-frame=sky
time-reference=geocent
likelihood-type=GravitationalWaveTransient
calibration-lookup-table=None
number-of-response-curves=1000
roq-folder=None
roq-linear-matrix=None
roq-quadratic-matrix=None
roq-weights=None
roq-weight-format=hdf5
roq-scale-factor=1
fiducial-parameters=None
update-fiducial-parameters=False
epsilon=0.025
extra-likelihood-kwargs=None

################################################################################
## Output arguments
################################################################################

plot-trace=False
plot-data=False
plot-injection=False
plot-spectrogram=False
plot-calibration=False
plot-corner=False
plot-marginal=False
plot-skymap=False
plot-waveform=False
plot-format=png
create-summary=False
email=None
notification=Never
queue=None
existing-dir=None
webdir=None
summarypages-arguments=None
result-format=hdf5
final-result=True
final-result-nsamples=20000

################################################################################
## Prior arguments
################################################################################

default-prior=BBHPriorDict
deltaT=0.2
prior-file=bbh_injection.prior
prior-dict=None
enforce-signal-duration=True

################################################################################
## Post processing arguments
################################################################################

postprocessing-executable=None
postprocessing-arguments=None
single-postprocessing-executable=None
single-postprocessing-arguments=None

################################################################################
## Sampler arguments
################################################################################

sampler=dynesty
sampling-seed=None
n-parallel=1
sampler-kwargs={'nlive': 1000, 'naccept': 60, 'check_point_plot': True, 'check_point_delta_t': 1800, 'print_method': 'interval-60', 'sample': 'acceptance-walk', 'npool': 4}
reweighting-configuration=None
reweight-nested-samples=True

################################################################################
## Waveform arguments
################################################################################

waveform-generator=test_wg.specific_waveform_generator.SpecificWaveformGenerator
waveform-generator-constructor-dict={"log_level": "DEBUG", "configuration": {'additional_config1': "template"}}
reference-frequency=20
waveform-approximant=IMRPhenomPv2
catch-waveform-errors=True
pn-spin-order=-1
pn-tidal-order=-1
pn-phase-order=-1
pn-amplitude-order=0
numerical-relativity-file=None
waveform-arguments-dict=None
mode-array=None
frequency-domain-source-model=lal_binary_black_hole
conversion-function=None
generation-function=None

################################################################################
## Global settings
################################################################################

cosmology=Planck15

(the prior file is the same as for the gaussian noise example.)

In order to run the example, the python import mechanisms should be able to find the module and class specified by waveform-generator. This can be done by specifying the PYTHONPATH locally or as part of the ini file.

Running bilby_pipe with this ini file

$ bilby_pipe bbh_injection_with_wg_constructor.ini
# for local submission
$ PYTHONPATH=`pwd`:$PYTHONPATH bilby_pipe bbh_injection_with_wg_constructor.ini --local

will produce a bilby_pipe injection_file. This can be found in the data directory of the output.