diff --git a/bilby/__init__.py b/bilby/__init__.py
index eff33090a25b4c0147cce0166ac9b4ddbe433705..4b6ac0f52bfae1798ca6bf338f92294c0a96606b 100644
--- a/bilby/__init__.py
+++ b/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.
diff --git a/bilby/core/prior/dict.py b/bilby/core/prior/dict.py
index a6be2ba737559309a0ae819571944740115172df..abb54e67b523390e81c7211d6435e2fe764ca565 100644
--- a/bilby/core/prior/dict.py
+++ b/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
----------
diff --git a/docs/bilby-output.txt b/docs/bilby-output.txt
index 4426dd010d855b68cf3e79ff17870ba848242429..ed5cc8b64307977fcd53809e88123881bc667c5b 100644
--- a/docs/bilby-output.txt
+++ b/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>`_.
diff --git a/docs/dynesty-guide.txt b/docs/dynesty-guide.txt
index fb74c7c7791b97a0370409ff010c7475f6baaa88..194326d7b32e0fb6a5a64d5d385512386b416666 100644
--- a/docs/dynesty-guide.txt
+++ b/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
diff --git a/docs/examples.txt b/docs/examples.txt
index bc5c9e9229dc8d5374cf1e805372fc485e0db8a0..e11954fb1fd597388f991ff89c91714eefe9b189 100644
--- a/docs/examples.txt
+++ b/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>`__
diff --git a/docs/gw_prior.txt b/docs/gw_prior.txt
index 1167ec7edf9aa407575b4a37e5e60796095e6874..03c360a52f3beb913feddbad3a6fd323a5e07b9d 100644
--- a/docs/gw_prior.txt
+++ b/docs/gw_prior.txt
@@ -1,32 +1,132 @@
.. 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:
-
-
diff --git a/docs/installation.txt b/docs/installation.txt
index 96dc0f90d1d8cc0ae7a09e0be727b21f28402ecf..7a6a88f7daebd16e28d6dc1420e5eca98f26107e 100644
--- a/docs/installation.txt
+++ b/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.
diff --git a/docs/prior.txt b/docs/prior.txt
index 8e5f2944d1d315edc23cd5af2cd38394dcb828a6..f55aafe76324d984a2e013402477184a96d5170c 100644
--- a/docs/prior.txt
+++ b/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>`_.