Merge branch 'fixup-documentation' into 'master'

Fixup documentation

See merge request !583

bilby/core/sampler/base_sampler.py

@@ -569,6 +569,7 @@ class NestedSampler(Sampler):
         the prior constraint here.
 
         Parameters
+        ----------
         theta: array_like
             Parameter values at which to evaluate likelihood
 

bilby/gw/detector/interferometer.py

@@ -113,6 +113,17 @@ class Interferometer(object):
                     float(self.geometry.yarm_azimuth), float(self.geometry.xarm_tilt),
                     float(self.geometry.yarm_tilt))
 
+    def set_strain_data_from_gwpy_timeseries(self, time_series):
+        """ Set the `Interferometer.strain_data` from a gwpy TimeSeries
+
+        Parameters
+        ----------
+        time_series: gwpy.timeseries.timeseries.TimeSeries
+            The data to set.
+
+        """
+        self.strain_data.set_from_gwpy_timeseries(time_series=time_series)
+
     def set_strain_data_from_frequency_domain_strain(
             self, frequency_domain_strain, sampling_frequency=None,
             duration=None, start_time=0, frequency_array=None):

bilby/gw/detector/strain_data.py

@@ -464,6 +464,7 @@ class InterferometerStrainData(object):
         Parameters
         ----------
         time_series: gwpy.timeseries.timeseries.TimeSeries
+            The data to use
 
         """
         logger.debug('Setting data using provided gwpy TimeSeries object')

docs/basics-of-parameter-estimation.txt

@@ -80,12 +80,12 @@ The code
 --------
 
 In the following example, also available under
-`examples/other_examples/linear_regression.py
-<https://git.ligo.org/lscsoft/bilby/tree/master/examples/other_examples/linear_regression.py>`_
+`examples/core_examples/linear_regression.py
+<https://git.ligo.org/lscsoft/bilby/tree/master/examples/core_examples/linear_regression.py>`_
 we will step through the process of generating some simulated data, writing
 a likelihood and prior, and running nested sampling using `bilby`.
 
-.. literalinclude:: /../examples/other_examples/linear_regression.py
+.. literalinclude:: /../examples/core_examples/linear_regression.py
    :language: python
    :linenos:
 

docs/compact-binary-coalescence-parameter-estimation.txt

@@ -3,7 +3,7 @@ Compact binary coalescence parameter estimation
 ===============================================
 
 In `this example
-<https://git.ligo.org/lscsoft/bilby/blob/master/examples/injection_examples/standard_15d_cbc_tutorial.py>`_,
+<https://git.ligo.org/lscsoft/bilby/blob/master/examples/gw_examples/injection_examples/standard_15d_cbc_tutorial.py>`_,
 we demonstrate how to generate simulated data for a binary black hole
 coalescence observed by the two LIGO interferometers at Hanford and Livingston
 for all parameters in the `IMRPhenomPv2` waveform model.
@@ -11,9 +11,9 @@ for all parameters in the `IMRPhenomPv2` waveform model.
 The code will take around 15 hours to run.
 
 For testing, you may prefer to run the `4-parameter CBC tutorial
-<https://git.ligo.org/lscsoft/bilby/blob/master/examples/injection_examples/fast_tutorial.py>`__.
+<https://git.ligo.org/lscsoft/bilby/blob/master/examples/gw_examples/injection_examples/fast_tutorial.py>`__.
 
-.. literalinclude:: /../examples/injection_examples/standard_15d_cbc_tutorial.py
+.. literalinclude:: /../examples/gw_examples/injection_examples/standard_15d_cbc_tutorial.py
    :language: python
    :linenos:
 

docs/conf.py

@@ -48,8 +48,8 @@ master_doc = 'index'
 
 # General information about the project.
 project = u'bilby'
-copyright = u'2018, Paul Lasky'
-author = u'Paul Lasky'
+copyright = u'2019, Greg Ashton'
+author = u'Greg Ashton'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
@@ -61,7 +61,7 @@ fullversion = bilby.__version__.split(':')[0]
 version = '.'.join(fullversion.split('.')[:2])
 
 # The full version, including alpha/beta/rc tags.
-release = fullversion
+release = version
 
 # The language for content autogenerated by Sphinx. Refer to documentation
 # for a list of supported languages.

docs/containers.txt

 .. _containers:
 
-==========
-Containers
-==========
+================
+Using Containers
+================
 
 Containers package software together, providing all the neccersery dependencies
 to run :code:`bilby`. Using containers can help eliminate

docs/examples.txt

@@ -9,30 +9,20 @@ Examples
 
 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>`__
+   -  `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>`__
 
 
 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>`__
+   -  `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_likelihood.txt

+.. gw_likelihood:
+
 =======================================
 Transient gravitational wave likelihood
 =======================================

docs/samplers.txt

@@ -82,7 +82,7 @@ PyMultinest
 PyPolyChord
 ===========
 
-.. autoclass:: bilby.core.sampler.pypolychord.PyPolyChord
+.. autoclass:: bilby.core.sampler.polychord.PyPolyChord
 
 
 -------------

docs/transient-gw-data.txt

@@ -10,30 +10,47 @@ you can load data.
 What is used by the likelihood?
 -------------------------------
 
-First up, the :ref:`likelihood` used for transient gravitational wave searches
-is either :code:`bilby.gw.likelihood.GravitationalWaveTransient` or
-:code:`bilby.gw.likelihood.BasicGravitationalWaveTransient`. Both of these take
+The primary likelihhod for use in transient gravitational wave data analysis
+is the `GravitationalWaveTransient <gw_likelihood.html>`_ . This takes
 an argument `interferometers` which is a list of
 `bilby.gw.detector.Interferometer` objects. These objects know about the
 geometry of the detector, the noise properties of the detector, and the
 segment of data which is to be analysed. In the following, we'll describe
-difference ways to set this data.
+different ways to initilalse a likelihood for gravitational wave data analysis.
 
 Making an Interferometer
 ------------------------
 
-First up, you can easily get one of the known interferometers using this command::
+To make an empty interferometer, for example the Hanford detector::
 
    >>> H1 = bilby.gw.detector.get_empty_interferometer('H1')
 
-By default, these will have power spectral densities based on typical behaviour
-of the detector. The strain data (i.e. the data about the segment of interferomer
-data which we want to analyse) is in an attribute :code:`H1.strain_data`. The
-following is a list of ways to set this strain data.
+By default, these will have power spectral densities based on the expected
+design sensitivity of the detector. The strain data (i.e. the data about the
+segment of interferomer data which we want to analyse) is in an attribute
+:code:`H1.strain_data`. The following is a list of ways to set this strain
+data.
 
 Setting the strain data
 -----------------------
 
+Setting the strain data using gwpy
+==================================
+
+The `gwpy <https://gwpy.github.io/>`_ module is the recommended way to read in
+and manipulate gravitational wave strain data. For example, here is a snippet
+taken from the documentation to obtain the Hanford open date for GW150914::
+
+   >>> from gwpy.timeseries import TimeSeries
+   >>> time_series = TimeSeries.fetch_open_data('H1', 1126259446, 1126259478)
+
+Gwpy provides a complete interface for reading any type of data related to
+gravitational wave strain data. Once you have created your time series, you can
+pass it into your :code:`bilby` interferometer as follows::
+
+   >>> H1.set_strain_data_from_gwpy_time_series(time_series=time_series)
+
+
 Setting the strain data directly
 ================================
 
@@ -60,22 +77,6 @@ Here is the full API:
 .. automethod:: bilby.gw.detector.Interferometer.set_strain_data_from_frequency_domain_strain
 
 
-Setting the strain data from a frame file
-=========================================
-
-To set the data from a frame file, use this method
-
-.. automethod:: bilby.gw.detector.Interferometer.set_strain_data_from_frame_file
-
-Setting the strain data from a channel name
-===========================================
-
-To set the data by specifying the channel name, use this method. It calls 
-:code:`gwpy.TimeSeries.get`, which dynamically accesses either frames on disk, 
-or a remote NDS2 server to find and return data.
-
-.. automethod:: bilby.gw.detector.Interferometer.set_strain_data_from_channel_name
-
 Setting the strain data to be Gaussian noise
 ============================================
 
@@ -88,6 +89,8 @@ method:
 Setting the strain data to be zero noise
 ========================================
 
+You can also set the strain data without any noise at all
+
 .. automethod:: bilby.gw.detector.Interferometer.set_strain_data_from_zero_noise
 
 Injecting a signal
@@ -96,16 +99,3 @@ Injecting a signal
 If you wish to inject a signal into the data, you can use this function
 
 .. automethod:: bilby.gw.detector.Interferometer.inject_signal
-
-Helper functions
-----------------
-
-To help setting things up, we provide a few convienience functions for typical
-operations:
-
-.. autofunction:: bilby.gw.detector.get_interferometer_with_fake_noise_and_injection
-
-.. autofunction:: bilby.gw.detector.get_interferometer_with_open_data
-
-.. autofunction:: bilby.gw.detector.get_event_data
-