================
Using bilby_pipe
================

The primary user-interface for this code is a command line tool
:code:`bilby_pipe` which is available after following the `installation
instructions <installation.txt>`_. To see the help for this tool, run

.. code-block:: console

   $ bilby_pipe --help

(the complete output is given in `bilby_pipe help`_)

To run :code:`bilby_pipe`, you first need to define an define <an ini file
<ini_file.txt>`_; examples for different types of ini files can be found below.

Once you have an ini file (for the purpose of clarity, lets say
:code:`my-run.ini`, you initialize your job with

.. code-block:: console

   $ bilby_pipe my-run.ini

This will produce a directory structure as follows:

.. code-block:: console

   my-run.ini
   outdir/
     -> data/
     -> log_data_analysis/
     -> log_data_generation/
     -> log_results_page/
     -> result/
     -> results_page/
     -> submit/

The first six of these folders will initially be empty, but as the job
progresses will be populated. The :code:`data` directory will contain all the
data to be analyses while :code:`result` will contain the :code:`*result.json`
result files generated by bilby along with any plots. Note that the location to the
`log` and `results_page` folders can be modified.

The final folder, :code:`submit`, contains all the of the DAG submission
scripts. To submit your job, run :code:`condor_submit_dag` giving as a
first argument the file prepended with :code:`dag` under :code:`outdir/submit`
(instructions to do this are printed to the terminal after).
Alternatively, you can initialise and submit your jobs with

.. code-block:: console

   $ bilby_pipe my-run.ini --submit


Summary webpage
---------------

:code:`bilby_pipe` allows the user to visualise the posterior samples through
a 'summary' webpage. This is implemented using `PESummary
<https://git.ligo.org/charlie.hoy/pesummary>`_ (documentation `here
<https://docs.ligo.org/charlie.hoy/pesummary/>`_). 

To generate a summary webpage, the :code:`create-summary` option must be passed
in the configuration file. Additionally, you can specify a web directory where
you would like the output from :code:`PESummary` to be stored; by default this
is placed in :code:`outdir/results_page`. If you are working on an LDG cluster,
then the web directory should be in your public_html. Below is an example of
the additional lines to put in your configuration file to generate 'summary'
webpages:

.. code-block:: text

    create-summary = True
    email = albert.einstein@ligo.org
    webdir = /home/albert.einstein/public_html/project

If you have already generated a webpage in the past using :code:`PESummary`,
then you are able to pass the :code:`existing-dir` options to add further
results files to a single webpage. This includes all histograms for each
results file as well as comparison plots. Below is an example of the additional
lines in the configuration file that will add to an existing webpage:

.. code-block:: text

    create-summary = True
    email = albert.einstein@ligo.org
    existing-dir = /home/albert.einstein/public_html/project


bilby_pipe help
---------------

For reference, here is the full output of
.. code-block:: console

   $ bilby_pipe --help

.. highlight:: none

.. argparse::
   :ref: bilby_pipe.main.create_parser
   :prog: bilby_pipe
   :noepilog: