Merge branch 'improve-documentation' into 'master'

Minor fixes to bugs/typo's in the documentation

See merge request !823

bilby/__init__.py

@@ -4,7 +4,7 @@ Bilby
 
 Bilby: a user-friendly Bayesian inference library.
 
-The aim of bilby is to provide user friendly interface to perform parameter
+The aim of bilby is to provide a user-friendly interface to perform parameter
 estimation. It is primarily designed and built for inference of compact
 binary coalescence events in interferometric data, but it can also be used for
 more general problems.

bilby/core/prior/dict.py

@@ -16,7 +16,7 @@ from bilby.core.utils import logger, check_directory_exists_and_if_not_mkdir, Bi
 class PriorDict(dict):
     def __init__(self, dictionary=None, filename=None,
                  conversion_function=None):
-        """ A set of priors
+        """ A dictionary of priors
 
         Parameters
         ----------

docs/bilby-output.txt

@@ -2,13 +2,11 @@
 Bilby output
 ============
 
-In this document, we will describe what :code:`bilby` outputs, where it is stored,
-and how you can access it.
-
-When you call :code:`run_sampler`, there are two arguments :code:`outdir` and :code:`label` which
-are used in generating all the file names for saved data. In the rest of these
-documents, we'll assume the defaults where used (which are :code:`outdir` and
-:code:`label`).
+In this document, we will describe what :code:`bilby` outputs, where it is
+stored, and how you can access it.  When you call :code:`run_sampler`, there
+are two arguments :code:`outdir` and :code:`label` which are used in generating
+all the file names for saved data. In the rest of these documents, we'll assume
+the defaults where used (which are :code:`outdir` and :code:`label`).
 
 
 The result file
@@ -97,8 +95,8 @@ done via::
 which will generate a file :code:`outdir/label_posterior.txt`.
 
 
-Visualising the results  
---------------------
+Visualising the results
+-----------------------
 Bilby also provides some useful built-in plotting tools. Some examples on how
 to visualise results using these tools (and  how to extend them) are shown in
 one of the tutorials at `visualising_the_results.ipynb  <https://git.ligo.org/lscsoft/bilby/-/blob/master/examples/tutorials/visualising_the_results.ipynb>`_.

docs/dynesty-guide.txt

@@ -49,34 +49,28 @@ until one of the stopping criteria are reached:
 Bilby-specific implementation details
 -------------------------------------
 
