Merge branch 'constraint-documentation' into 'master'

update conversion documentation

See merge request !416

docs/conversion.txt

@@ -7,5 +7,11 @@ E.g., sampling in chirp mass and mass ratio can be much more efficient than samp
 
 We have many functions to do this.
 
+These are used in multiple places:
+- `PriorDict`s have a `conversion_function`, for the GW PriorDicts, these are from this module.
+- `WaveformGenerator`s can use a `parameter_conversion`, again these are from this module.
+- A `conversion_function` can be passed to `run_sampler`, this is done as a post-processing step.
+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

docs/prior.txt

@@ -83,11 +83,85 @@ note that this list is incomplete.
    :members:
    :special-members:
 
+-----------------------
 Defining your own prior
-=======================
+-----------------------
 
 You can define your own by subclassing the :code:`bilby.prior.Prior` class.
 
 .. autoclass:: bilby.core.prior.Prior
    :members:
    :special-members:
+
+-----------------
+Prior Constraints
+-----------------
+
+Added v. 0.4.3
+
+This allows cuts to be specified in the prior space.
+
+You can provide the `PriorDict` a `conversion_function` and a set of `Constraint` priors to remove parts of the prior space.
+
+*Note*: after doing this the prior probability will not be normalised.
+
+Simple example
+==============
+
+Sample from uniform distributions in two parameters x and y with the condition x >= y.
+
+First thing: define a function which generates z=x-y from x and y.
+
+.. code:: python
+
+    def convert_x_y_to_z(parameters):
+        """
+        Function to convert between sampled parameters and constraint parameter.
+
+        Parameters
+        ----------
+        parameters: dict
+            Dictionary containing sampled parameter values, 'x', 'y'.
+
+        Returns
+        -------
+        dict: Dictionary with constraint parameter 'z' added.
+        """
+        parameters['z'] = parameters['x'] - parameters['y']
+        return parameters
+
+Create our prior:
+
+.. code:: python
+
+    from bilby.core.prior import PriorDict, Uniform, Constraint
+
+    priors = PriorDict(conversion_function=convert_x_y_to_z)
+    priors['x'] = Uniform(minimum=0, maximum=10)
+    priors['y'] = Uniform(minimum=0, maximum=10)
+    priors['z'] = Constraint(minimum=0, maximum=10)
+
+Sample from this distribution and plot the samples.
+
+.. code:: python
+
+    import matplotlib.pyplot as plt
+
+    samples = priors.sample(1000000)
+    plt.hist2d(samples['x'], samples['y'], bins=100, cmap='Blues')
+    plt.xlabel('$x$')
+    plt.ylabel('$y$')
+    plt.tight_layout()
+    plt.show()
+    plt.close()
+
+------
+
+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.