Commit 6681ce04 authored by Colm Talbot's avatar Colm Talbot
Browse files

Merge branch 'update-docs' into 'master'

Improve docs

See merge request !915
parents 31439b55 83f856d3
...@@ -10,11 +10,12 @@ ...@@ -10,11 +10,12 @@
# before the next stage begins # before the next stage begins
stages: stages:
- initial
- test - test
- deploy - deploy
.test-python: &test-python .test-python: &test-python
stage: test stage: initial
image: python image: python
before_script: before_script:
# this is required because pytables doesn't use a wheel on py37 # this is required because pytables doesn't use a wheel on py37
...@@ -55,15 +56,30 @@ python-3.7: ...@@ -55,15 +56,30 @@ python-3.7:
- coverage html - coverage html
- coverage-badge -o coverage_badge.svg -f - coverage-badge -o coverage_badge.svg -f
artifacts:
paths:
- coverage_badge.svg
- htmlcov/
docs:
stage: initial
image: quay.io/bilbydev/v2-dockerfile-test-suite-python37
script:
# Make the documentation # Make the documentation
- apt-get -yqq install pandoc
- python -m pip install .
- cd docs - cd docs
- pip install ipykernel ipython jupyter
- cp ../examples/tutorials/*.ipynb ./
- rm basic_ptmcmc_tutorial.ipynb
- rm compare_samplers.ipynb
- rm visualising_the_results.ipynb
- jupyter nbconvert --to notebook --execute *.ipynb --inplace
- make clean - make clean
- make html - make html
artifacts: artifacts:
paths: paths:
- htmlcov/
- coverage_badge.svg
- docs/_build/html/ - docs/_build/html/
# test example on python 3.8 # test example on python 3.8
...@@ -105,7 +121,7 @@ python-3.6-samplers: ...@@ -105,7 +121,7 @@ python-3.6-samplers:
# Test containers are up to date # Test containers are up to date
containers: containers:
stage: test stage: initial
image: quay.io/bilbydev/v2-dockerfile-test-suite-python37 image: quay.io/bilbydev/v2-dockerfile-test-suite-python37
script: script:
- cd containers - cd containers
...@@ -139,7 +155,7 @@ plotting: ...@@ -139,7 +155,7 @@ plotting:
- pytest test/gw/plot_test.py - pytest test/gw/plot_test.py
authors: authors:
stage: test stage: initial
image: quay.io/bilbydev/v2-dockerfile-test-suite-python37 image: quay.io/bilbydev/v2-dockerfile-test-suite-python37
script: script:
- python test/check_author_list.py - python test/check_author_list.py
...@@ -147,6 +163,7 @@ authors: ...@@ -147,6 +163,7 @@ authors:
pages: pages:
stage: deploy stage: deploy
dependencies: dependencies:
- docs
- python-3.7 - python-3.7
script: script:
- mkdir public/ - mkdir public/
...@@ -176,7 +193,7 @@ deploy_release: ...@@ -176,7 +193,7 @@ deploy_release:
precommits-py3.7: precommits-py3.7:
stage: test stage: initial
image: quay.io/bilbydev/v2-dockerfile-test-suite-python37 image: quay.io/bilbydev/v2-dockerfile-test-suite-python37
script: script:
- source activate python37 - source activate python37
......
...@@ -14,7 +14,7 @@ def grid_file_name(outdir, label, gzip=False): ...@@ -14,7 +14,7 @@ def grid_file_name(outdir, label, gzip=False):
""" Returns the standard filename used for a grid file """ Returns the standard filename used for a grid file
Parameters Parameters
---------- ==========
outdir: str outdir: str
Name of the output directory Name of the output directory
label: str label: str
...@@ -23,7 +23,7 @@ def grid_file_name(outdir, label, gzip=False): ...@@ -23,7 +23,7 @@ def grid_file_name(outdir, label, gzip=False):
Set to True to append `.gz` to the extension for saving in gzipped format Set to True to append `.gz` to the extension for saving in gzipped format
Returns Returns
------- =======
str: File name of the output file str: File name of the output file
""" """
if gzip: if gzip:
...@@ -39,7 +39,7 @@ class Grid(object): ...@@ -39,7 +39,7 @@ class Grid(object):
""" """
Parameters Parameters
---------- ==========
likelihood: bilby.likelihood.Likelihood likelihood: bilby.likelihood.Likelihood
priors: bilby.prior.PriorDict priors: bilby.prior.PriorDict
grid_size: int, list, dict grid_size: int, list, dict
...@@ -112,7 +112,7 @@ class Grid(object): ...@@ -112,7 +112,7 @@ class Grid(object):
Marginalize over a list of parameters. Marginalize over a list of parameters.
Parameters Parameters
---------- ==========
log_array: array_like log_array: array_like
A :class:`numpy.ndarray` of log likelihood/posterior values. A :class:`numpy.ndarray` of log likelihood/posterior values.
parameters: list, str parameters: list, str
...@@ -123,7 +123,7 @@ class Grid(object): ...@@ -123,7 +123,7 @@ class Grid(object):
the set of parameter to *not* marginalize over. the set of parameter to *not* marginalize over.
Returns Returns
------- =======
out_array: array_like out_array: array_like
An array containing the marginalized log likelihood/posterior. An array containing the marginalized log likelihood/posterior.
""" """
...@@ -162,7 +162,7 @@ class Grid(object): ...@@ -162,7 +162,7 @@ class Grid(object):
Marginalize the log likelihood/posterior over a single given parameter. Marginalize the log likelihood/posterior over a single given parameter.
Parameters Parameters
---------- ==========
log_array: array_like log_array: array_like
A :class:`numpy.ndarray` of log likelihood/posterior values. A :class:`numpy.ndarray` of log likelihood/posterior values.
name: str name: str
...@@ -171,7 +171,7 @@ class Grid(object): ...@@ -171,7 +171,7 @@ class Grid(object):
A list of parameter names that have not been marginalized over. A list of parameter names that have not been marginalized over.
Returns Returns
------- =======
out: array_like out: array_like
An array containing the marginalized log likelihood/posterior. An array containing the marginalized log likelihood/posterior.
""" """
...@@ -218,14 +218,14 @@ class Grid(object): ...@@ -218,14 +218,14 @@ class Grid(object):
ln likelihood will be fully marginalized over. ln likelihood will be fully marginalized over.
Parameters Parameters
---------- ==========
parameters: str, list, optional parameters: str, list, optional
Name of, or list of names of, the parameter(s) to marginalize over. Name of, or list of names of, the parameter(s) to marginalize over.
not_parameters: str, optional not_parameters: str, optional
Name of, or list of names of, the parameter(s) to not marginalize over. Name of, or list of names of, the parameter(s) to not marginalize over.
Returns Returns
------- =======
array-like: array-like:
The marginalized ln likelihood. The marginalized ln likelihood.
""" """
...@@ -239,14 +239,14 @@ class Grid(object): ...@@ -239,14 +239,14 @@ class Grid(object):
ln posterior will be fully marginalized over. ln posterior will be fully marginalized over.
Parameters Parameters
---------- ==========
parameters: str, list, optional parameters: str, list, optional
Name of, or list of names of, the parameter(s) to marginalize over. Name of, or list of names of, the parameter(s) to marginalize over.
not_parameters: str, optional not_parameters: str, optional
Name of, or list of names of, the parameter(s) to not marginalize over. Name of, or list of names of, the parameter(s) to not marginalize over.
Returns Returns
------- =======
array-like: array-like:
The marginalized ln posterior. The marginalized ln posterior.
""" """
...@@ -260,14 +260,14 @@ class Grid(object): ...@@ -260,14 +260,14 @@ class Grid(object):
likelihood will be fully marginalized over. likelihood will be fully marginalized over.
Parameters Parameters
---------- ==========
parameters: str, list, optional parameters: str, list, optional
Name of, or list of names of, the parameter(s) to marginalize over. Name of, or list of names of, the parameter(s) to marginalize over.
not_parameters: str, optional not_parameters: str, optional
Name of, or list of names of, the parameter(s) to not marginalize over. Name of, or list of names of, the parameter(s) to not marginalize over.
Returns Returns
------- =======
array-like: array-like:
The marginalized likelihood. The marginalized likelihood.
""" """
...@@ -283,14 +283,14 @@ class Grid(object): ...@@ -283,14 +283,14 @@ class Grid(object):
posterior will be fully marginalized over. posterior will be fully marginalized over.
Parameters Parameters
---------- ==========
parameters: str, list, optional parameters: str, list, optional
Name of, or list of names of, the parameter(s) to marginalize over. Name of, or list of names of, the parameter(s) to marginalize over.
not_parameters: str, optional not_parameters: str, optional
Name of, or list of names of, the parameter(s) to not marginalize over. Name of, or list of names of, the parameter(s) to not marginalize over.
Returns Returns
------- =======
array-like: array-like:
The marginalized posterior. The marginalized posterior.
""" """
...@@ -375,7 +375,7 @@ class Grid(object): ...@@ -375,7 +375,7 @@ class Grid(object):
Writes the Grid to a file. Writes the Grid to a file.
Parameters Parameters
---------- ==========
filename: str, optional filename: str, optional
Filename to write to (overwrites the default) Filename to write to (overwrites the default)
overwrite: bool, optional overwrite: bool, optional
...@@ -418,7 +418,7 @@ class Grid(object): ...@@ -418,7 +418,7 @@ class Grid(object):
""" Read in a saved .json grid file """ Read in a saved .json grid file
Parameters Parameters
---------- ==========
filename: str filename: str
If given, try to load from this filename If given, try to load from this filename
outdir, label: str outdir, label: str
...@@ -429,11 +429,11 @@ class Grid(object): ...@@ -429,11 +429,11 @@ class Grid(object):
extension) extension)
Returns Returns
------- =======
grid: bilby.core.grid.Grid grid: bilby.core.grid.Grid
Raises Raises
------- =======
ValueError: If no filename is given and either outdir or label is None ValueError: If no filename is given and either outdir or label is None
If no bilby.core.grid.Grid is found in the path If no bilby.core.grid.Grid is found in the path
......
...@@ -13,7 +13,7 @@ class Likelihood(object): ...@@ -13,7 +13,7 @@ class Likelihood(object):
"""Empty likelihood class to be subclassed by other likelihoods """Empty likelihood class to be subclassed by other likelihoods
Parameters Parameters
---------- ==========
parameters: dict parameters: dict
A dictionary of the parameter names and associated values A dictionary of the parameter names and associated values
""" """
...@@ -28,7 +28,7 @@ class Likelihood(object): ...@@ -28,7 +28,7 @@ class Likelihood(object):
""" """
Returns Returns
------- =======
float float
""" """
return np.nan return np.nan
...@@ -37,7 +37,7 @@ class Likelihood(object): ...@@ -37,7 +37,7 @@ class Likelihood(object):
""" """
Returns Returns
------- =======
float float
""" """
return np.nan return np.nan
...@@ -46,7 +46,7 @@ class Likelihood(object): ...@@ -46,7 +46,7 @@ class Likelihood(object):
"""Difference between log likelihood and noise log likelihood """Difference between log likelihood and noise log likelihood
Returns Returns
------- =======
float float
""" """
return self.log_likelihood() - self.noise_log_likelihood() return self.log_likelihood() - self.noise_log_likelihood()
...@@ -71,7 +71,7 @@ class ZeroLikelihood(Likelihood): ...@@ -71,7 +71,7 @@ class ZeroLikelihood(Likelihood):
""" A special test-only class which already returns zero likelihood """ A special test-only class which already returns zero likelihood
Parameters Parameters
---------- ==========
likelihood: bilby.core.likelihood.Likelihood likelihood: bilby.core.likelihood.Likelihood
A likelihood object to mimic A likelihood object to mimic
...@@ -98,7 +98,7 @@ class Analytical1DLikelihood(Likelihood): ...@@ -98,7 +98,7 @@ class Analytical1DLikelihood(Likelihood):
parameters are inferred from the arguments of function parameters are inferred from the arguments of function
Parameters Parameters
---------- ==========
x, y: array_like x, y: array_like
The data to analyse The data to analyse
func: func:
...@@ -174,7 +174,7 @@ class GaussianLikelihood(Analytical1DLikelihood): ...@@ -174,7 +174,7 @@ class GaussianLikelihood(Analytical1DLikelihood):
parameters are inferred from the arguments of function parameters are inferred from the arguments of function
Parameters Parameters
---------- ==========
x, y: array_like x, y: array_like
The data to analyse The data to analyse
func: func:
...@@ -235,7 +235,7 @@ class PoissonLikelihood(Analytical1DLikelihood): ...@@ -235,7 +235,7 @@ class PoissonLikelihood(Analytical1DLikelihood):
inferred from the arguments of function, which provides a rate. inferred from the arguments of function, which provides a rate.
Parameters Parameters
---------- ==========
x: array_like x: array_like
A dependent variable at which the Poisson rates will be calculated A dependent variable at which the Poisson rates will be calculated
...@@ -291,7 +291,7 @@ class ExponentialLikelihood(Analytical1DLikelihood): ...@@ -291,7 +291,7 @@ class ExponentialLikelihood(Analytical1DLikelihood):
An exponential likelihood function. An exponential likelihood function.
Parameters Parameters
---------- ==========
x, y: array_like x, y: array_like
The data to analyse The data to analyse
...@@ -338,7 +338,7 @@ class StudentTLikelihood(Analytical1DLikelihood): ...@@ -338,7 +338,7 @@ class StudentTLikelihood(Analytical1DLikelihood):
https://en.wikipedia.org/wiki/Student%27s_t-distribution#Generalized_Student's_t-distribution https://en.wikipedia.org/wiki/Student%27s_t-distribution#Generalized_Student's_t-distribution
Parameters Parameters
---------- ==========
x, y: array_like x, y: array_like
The data to analyse The data to analyse
func: func:
...@@ -410,7 +410,7 @@ class Multinomial(Likelihood): ...@@ -410,7 +410,7 @@ class Multinomial(Likelihood):
""" """
Parameters Parameters
---------- ==========
data: array-like data: array-like
The number of objects in each class The number of objects in each class
n_dimensions: int n_dimensions: int
...@@ -454,7 +454,7 @@ class AnalyticalMultidimensionalCovariantGaussian(Likelihood): ...@@ -454,7 +454,7 @@ class AnalyticalMultidimensionalCovariantGaussian(Likelihood):
with known analytic solution. with known analytic solution.
Parameters Parameters
---------- ==========
mean: array_like mean: array_like
Array with the mean values of distribution Array with the mean values of distribution
cov: array_like cov: array_like
...@@ -484,7 +484,7 @@ class AnalyticalMultidimensionalBimodalCovariantGaussian(Likelihood): ...@@ -484,7 +484,7 @@ class AnalyticalMultidimensionalBimodalCovariantGaussian(Likelihood):
with known analytic solution. with known analytic solution.
Parameters Parameters
---------- ==========
mean_1: array_like mean_1: array_like
Array with the mean value of the first mode Array with the mean value of the first mode
mean_2: array_like mean_2: array_like
...@@ -523,7 +523,7 @@ class JointLikelihood(Likelihood): ...@@ -523,7 +523,7 @@ class JointLikelihood(Likelihood):
set consistently set consistently
Parameters Parameters
---------- ==========
*likelihoods: bilby.core.likelihood.Likelihood *likelihoods: bilby.core.likelihood.Likelihood
likelihoods to be combined parsed as arguments likelihoods to be combined parsed as arguments
""" """
......
...@@ -13,7 +13,7 @@ class DeltaFunction(Prior): ...@@ -13,7 +13,7 @@ class DeltaFunction(Prior):
"""Dirac delta function prior, this always returns peak. """Dirac delta function prior, this always returns peak.
Parameters Parameters
---------- ==========
peak: float peak: float
Peak value of the delta function Peak value of the delta function
name: str name: str
...@@ -33,11 +33,11 @@ class DeltaFunction(Prior): ...@@ -33,11 +33,11 @@ class DeltaFunction(Prior):
"""Rescale everything to the peak with the correct shape. """Rescale everything to the peak with the correct shape.
Parameters Parameters
---------- ==========
val: Union[float, int, array_like] val: Union[float, int, array_like]
Returns Returns
------- =======
float: Rescaled probability, equivalent to peak float: Rescaled probability, equivalent to peak
""" """
self.test_valid_for_rescaling(val) self.test_valid_for_rescaling(val)
...@@ -47,11 +47,11 @@ class DeltaFunction(Prior): ...@@ -47,11 +47,11 @@ class DeltaFunction(Prior):
"""Return the prior probability of val """Return the prior probability of val
Parameters Parameters
---------- ==========
val: Union[float, int, array_like] val: Union[float, int, array_like]
Returns Returns
------- =======
Union[float, array_like]: np.inf if val = peak, 0 otherwise Union[float, array_like]: np.inf if val = peak, 0 otherwise
""" """
...@@ -69,7 +69,7 @@ class PowerLaw(Prior): ...@@ -69,7 +69,7 @@ class PowerLaw(Prior):
"""Power law with bounds and alpha, spectral index """Power law with bounds and alpha, spectral index
Parameters Parameters
---------- ==========
alpha: float alpha: float
Power law exponent parameter Power law exponent parameter
minimum: float minimum: float
...@@ -97,12 +97,12 @@ class PowerLaw(Prior): ...@@ -97,12 +97,12 @@ class PowerLaw(Prior):
This maps to the inverse CDF. This has been analytically solved for this case. This maps to the inverse CDF. This has been analytically solved for this case.
Parameters Parameters
---------- ==========
val: Union[float, int, array_like] val: Union[float, int, array_like]
Uniform probability Uniform probability
Returns Returns
------- =======