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.o3.cbc.pe.lalinference

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:DCS-CALIB_STRAIN_C02, L1:DCS-CALIB_STRAIN_C02}

create-plots = True
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),
chirp_mass =  Uniform(name='chirp_mass', minimum=25, maximum=40),
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.o3.cbc.pe.lalinference

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:DCS-CALIB_STRAIN_C02, L1:DCS-CALIB_STRAIN_C02}
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.o3.cbc.pe.lalinference

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:DCS-CALIB_STRAIN_C02, L1:DCS-CALIB_STRAIN_C02}
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.

accounting = ligo.dev.o3.cbc.pe.lalinference

label = bbh_injection
outdir = outdir_bbh_injection

detectors = [H1, L1]
duration = 4

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

prior-file = bbh_injection.prior

injection = True
gaussian-noise = True
n-simulation = 3
n-parallel = 2

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.o3.cbc.pe.lalinference
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}
create_plots=True
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.