From 320b76e7128170438d2b58d276b6518cfcdfebef Mon Sep 17 00:00:00 2001
From: Gregory Ashton <gregory.ashton@ligo.org>
Date: Tue, 25 Jun 2019 16:23:55 +1000
Subject: [PATCH] General improvements to the documentation
- Remove obsolete h5 file discussion
- Close #237 (add reference for detector information)
- Add references for the constants used
- Close #336 (add documentation of the likelihood and reference Thrane &
Talbot)
---
bilby/gw/likelihood.py | 2 +-
docs/bilby-output.txt | 142 +++++++++++++++--------------------------
docs/code-overview.txt | 2 +-
docs/conversion.txt | 8 +--
docs/gw_likelihood.txt | 19 ++++++
docs/gw_references.txt | 17 +++++
docs/index.txt | 2 +
docs/installation.txt | 17 ++---
docs/likelihood.txt | 14 ----
9 files changed, 104 insertions(+), 119 deletions(-)
create mode 100644 docs/gw_likelihood.txt
create mode 100644 docs/gw_references.txt
diff --git a/bilby/gw/likelihood.py b/bilby/gw/likelihood.py
index 407c8002d..e06552413 100644
--- a/bilby/gw/likelihood.py
+++ b/bilby/gw/likelihood.py
@@ -35,7 +35,7 @@ class GravitationalWaveTransient(likelihood.Likelihood):
This is the usual likelihood object to use for transient gravitational
wave parameter estimation. It computes the log-likelihood in the frequency
domain assuming a colored Gaussian noise model described by a power
- spectral density
+ spectral density. See Thrane & Talbot (2019), arxiv.org/abs/1809.02293.
Parameters
diff --git a/docs/bilby-output.txt b/docs/bilby-output.txt
index c38962d57..4cfa59a90 100644
--- a/docs/bilby-output.txt
+++ b/docs/bilby-output.txt
@@ -11,110 +11,74 @@ documents, we'll assume the defaults where used (which are :code:`outdir` and
:code:`label`).
-The raw data
-------------
+The result file
+---------------
-First off, the primary data dump of :code:`bilby` goes into :code:`outdir/label_result.h5`.
-This is a binary file, so isn't human readable, but you can use it using a
-command-line tool :code:`ddls` [#f1]_ (you have this installed already if you have installed
-the :code:`bilby` requirements). To have a look at what is inside run
+First off, the primary data dump of :code:`bilby` goes into
+:code:`outdir/label_result.json`. This is a `JSON file
+<https://en.wikipedia.org/wiki/JSON>`_, so it is human readable. Note, older
+version of bilby used a H5 file, the use of H5 files is still possible in bilby,
+but we recommend using the default JSON format.
+
+Here is an example of the first 10 lines of a result file
.. code-block:: console
- $ ddls outdir/label_result.h5
- /fixed_parameter_keys list
- /fixed_parameter_keys/i0 'dec' (3) [ascii]
- /fixed_parameter_keys/i1 'psi' (3) [ascii]
- /fixed_parameter_keys/i2 'a_2' (3) [ascii]
- /fixed_parameter_keys/i3 'a_1' (3) [ascii]
- /fixed_parameter_keys/i4 'geocent_time' (12) [ascii]
- /fixed_parameter_keys/i5 'phi_jl' (6) [ascii]
- /fixed_parameter_keys/i6 'ra' (2) [ascii]
- /fixed_parameter_keys/i7 'phase' (5) [ascii]
- /fixed_parameter_keys/i8 'phi_12' (6) [ascii]
- /fixed_parameter_keys/i9 'tilt_2' (6) [ascii]
- /fixed_parameter_keys/i10 'tilt_1' (6) [ascii]
- /injection_parameters dict
- /injection_parameters/a_1 0.4 [float64]
- /injection_parameters/a_2 0.3 [float64]
- /injection_parameters/dec -1.2108 [float64]
- /injection_parameters/geocent_time 1126259642.413 [float64]
- /injection_parameters/iota 0.4 [float64]
- /injection_parameters/luminosity_distance 4000.0 [float64]
- /injection_parameters/mass_1 36.0 [float64]
- /injection_parameters/mass_2 29.0 [float64]
- /injection_parameters/phase 1.3 [float64]
- /injection_parameters/phi_12 1.7 [float64]
- /injection_parameters/phi_jl 0.3 [float64]
- /injection_parameters/psi 2.659 [float64]
- /injection_parameters/ra 1.375 [float64]
- /injection_parameters/reference_frequency 50.0 [float64]
- /injection_parameters/tilt_1 0.5 [float64]
- /injection_parameters/tilt_2 1.0 [float64]
- /injection_parameters/waveform_approximant 'IMRPhenomPv2' (12) [ascii]
- /kwargs dict
- /kwargs/bound 'multi' (5) [ascii]
- /kwargs/dlogz 0.1 [float64]
- /kwargs/nlive 1000 [int64]
- /kwargs/sample 'rwalk' (5) [ascii]
- /kwargs/update_interval 600 [int64]
- /kwargs/verbose True [bool]
- /kwargs/walks 20 [int64]
- /label 'basic_tutorial' (14) [ascii]
- /log_bayes_factor 29.570224130853056 [float64]
- /logz -12042.875089354413 [float64]
- /logzerr 0.040985337772488764 [float64]
- /noise_logz -12072.445313485267 [float64]
- /outdir 'outdir' (6) [ascii]
- /parameter_labels list
- /parameter_labels/i0 '$d_L$' (5) [ascii]
- /parameter_labels/i1 '$m_2$' (5) [ascii]
- /parameter_labels/i2 '$m_1$' (5) [ascii]
- /parameter_labels/i3 '$\\iota$' (7) [ascii]
- /posterior DataFrame (4, 15073)
- /search_parameter_keys list
- /search_parameter_keys/i0 'luminosity_distance' (19) [ascii]
- /search_parameter_keys/i1 'mass_2' (6) [ascii]
- /search_parameter_keys/i2 'mass_1' (6) [ascii]
- /search_parameter_keys/i3 'iota' (4) [ascii]
-
-
-This shows the different data that is stored in the :code:`h5` file. You can think of
-the file like a python dictionary - its a bag with lots of different kind of
-data which can be accessed via a :code:`key` (a string). We use `deepdish
-<http://deepdish.io/>`_ to handle the saving of :code:`h5` files in :code:`bilby`. In python,
-you can load any :code:`h5` file and access its contents like a dictionary::
-
- >>> import deepdish
- >>> output = deepdish.io.load('outdir/label_result.h5')
- >>> print(output['logz'])
- -146.23
-
-Here we printed the stored data for the :code:`'logz'` key, but you could equally get
-the :code:`posterior` or any other attribute. For a full list, print the
-`output.keys()`.
+ (base) 15:49 outdir [master]: $ head gaussian_example_result.json
+ {
+ "label": "gaussian_example",
+ "outdir": "/home/user1/bilby/examples/other_examples/outdir",
+ "sampler": "dynesty",
+ "log_evidence": -278.8659756143005,
+ "log_evidence_err": 0.06169580559443693,
+ "log_noise_evidence": NaN,
+ "log_bayes_factor": NaN,
+ "priors": {
+ "mu": "Uniform(minimum=0, maximum=5, name='mu', latex_label='mu', unit=None, boundary=None)",
+ ...
+ ...
+
+
+At its core, the JSON file is a nested set of dictionaries. JSON is a cross
+platform and language agnostic data format. In python, you can read in a JSON
+file like this
+
+.. code-block:: python
+
+ import json
+ with open(filename, "r") as f:
+ data = json.load(f)
+
+ print(In [5]: data.keys())
+ dict_keys(['label', 'outdir', 'sampler', 'log_evidence', 'log_evidence_err', 'log_noise_evidence', 'log_bayes_factor', 'priors', 'posterior', 'injection_parameters', 'meta_data', 'search_parameter_keys', 'fixed_parameter_keys', 'constraint_parameter_keys', 'sampling_time', 'sampler_kwargs', 'use_ratio', 'log_likelihood_evaluations', 'log_prior_evaluations', 'samples', 'nested_samples', 'parameter_labels', 'parameter_labels_with_unit', 'version']))
+
+
+This will read in any properly formatted JSON file. However, JSON by default
+only understands simple data types (str, int, dict, etc). So, complicated things
+like the posterior (which is a pandas dataframe) will exist, but won't be easy
+to use.
Reading in a result file
------------------------
-Rather than reading in the raw :code:`h5` file, may find it more convienient to
-instead load a :code:`*result.h5` as a :code:`bilby` :code:`result` object (i.e., like the output
-of :code:`run_sampler`). To do this::
+Rather than reading in the raw :code:`json` file, you will find it more convienient to
+instead load the data using :code:`bilby`. To do this::
>>> import bilby
- >>> result = bilby.result.read_in_result(outdir=outdir, label=label)
- >>> result = bilby.result.read_in_result(filename='outdir/label_result.h5)
+ >>> result = bilby.result.read_in_result(outdir=outdir, label=label) # OR
+ >>> result = bilby.result.read_in_result(filename='outdir/label_result.json')
Note, these two lines are equivalent, but show two different ways to read in
-the data. Using this method, :code:`result` is now a :code:`bilby.result.Result` instance
-and has all the methods and attributes. So, for example, you could call
-`result.plot_corner()` to generate a corner plot.
+the data. Using this method, :code:`result` is now a
+:code:`bilby.result.Result` instance and has all the methods and attributes.
+So, for example, you could call `result.plot_corner()` to generate a corner
+plot. This method will also read in a :code:`h5` file.
Accessing samples directly
--------------------------
To get the samples for a particular parameter, use::
- >>> result.posterior.[key]
+ >>> result.posterior[key]
where :code:`key` is a string of the parameter name you are interested in. The
`posterior` attribute is a :code:`pandas.DataFrame`, so if you want to return just
@@ -131,7 +95,3 @@ done via::
result.save_posterior_samples()
which will generate a file :code:`outdir/label_posterior.txt`.
-
-
-.. rubric:: Footnotes
-.. [#f1] :code:`ddls` is an acronym for deep-dish ls
diff --git a/docs/code-overview.txt b/docs/code-overview.txt
index 210a1e6a4..74272566c 100644
--- a/docs/code-overview.txt
+++ b/docs/code-overview.txt
@@ -1,5 +1,5 @@
====================
-Code Overview
+Code overview
====================
Below is a flowchart showing the dependency of different packages and modules within Bilby.
diff --git a/docs/conversion.txt b/docs/conversion.txt
index d15671aa9..d77353722 100644
--- a/docs/conversion.txt
+++ b/docs/conversion.txt
@@ -1,6 +1,6 @@
-========================
-GW Parameter Conversions
-========================
+==================================================
+Transient gravitational wave parameter conversions
+==================================================
Sometimes it is useful to sample in some parameters and return others in the output.
E.g., sampling in chirp mass and mass ratio can be much more efficient than sampling in component masses.
@@ -14,4 +14,4 @@ These are used in multiple places:
For CBCs either `generate_all_bbh_parameters` or `generate_all_bns_parameters` can be used.
.. automodule:: bilby.gw.conversion
- :members:
\ No newline at end of file
+ :members:
diff --git a/docs/gw_likelihood.txt b/docs/gw_likelihood.txt
new file mode 100644
index 000000000..930594840
--- /dev/null
+++ b/docs/gw_likelihood.txt
@@ -0,0 +1,19 @@
+=======================================
+Transient gravitational wave likelihood
+=======================================
+
+The likelihood for gravitational waves transient analysis is
+:code:`GravitationalWaveTransient`:
+
+.. autoclass:: bilby.gw.likelihood.GravitationalWaveTransient
+
+The likelihood for gravitational waves transient analysis with an ROQ is
+:code:`ROQGravitationalWaveTransient`:
+
+.. autoclass:: bilby.gw.likelihood.ROQGravitationalWaveTransient
+
+We also provide a simpler likelihood, :code:`BasicGravitationalWaveTransient`:
+
+.. autoclass:: bilby.gw.likelihood.BasicGravitationalWaveTransient
+
+
diff --git a/docs/gw_references.txt b/docs/gw_references.txt
new file mode 100644
index 000000000..a1271bc14
--- /dev/null
+++ b/docs/gw_references.txt
@@ -0,0 +1,17 @@
+==================================================
+Transient gravitational wave reference information
+==================================================
+
+This page collects relevant reference material.
+
+Detector information
+--------------------
+The detectors, implemented in :code:`bilby.gw.detector.interferometer`, are
+defined with respect to https://dcc.ligo.org/LIGO-T980044/public.
+
+Constants
+---------
+All constants used in bilby are defined in :code:`bilby.core.utils` and are
+taken from the `astropy project <https://www.astropy.org/>`_.
+
+
diff --git a/docs/index.txt b/docs/index.txt
index 9847d1de4..e4d2ce7ed 100644
--- a/docs/index.txt
+++ b/docs/index.txt
@@ -18,7 +18,9 @@ Welcome to bilby's documentation!
bilby-output
compact-binary-coalescence-parameter-estimation
transient-gw-data
+ gw_likelihood
conversion
+ gw_references
writing-documentation
hyperparameters
containers
diff --git a/docs/installation.txt b/docs/installation.txt
index dd1c9bd2a..a6ae1a11a 100644
--- a/docs/installation.txt
+++ b/docs/installation.txt
@@ -4,22 +4,23 @@ Installation
.. tabs::
- .. tab:: Pip
+ .. tab:: Conda
.. code-block:: console
- $ pip install bilby
+ $ conda install -c conda-forge bilby
Supported python versions: 2.7, 3.5+.
- .. tab:: Conda
+ .. tab:: Pip
.. code-block:: console
- $ conda install -c conda-forge bilby
+ $ pip install bilby
Supported python versions: 2.7, 3.5+.
+
This will install all requirements for running :code:`bilby` for general
inference problems, including our default sampler `dynesty
<https://dynesty.readthedocs.io/en/latest/>`_. Other samplers will need to be
@@ -30,17 +31,17 @@ wave inference, please additionally run the following commands.
.. tabs::
- .. tab:: Pip
+ .. tab:: Conda
.. code-block:: console
- $ pip install gwpy lalsuite
+ $ conda install -c conda-forge gwpy python-lalsimulation
- .. tab:: Conda
+ .. tab:: Pip
.. code-block:: console
- $ conda install -c conda-forge gwpy python-lalsimulation
+ $ pip install gwpy lalsuite
Install bilby from source
diff --git a/docs/likelihood.txt b/docs/likelihood.txt
index d7edd4278..e6f4e0db0 100644
--- a/docs/likelihood.txt
+++ b/docs/likelihood.txt
@@ -232,20 +232,6 @@ the following common likelihood functions:
.. autoclass:: bilby.core.likelihood.ExponentialLikelihood
:members:
-Likelihood for transient gravitational waves
---------------------------------------------
-
-In the examples above, we show how to write your own likelihood. However, for
-routine gravitational wave data analysis of transient events, we have in built
-likelihoods. The default likelihood we use in the examples is
-`GravitationalWaveTransient`:
-
-.. autoclass:: bilby.gw.likelihood.GravitationalWaveTransient
-
-We also provide a simpler likelihood
-
-.. autoclass:: bilby.gw.likelihood.BasicGravitationalWaveTransient
-
Empty likelihood for subclassing
--------------------------------
--
GitLab