========
Examples
========

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


Trigger time
------------
The :code:`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

.. literalinclude:: ../examples/event/GW150914.ini


Running on GPS times
--------------------

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

.. literalinclude:: ../examples/gps_times/gps_times_from_file.ini

The ini file argument :code:`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:

.. literalinclude:: ../examples/gps_times/gps_times.txt

The :code:`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 :code:`start,step,number`. As an example:

.. literalinclude:: ../examples/gps_times/gps_times_from_file.ini

Running on injections in Gaussian noise
---------------------------------------

:code:`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 :code:`n-injection`
samples from the prior.

.. literalinclude:: ../examples/injection/bbh_injection.ini

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

.. literalinclude:: ../examples/injection/bbh_injection.prior

Running :code:`bilby_pipe` with this ini file

.. code-block:: console

   $ bilby_pipe bbh_injection.ini

will produce a bilby_pipe :code:`injection_file`. This can be found in the
:code:`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 :code:`bilby_pipe` code itself does not run directly on GraceDB event IDs.
Instead, we provide a command line tool :code:`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 :code:`--gracedb` or a json file with
the information of a GraceDB event :code:`--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 :code:`bilby_pipe_gracedb` with the following GraceDB ID

.. code-block:: console

   $ bilby_pipe_gracedb --gracedb G298936

will produce an output directory :code:`outdir_G298936` with json file 
:code:`G298936.json` containing information of the event, an ini file 
:code:`bilby_config.ini` with settings appropriate for that event, a prior 
file, and a complete configuration file :code:`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,

.. literalinclude:: ../examples/gracedb/G298936.json

by running :code:`bilby_pipe_gracedb` with the path to the coinc file,

.. code-block:: console

   $ bilby_pipe_gracedb --json G298936.json

will also generate an ini file.

Both of the above commands will produce the following ini,

.. literalinclude:: ../examples/gracedb/bilby_config.ini

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.

.. code-block:: text

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

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

Output methods
^^^^^^^^^^^^^^

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

.. code-block:: text

   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 :code:`--output` is not specified the default option is :code:`full`
This will generate an output directory with all the submission files.