Merge pull request #274 from astro-informatics/feature/documentation

update documentation to support flow models
astro-informatics · Nov 13, 2023 · e0daa83 · e0daa83
2 parents 32c86c3 + d0c9fd4
commit e0daa83
Show file tree

Hide file tree

Showing 16 changed files with 939 additions and 1,816 deletions.
diff --git a/.pip_readme.rst b/.pip_readme.rst
@@ -9,14 +9,14 @@ harmonic
     :target: https://astro-informatics.github.io/harmonic/
 .. image:: https://codecov.io/gh/astro-informatics/harmonic/branch/main/graph/badge.svg?token=1s4SATphHV
     :target: https://codecov.io/gh/astro-informatics/harmonic
-.. .. image:: https://badge.fury.io/py/harmonic.svg
-..     :target: https://badge.fury.io/py/harmonic
 .. image:: https://img.shields.io/badge/License-GPL-blue.svg
     :target: http://perso.crans.org/besson/LICENSE.html
 .. image:: http://img.shields.io/badge/arXiv-2111.12720-orange.svg?style=flat
     :target: https://arxiv.org/abs/2111.12720
-.. .. image:: https://img.shields.io/pypi/pyversions/harmonic.svg
-..     :target: https://pypi.python.org/pypi/harmonic/
+.. image:: http://img.shields.io/badge/arXiv-2207.04037-red.svg?style=flat
+    :target: https://arxiv.org/abs/2207.04037
+.. image:: http://img.shields.io/badge/arXiv-2307.00048-red.svg?style=flat
+    :target: https://arxiv.org/abs/2307.00048
 
 
 **Python package to efficiently compute the learnt harmonic mean estimator of the Bayesian evidence**
@@ -50,6 +50,31 @@ A BibTeX entry for the paper is:
           year = 2021
      }
 
+Please *also* cite `Spurio Mancini et al. (2022) <https://arxiv.org/abs/2207.04037>`_ if this code has been of use in a simulation-based inference project.
+
+A BibTeX entry for the paper is:
+
+.. code-block::
+
+     @article{spurio-mancini:harmonic_sbi,
+        author   = {A.~Spurio Mancini and M.~M.~Docherty and M.~A.~Price and J.~D.~McEwen},
+        doi      = {10.1093/rasti/rzad051},
+        eprint   = {arXiv:2207.04037},
+        journal  = {{RASTI}, in press},
+        title    = {{B}ayesian model comparison for simulation-based inference},
+        year     = {2023}
+     }
+
+.. code-block::
+
+     @inproceedings{polanska:harmonic_nfs_maxent,
+        author    = {A.~Polanska and M.~A.~Price and A.~Spurio Mancini and J.~D.~McEwen},
+        booktitle = {International Workshop on Bayesian Inference and Maximum Entropy Methods in Science and Engineering},
+        eprint    = {arXiv:2307.00048},
+        title     = {Learned harmonic mean estimation of the marginal likelihood with normalizing flows},
+        year      = {2023}
+     }
+
 License
 -------
 
@@ -60,7 +85,8 @@ the non-commercial use condition (see `LICENSE_EXT.txt <https://github.com/astro
 
      harmonic
      Copyright (C) 2021 Jason D. McEwen, Christopher G. R. Wallis, 
-     Matthew A. Price, Matthew M. Docherty & contributors
+     Matthew A. Price, Matthew M. Docherty, Alessio Spurio Mancini, 
+     Alicja Polanska & contributors
 
      This program is released under the GPL-3 license (see LICENSE.txt), 
      subject to a non-commercial use condition (see LICENSE_EXT.txt).

diff --git a/README.rst b/README.rst
@@ -14,6 +14,8 @@
     :target: https://arxiv.org/abs/2111.12720
 .. image:: http://img.shields.io/badge/arXiv-2207.04037-red.svg?style=flat
     :target: https://arxiv.org/abs/2207.04037
+.. image:: http://img.shields.io/badge/arXiv-2307.00048-red.svg?style=flat
+    :target: https://arxiv.org/abs/2307.00048
 .. .. image:: https://img.shields.io/pypi/pyversions/harmonic.svg
 ..     :target: https://pypi.python.org/pypi/harmonic/
 
@@ -115,12 +117,23 @@ A BibTeX entry for the paper is:
 
 .. code-block::
 
-     @article{harmonic_sbi,
-        author = {Spurio Mancini, A. and Docherty, M. M. and Price, M. A. and McEwen, J. D.},
-         title = {{B}ayesian model comparison for simulation-based inference},
-       journal = {ArXiv},
-        eprint = {arXiv:2207.04037},
-          year = 2022
+     @article{spurio-mancini:harmonic_sbi,
+        author   = {A.~Spurio Mancini and M.~M.~Docherty and M.~A.~Price and J.~D.~McEwen},
+        doi      = {10.1093/rasti/rzad051},
+        eprint   = {arXiv:2207.04037},
+        journal  = {{RASTI}, in press},
+        title    = {{B}ayesian model comparison for simulation-based inference},
+        year     = {2023}
+     }
+
+.. code-block::
+
+     @inproceedings{polanska:harmonic_nfs_maxent,
+        author    = {A.~Polanska and M.~A.~Price and A.~Spurio Mancini and J.~D.~McEwen},
+        booktitle = {International Workshop on Bayesian Inference and Maximum Entropy Methods in Science and Engineering},
+        eprint    = {arXiv:2307.00048},
+        title     = {Learned harmonic mean estimation of the marginal likelihood with normalizing flows},
+        year      = {2023}
      }
 
 License

diff --git a/docs/api/flows.rst b/docs/api/flows.rst
@@ -0,0 +1,5 @@
+.. autoclass:: harmonic.flows.RealNVP
+   :members:
+
+.. autoclass:: harmonic.flows.RQSpline
+   :members:
diff --git a/docs/api/index.rst b/docs/api/index.rst
@@ -12,10 +12,18 @@ Automatically generated documentation for **harmonic** APIs. All functionality i
 	.. tab:: Evidence
 
 		.. include:: evidence.rst
+
+	.. tab:: Flows
+
+		.. include:: flows.rst
 
-	.. tab:: Model
+	.. tab:: Models
 
 		.. include:: model.rst
+
+	.. tab:: Legacy Models
+
+		.. include:: model_legacy.rst
 
 	.. tab:: Logs
 

diff --git a/docs/api/model.rst b/docs/api/model.rst
@@ -1,8 +1,3 @@
-.. autoclass:: harmonic.model.HyperSphere
+.. automodule:: harmonic.model
    :members:
 
-.. autoclass:: harmonic.model.KernelDensityEstimate
-   :members:
-
-.. autoclass:: harmonic.model.ModifiedGaussianMixtureModel
-   :members:
diff --git a/docs/api/model_legacy.rst b/docs/api/model_legacy.rst
@@ -0,0 +1,3 @@
+.. automodule:: harmonic.model_legacy
+   :members:
+
Original file line number	Diff line number	Diff line change
		@@ -0,0 +1,3 @@
		.. automodule:: harmonic.model_legacy
		:members: