From 500babfda6e4e9f7ccb13c7190c548601339f2cb Mon Sep 17 00:00:00 2001
From: Gregory Ashton <gregory.ashton@ligo.org>
Date: Tue, 3 Sep 2019 09:07:03 -0500
Subject: [PATCH] Fixup documentation
---
bilby/core/sampler/base_sampler.py | 1 +
bilby/gw/detector/interferometer.py | 11 ++++
bilby/gw/detector/strain_data.py | 1 +
docs/basics-of-parameter-estimation.txt | 6 +-
...inary-coalescence-parameter-estimation.txt | 6 +-
docs/conf.py | 6 +-
docs/containers.txt | 6 +-
docs/examples.txt | 30 +++------
docs/gw_likelihood.txt | 2 +
docs/samplers.txt | 2 +-
docs/transient-gw-data.txt | 66 ++++++++-----------
11 files changed, 66 insertions(+), 71 deletions(-)
diff --git a/bilby/core/sampler/base_sampler.py b/bilby/core/sampler/base_sampler.py
index ccad84046..9ade52fc6 100644
--- a/bilby/core/sampler/base_sampler.py
+++ b/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
diff --git a/bilby/gw/detector/interferometer.py b/bilby/gw/detector/interferometer.py
index dbbbb5629..e87100a06 100644
--- a/bilby/gw/detector/interferometer.py
+++ b/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):
diff --git a/bilby/gw/detector/strain_data.py b/bilby/gw/detector/strain_data.py
index 80c12d164..05499a3d3 100644
--- a/bilby/gw/detector/strain_data.py
+++ b/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')
diff --git a/docs/basics-of-parameter-estimation.txt b/docs/basics-of-parameter-estimation.txt
index 36dd756be..7cf00eeec 100644
--- a/docs/basics-of-parameter-estimation.txt
+++ b/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:
diff --git a/docs/compact-binary-coalescence-parameter-estimation.txt b/docs/compact-binary-coalescence-parameter-estimation.txt
index d15a68c7d..22a043941 100644
--- a/docs/compact-binary-coalescence-parameter-estimation.txt
+++ b/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:
diff --git a/docs/conf.py b/docs/conf.py
index f18aa8a6b..0a8f39f46 100644
--- a/docs/conf.py
+++ b/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.
diff --git a/docs/containers.txt b/docs/containers.txt
index 32a7e82e3..2c454bdd9 100644
--- a/docs/containers.txt
+++ b/docs/containers.txt
@@ -1,8 +1,8 @@
.. _containers:
-==========
-Containers
-==========
+================
+Using Containers
+================
Containers package software together, providing all the neccersery dependencies
to run :code:`bilby`. Using containers can help eliminate
diff --git a/docs/examples.txt b/docs/examples.txt
index ca8c1224d..ca2fb7d05 100644
--- a/docs/examples.txt
+++ b/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>`__
diff --git a/docs/gw_likelihood.txt b/docs/gw_likelihood.txt
index 930594840..b1a90ea1b 100644
--- a/docs/gw_likelihood.txt
+++ b/docs/gw_likelihood.txt
@@ -1,3 +1,5 @@
+.. gw_likelihood:
+
=======================================
Transient gravitational wave likelihood
=======================================
diff --git a/docs/samplers.txt b/docs/samplers.txt
index c497beb6a..d6ea9ee15 100644
--- a/docs/samplers.txt
+++ b/docs/samplers.txt
@@ -82,7 +82,7 @@ PyMultinest
PyPolyChord
===========
-.. autoclass:: bilby.core.sampler.pypolychord.PyPolyChord
+.. autoclass:: bilby.core.sampler.polychord.PyPolyChord
-------------
diff --git a/docs/transient-gw-data.txt b/docs/transient-gw-data.txt
index 5f11d4922..9f076a5eb 100644
--- a/docs/transient-gw-data.txt
+++ b/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
-
--
GitLab