-In Bilby, we have re-implemented the :code:`sample="rwalk"` sample method. In
-dynesty, this method took an argument :code:`walks` which was the fixed number
-of walks to take each time a new point was proposed. In the bilby implementation,
-we still take an argument :code:`walks` which has the new meaning: the minimum
-number of walks to take (this ensures backward compatibility). Meanwhile, we
-add two new arguments
-1. :code:`maxmcmc`: the maximum number of walks to use. This naming is chosen for consistency with other codes. Default is 5000. If this limit is reached, a warning will be printed during sampling.
-2. :code:`nact`: the number of auto-correlation times to use before accepting a point. Default is 5.
-
-The autocorrelation time calculation uses the `emcee
-<https://emcee.readthedocs.io/en/stable/>`_ autocorr methods. For a detailed
-discussion on the topics, see `this post by Dan Foreman-Mackey
-<https://dfm.io/posts/autocorr/>`_.
+In Bilby, we have re-implemented the :code:`sample="rwalk"` sample method (you
+can see exact details by looking at the function
+:code:`bilby.core.sampler.dynesty.sample_rwalk_bilby`. In dynesty, this method
+took an argument :code:`walks` which was the fixed number of walks to take each
+time a new point was proposed. In the bilby implementation, we still take an
+argument :code:`walks` which has the new meaning: the minimum number of walks
+to take (this ensures backward compatibility). Meanwhile, we add two new
+arguments
 
-You can revert to the original dynesty implementation by specifying
-:code:`sample="rwalk_dynesty"`.
+1. :code:`maxmcmc`: the maximum number of walks to use. This naming is chosen for consistency with other codes. Default is 5000. If this limit is reached, a warning will be printed during sampling.
 
-In addition, we also set several kwargs by default
+2. :code:`nact`: the number of auto-correlation times to use before accepting a point.
 
-1. :code:`nwalk` (alias of :code:`nlive`), the number of live poinst. This defaults to 1000.
-2. :code:`facc`: The target acceptance fraction for the 'rwalk'. In dynesty, this defaults 0.5, but in testing we found that a value of 0.2 produced better behaviour at boundaries.
+In general, poor convergance can be resolved by increasing :code:`nact`. For GW
+events, we find a value of 10 is typically okay.  You can revert to the
+original dynesty implementation by specifying :code:`sample="rwalk_dynesty"`.
 
 Understanding the output
 ------------------------
 
 Before sampling begins, you will see a message like this
 
-
 .. code-block:: console
 
    10:42 bilby INFO    : Single likelihood evaluation took 2.977e-03 s

docs/examples.txt

@@ -2,28 +2,26 @@
 Examples
 ========
 
-1. `General inference examples <https://git.ligo.org/lscsoft/bilby/tree/master/examples/core_examples>`_
-   - `A simple Gaussian likelihood <https://git.ligo.org/lscsoft/bilby/blob/master/examples/core_examples/gaussian_example.py>`_: a good example to see how to write your own likelihood.
-   - `Linear regression for unknown noise <https://git.ligo.org/lscsoft/bilby/blob/master/examples/core_examples/linear_regression_unknown_noise.py>`_: fitting to general time-domain data.
+1. `General inference examples <https://git.ligo.org/lscsoft/bilby/tree/master/examples/core_examples>`_:
 
+  * `A simple Gaussian likelihood <https://git.ligo.org/lscsoft/bilby/blob/master/examples/core_examples/gaussian_example.py>`_: a good example to see how to write your own likelihood.
+  * `Linear regression for unknown noise <https://git.ligo.org/lscsoft/bilby/blob/master/examples/core_examples/linear_regression_unknown_noise.py>`_: fitting to general time-domain data.
 
-2. `Examples of injecting and recovering
-   data <https://git.ligo.org/lscsoft/bilby/tree/master/examples/gw_examples/injection_examples>`__
-   -  `4-parameter CBC tutorial <https://git.ligo.org/lscsoft/bilby/blob/master/examples/gw_examples/injection_examples/fast_tutorial.py>`__
-   -  `15-parameter CBC tutorial <https://git.ligo.org/lscsoft/bilby/blob/master/examples/gw_examples/injection_examples/standard_15d_cbc_tutorial.py>`__
-   -  `Create your own source model <https://git.ligo.org/lscsoft/bilby/blob/master/examples/gw_examples/injection_examples/create_your_own_source_model.py>`__
-   -  `Create your own time-domain source model <https://git.ligo.org/lscsoft/bilby/blob/master/examples/gw_examples/injection_examples/create_your_own_time_domain_source_model.py>`__
-   -  `How to specify the prior <https://git.ligo.org/lscsoft/bilby/blob/master/examples/gw_examples/injection_examples/how_to_specify_the_prior.py>`__
-   -  `Using a partially marginalized likelihood <https://git.ligo.org/lscsoft/bilby/blob/master/examples/gw_examples/injection_examples/marginalized_likelihood.py>`__
-   -  `Injecting and recovering a neutron-star equation of state <https://git.ligo.org/lscsoft/bilby/blob/master/examples/gw_examples/injection_examples/bns_eos_example.py>`__
+2. `Examples of injecting and recovering data <https://git.ligo.org/lscsoft/bilby/tree/master/examples/gw_examples/injection_examples>`__:
 
+  * `4-parameter CBC tutorial <https://git.ligo.org/lscsoft/bilby/blob/master/examples/gw_examples/injection_examples/fast_tutorial.py>`__
+  *  `15-parameter CBC tutorial <https://git.ligo.org/lscsoft/bilby/blob/master/examples/gw_examples/injection_examples/standard_15d_cbc_tutorial.py>`__
+  *  `Create your own source model <https://git.ligo.org/lscsoft/bilby/blob/master/examples/gw_examples/injection_examples/create_your_own_source_model.py>`__
+  *  `Create your own time-domain source model <https://git.ligo.org/lscsoft/bilby/blob/master/examples/gw_examples/injection_examples/create_your_own_time_domain_source_model.py>`__
+  *  `How to specify the prior <https://git.ligo.org/lscsoft/bilby/blob/master/examples/gw_examples/injection_examples/how_to_specify_the_prior.py>`__
+  *  `Using a partially marginalized likelihood <https://git.ligo.org/lscsoft/bilby/blob/master/examples/gw_examples/injection_examples/marginalized_likelihood.py>`__
+  *  `Injecting and recovering a neutron-star equation of state <https://git.ligo.org/lscsoft/bilby/blob/master/examples/gw_examples/injection_examples/bns_eos_example.py>`__
 
-3. `Examples using open
-   data <https://git.ligo.org/lscsoft/bilby/tree/master/examples/gw_examples/data_examples>`__
-   -  `Analysing the first Binary Black hole detection, GW150914 <https://git.ligo.org/lscsoft/bilby/blob/master/examples/gw_examples/data_examples/GW150914.py>`__
+3. `Examples using open data <https://git.ligo.org/lscsoft/bilby/tree/master/examples/gw_examples/data_examples>`__:
 
+  * `Analysing the first Binary Black hole detection, GW150914 <https://git.ligo.org/lscsoft/bilby/blob/master/examples/gw_examples/data_examples/GW150914.py>`__
 
-4. `Notebook-style tutorials <https://git.ligo.org/lscsoft/bilby/tree/master/examples/tutorials>`__
+4. `Notebook-style tutorials <https://git.ligo.org/lscsoft/bilby/tree/master/examples/tutorials>`__:
 
-   -  `Comparing different samplers <https://git.ligo.org/lscsoft/bilby/blob/master/examples/tutorials/compare_samplers.ipynb>`__
-   -  `Visualising the output <https://git.ligo.org/lscsoft/bilby/blob/master/examples/tutorials/visualising_the_results.ipynb>`__
+  * `Comparing different samplers <https://git.ligo.org/lscsoft/bilby/blob/master/examples/tutorials/compare_samplers.ipynb>`__
+  * `Visualising the output <https://git.ligo.org/lscsoft/bilby/blob/master/examples/tutorials/visualising_the_results.ipynb>`__

docs/gw_prior.txt

 .. gw_prior:
 
 ===================================
-Transient Graviatiaonal wave priors
+Transient Gravitational wave priors
 ===================================
 
+We provide two base prior dictionaries for binary black hole (BBH) and binary
+neutron star (BNS) systems. These are :code:`bilby.gw.prior.BBHPriorDict` and
+:code:`bilby.gw.prior.BNSPriorDict` respectively. For BBHs this generates all
+the BBH mass parameters so constraints can be placed on any mass parameters.
+For BNSs it also generates the tidal deformability parameters.
+
+You can load in the default priors by running, e.g.
+
+.. code:: python
+
+   >>> prior = bilby.gw.prior.BBHPriorDict()
+
+This prior has a complete set of parameters for a BBH system. You can modify
+this, for example to set a different prior range for the chirp mass
+
+.. code:: python
+
+   >>> prior["chirp_mass"] = bilby.core.prior.Uniform(30, 31, "chirp_mass")
+
+.. note::
+   If you are using a tidal waveform, you need to specify a frequency domain
+   source model which includes tidal effects, e.g.
+
+    .. code:: python
+
+     frequency_domain_source_model=lal_binary_neutron_star
+
+
+Prior files
+===========
+
+As an alternative to specifying the prior in a python script, we also provide
+the ability to use a prior file. For example, given a file :code:`bbh.prior`
+which contains:
+
+.. literalinclude:: /../bilby/gw/prior_files/precessing_spins_bbh.prior
+
+You can load this with
+
+.. code:: python
+
+   prior = bilby.gw.prior.BBHPriorDict("bbh.prior")
+
+Here we see several examples of different types of priors. For those available
+in the :code:`bilby.core.prior` module, you can specify these without a prefix,
+but for other (including any exisiting in your own modules) you need to specify
+the module path.
+
+Aligned spins waveform with tides off
+-------------------------------------
+
+.. literalinclude:: /../bilby/gw/prior_files/aligned_spins_bbh.prior
+
+Aligned spins waveform with tides on
+------------------------------------
+
+.. literalinclude:: /../bilby/gw/prior_files/aligned_spins_bns.prior
+
+Precessing spins waveform with tides off
+----------------------------------------
+
+.. literalinclude:: /../bilby/gw/prior_files/precessing_spins_bbh.prior
+
+Precessing spins waveform with tides on
+---------------------------------------
+
+.. literalinclude:: /../bilby/gw/prior_files/precessing_spins_bns.prior
+
+
+Modifying the prior
+-------------------
+
+Taking the example priors above, you can copy and modify them to suite your
+needs. For example, to fix a parameter to a given value
+
+.. code:: python
+
+  parameter_name = <value>
+
+while to constrain the prior to a certain range , you can use:
+
+.. code:: python
+
+ parameter_name = Constraint(name='parameter_name', minimum=<value>, maximum=<value>)
+
+
+Priors using a Jupyter notebook
+===============================
+
+Bilby saves as output the prior volume sampled. You might also find useful to
+produce priors directly from a Jupyter notebook. You can have a look at one of
+the Bilby tutorials to check how you define and plot priors in a Jupyter notebook:
+`making_priors.ipynb <https://git.ligo.org/lscsoft/bilby/-/blob/master/examples/tutorials/making_priors.ipynb>`_.
+
+Notes on GW-specific priors
+===========================
+
 A Cosmological GW prior, :code:`Cosmological`:
+----------------------------------------------
 
 .. autoclass:: bilby.gw.prior.Cosmological
    :members:
 
 Uniform in Comoving Volume GW Prior (inherited from Cosmological) :code:`UniformComovingVolume`:
+------------------------------------------------------------------------------------------------
 
 .. autoclass:: bilby.gw.prior.UniformComovingVolume
    :members:
 
 Uniform in Source Frame GW Prior :code:`UniformSourceFrame`:
+------------------------------------------------------------
 
 .. autoclass:: bilby.gw.prior.UniformSourceFrame
    :members:
 
 Aligned Spine GW Prior :code:`AlignedSpin`:
+-------------------------------------------
 
 .. autoclass:: bilby.gw.prior.AlignedSpin
    :members:
 
 HealPixMap JointPriorDist (See JointPriors in bilby.core.prior.joint) :code:`HealPixMapPriorDist`:
+--------------------------------------------------------------------------------------------------
 
 .. autoclass:: bilby.gw.prior.HealPixMapPriorDist
    :members:
-
-

docs/installation.txt

@@ -93,7 +93,7 @@ The `requirements.txt
 <https://git.ligo.org/lscsoft/bilby/blob/master/requirements.txt>`_ is a
 minimal set of requirements for using :code:`bilby`. Additionally, we provide:
 
-1.  `optional_requirements.txt
+1. The file `optional_requirements.txt
 <https://git.ligo.org/lscsoft/bilby/blob/master/optional_requirements.txt>`_
 which you should install if you plan to use :code:`bilby` for
 gravitational-wave data analysis.

docs/prior.txt

@@ -30,22 +30,9 @@ simple example that sets a uniform prior for :code:`a`, and a fixed value for
 Notice, that the :code:`latex_label` is optional, but if given will be used
 when generating plots. Latex label strings containing escape characters like :code:`\t`
 should either be preceded by :code:`r'` or include an extra backslash. As an example,
-either :code:`r'$\theta$'` or :code:`'$\\theta$'` is permissable. For a list of 
-recognized escape sequences, see the `python docs <https://docs.python.org/2.0/ref/strings.html>`_. 
+either :code:`r'$\theta$'` or :code:`'$\\theta$'` is permissable. For a list of
+recognized escape sequences, see the `python docs <https://docs.python.org/2.0/ref/strings.html>`_.
 
---------------
-Default priors
---------------
-
-If any model parameter required by the :ref:`likelihood` are not defined in the
-`priors` dictionary passed to :ref:`run_sampler <run_sampler>` then the code
-will try to use a default prior. By default, these are setup for a binary black
-hole and defined in a file like this
-
-.. literalinclude:: /../bilby/gw/prior_files/binary_black_holes.prior
-
-You can define your own default prior and pass a string pointing to that file
-to :ref:`run_sampler <run_sampler>`.
 
 
 --------------------------
@@ -92,7 +79,7 @@ Multivariate Gaussian prior
 
 We provide a prior class for correlated parameters in the form of a
 `multivariate Gaussian distribution <https://en.wikipedia.org/wiki/Multivariate_normal_distribution>`_.
-To set the prior you first must define the distribution using the 
+To set the prior you first must define the distribution using the
 :class:`bilby.core.prior.MultivariateGaussianDist` class. This requires the names of the
 correlated variables, their means, and either the covariance matrix or the correlation
 matrix and standard deviations, e.g.:
@@ -209,72 +196,4 @@ Sample from this distribution and plot the samples.
 
 ------
 
-Gravitational wave priors
-=========================
-
-We provide default conversion functions for the BBH and BNS PriorDicts.
-
-For BBHs this generates all the BBH mass parameters so constraints can be placed on any mass parameters.
-
-For BNSs it also generates the tidal deformability parameters.
-
------------------
-Prior Examples 
------------------
-
-Here we show some examples of prior files for different waveform families.
-To constrain a certain parameter to a fixed value, you just need:
-
-.. code:: python
-
-  parameter_name = <value>
-
-------
-
-To constrain the prior to a certain range , you can use:
-
-.. code:: python
-
- parameter_name = Constraint(name='parameter_name', minimum=<value>, maximum=<value>)
-
-------
-
-Note that to activate the tidal effect you need to specify in your configuration
-file:
-
-.. code:: python
-
- frequency_domain_source_model=lal_binary_neutron_star 
-
-------
-
-
-Aligned spins waveform with tides off
-==============
-
-.. literalinclude:: /../bilby/gw/prior_files/aligned_spins_waveform_tides_off.prior
-
-Aligned spins waveform with tides on
-==============
-
-.. literalinclude:: /../bilby/gw/prior_files/aligned_spins_waveform_tides_on.prior
-
-Precessing spins waveform with tides off
-==============
-
-.. literalinclude:: /../bilby/gw/prior_files/precessing_spins_waveform_tides_off.prior  
-
-Precessing spins waveform with tides on
-==============
-
-.. literalinclude:: /../bilby/gw/prior_files/precessing_spins_waveform_tides_on.prior  
-
-
------------------
-Priors using a Jupyter notebook 
------------------
 
-Bilby saves as output the prior volume sampled. You might also find useful to
-produce priors directly from a Jupyter notebook. You can have a look at one of
-the Bilby tutorials to check how you define and plot priors in a Jupyter notebook:
-`making_priors.ipynb <https://git.ligo.org/lscsoft/bilby/-/blob/master/examples/tutorials/making_priors.ipynb>`_.