From c008c81b6e937da21976d61796ee7d4866b5318a Mon Sep 17 00:00:00 2001 From: alicjapolanska Date: Tue, 14 May 2024 11:26:26 -0400 Subject: [PATCH 1/7] Add harmonic flows full paper. --- README.rst | 33 +++++++++++++++++++-------------- 1 file changed, 19 insertions(+), 14 deletions(-) diff --git a/README.rst b/README.rst index 851ef23..dac9e3a 100644 --- a/README.rst +++ b/README.rst @@ -16,10 +16,12 @@ :target: https://arxiv.org/abs/2207.04037 .. |arxiv3| image:: http://img.shields.io/badge/arXiv-2307.00048-orange.svg?style=flat :target: https://arxiv.org/abs/2307.00048 +.. |arxiv4| image:: http://img.shields.io/badge/arXiv:2405.05969-orange.svg?style=flat + :target: https://arxiv.org/abs/2405.05969 .. .. image:: https://img.shields.io/pypi/pyversions/harmonic.svg .. :target: https://pypi.python.org/pypi/harmonic/ -|github| |tests| |docs| |codecov| |pypi| |licence| |arxiv1| |arxiv2| |arxiv3| +|github| |tests| |docs| |codecov| |pypi| |licence| |arxiv1| |arxiv2| |arxiv3| |arxiv4| .. |logo| image:: ./docs/assets/harm_badge_simple.svg @@ -115,6 +117,22 @@ A BibTeX entry for the paper is: year = 2021 } + +Please *also* cite `Polanska et al. (2024) `_ if using normalizing flow models. + +A BibTeX entry for the paper is: + +.. code-block:: + + @misc{polanska2024learned, + title={Learned harmonic mean estimation of the Bayesian evidence with normalizing flows}, + author={Alicja Polanska and Matthew A. Price and Davide Piras and Alessio Spurio Mancini and Jason D. McEwen}, + year={2024}, + eprint={2405.05969}, + archivePrefix={arXiv}, + primaryClass={astro-ph.IM} + } + Please *also* cite `Spurio Mancini et al. (2022) `_ if this code has been of use in a simulation-based inference project. A BibTeX entry for the paper is: @@ -130,19 +148,6 @@ A BibTeX entry for the paper is: year = {2023} } -Please *also* cite `Polanska et al. (2023) `_ if using normalizing flow models. - -A BibTeX entry for the paper is: - -.. 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 ======= From ba98dc57d283e68bc744bf965d6282dba4e88bec Mon Sep 17 00:00:00 2001 From: alicjapolanska Date: Tue, 14 May 2024 11:44:06 -0400 Subject: [PATCH 2/7] Correct typo. --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index dac9e3a..2d6abd0 100644 --- a/README.rst +++ b/README.rst @@ -16,7 +16,7 @@ :target: https://arxiv.org/abs/2207.04037 .. |arxiv3| image:: http://img.shields.io/badge/arXiv-2307.00048-orange.svg?style=flat :target: https://arxiv.org/abs/2307.00048 -.. |arxiv4| image:: http://img.shields.io/badge/arXiv:2405.05969-orange.svg?style=flat +.. |arxiv4| image:: http://img.shields.io/badge/arXiv-2405.05969-orange.svg?style=flat :target: https://arxiv.org/abs/2405.05969 .. .. image:: https://img.shields.io/pypi/pyversions/harmonic.svg .. :target: https://pypi.python.org/pypi/harmonic/ From 155b8c62ef42bb63f2c9964a29235f90e63c3d71 Mon Sep 17 00:00:00 2001 From: alicjapolanska Date: Tue, 14 May 2024 11:47:17 -0400 Subject: [PATCH 3/7] Change build instructions. --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index 2d6abd0..12efadc 100644 --- a/README.rst +++ b/README.rst @@ -73,7 +73,7 @@ and running the install script, within the root directory, with one command .. code-block:: bash - bash build_harmonic.sh + pip install . To check the install has worked correctly run the unit tests with From af929542f5e4909616bce9831d4f28868e240876 Mon Sep 17 00:00:00 2001 From: alicjapolanska Date: Tue, 14 May 2024 11:49:26 -0400 Subject: [PATCH 4/7] Update installation phrasing. --- README.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.rst b/README.rst index 12efadc..c066891 100644 --- a/README.rst +++ b/README.rst @@ -69,7 +69,7 @@ The ``harmonic`` package can also be installed from source by running git clone https://github.com/astro-informatics/harmonic cd harmonic -and running the install script, within the root directory, with one command +and installing within the root directory, with one command .. code-block:: bash From 41ece0c2488f62bac00e077261d25fa6d2b948f9 Mon Sep 17 00:00:00 2001 From: alicjapolanska Date: Tue, 14 May 2024 12:12:48 -0400 Subject: [PATCH 5/7] Update documentation with new flows paper and build instructions --- docs/index.rst | 5 ++++- docs/user_guide/install.rst | 2 +- 2 files changed, 5 insertions(+), 2 deletions(-) diff --git a/docs/index.rst b/docs/index.rst index 6072463..95722d8 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -1,4 +1,4 @@ -|GitHub| |Build Status| |Docs| |CodeCov| |PyPI| |GPL license| |ArXiv1| |ArXiv2| |ArXiv3| +|GitHub| |Build Status| |Docs| |CodeCov| |PyPI| |GPL license| |ArXiv1| |ArXiv2| |ArXiv3| |ArXiv4| .. |GitHub| image:: https://img.shields.io/badge/GitHub-harmonic-brightgreen.svg?style=flat :target: https://github.com/astro-informatics/harmonic @@ -18,6 +18,9 @@ .. |ArXiv3| image:: http://img.shields.io/badge/arXiv-2307.00048-orange.svg?style=flat :target: https://arxiv.org/abs/2307.00048 +.. |ArXiv4| image:: http://img.shields.io/badge/arXiv-2405.05969-orange.svg?style=flat + :target: https://arxiv.org/abs/2405.05969 + .. |GPL license| image:: https://img.shields.io/badge/License-GPL-blue.svg :target: http://perso.crans.org/besson/LICENSE.html diff --git a/docs/user_guide/install.rst b/docs/user_guide/install.rst index 1f3e57b..d482b7c 100644 --- a/docs/user_guide/install.rst +++ b/docs/user_guide/install.rst @@ -38,7 +38,7 @@ Once within a fresh environment **harmonic** may be installed by cloning the Git git clone https://github.com/astro-informatics/harmonic cd harmonic -and running the install script, within the root directory, with one command +and installing within the root directory, with one command .. code-block:: bash From c14714a8c8e7825ad68dac4dea14adb74f112b51 Mon Sep 17 00:00:00 2001 From: alicjapolanska Date: Tue, 14 May 2024 12:19:06 -0400 Subject: [PATCH 6/7] Add flows paper and update sampler recommendations. --- .pip_readme.rst | 28 ++++++++++++++++++---------- README.rst | 2 +- 2 files changed, 19 insertions(+), 11 deletions(-) diff --git a/.pip_readme.rst b/.pip_readme.rst index 84fbaef..d9a25b2 100644 --- a/.pip_readme.rst +++ b/.pip_readme.rst @@ -17,6 +17,8 @@ harmonic :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:: http://img.shields.io/badge/arXiv-2405.05969-red.svg?style=flat + :target: https://arxiv.org/abs/2405.05969 **Python package to efficiently compute the learnt harmonic mean estimator of the Bayesian evidence** @@ -24,7 +26,7 @@ harmonic ``harmonic`` is an open source, well tested and documented Python implementation of the *learnt harmonic mean estimator* (`McEwen et al. 2021 `_) to compute the marginal likelihood (Bayesian evidence), required for Bayesian model selection. -While ``harmonic`` requires only posterior samples, and so is agnostic to the technique used to perform Markov chain Monte Carlo (MCMC) sampling, ``harmonic`` works exceptionally well with MCMC sampling techniques that naturally provide samples from multiple chains by their ensemble nature, such as affine invariant ensemble samplers. We therefore advocate use of `harmonic` with the popular `emcee `_ code implementing the affine invariant sampler of `Goodman & Weare (2010) `_. +While ``harmonic`` requires only posterior samples, and so is agnostic to the technique used to perform Markov chain Monte Carlo (MCMC) sampling, ``harmonic`` works well with MCMC sampling techniques that naturally provide samples from multiple chains by their ensemble nature, such as affine invariant ensemble samplers. For instance, `harmonic` can be used with the popular `emcee `_ code implementing the affine invariant sampler of `Goodman & Weare (2010) `_, or the `NumPyro `_ code implementing various MCMC algorithms. Basic usage is highlighted in this `interactive demo `_. @@ -50,6 +52,21 @@ A BibTeX entry for the paper is: year = 2021 } +Please *also* cite `Polanska et al. (2024) `_ if using normalizing flow models. + +A BibTeX entry for the paper is: + +.. code-block:: + + @misc{polanska2024learned, + title={Learned harmonic mean estimation of the Bayesian evidence with normalizing flows}, + author={Alicja Polanska and Matthew A. Price and Davide Piras and Alessio Spurio Mancini and Jason D. McEwen}, + year={2024}, + eprint={2405.05969}, + archivePrefix={arXiv}, + primaryClass={astro-ph.IM} + } + Please *also* cite `Spurio Mancini et al. (2022) `_ if this code has been of use in a simulation-based inference project. A BibTeX entry for the paper is: @@ -65,15 +82,6 @@ A BibTeX entry for the paper is: 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/README.rst b/README.rst index c066891..00e941a 100644 --- a/README.rst +++ b/README.rst @@ -36,7 +36,7 @@ For an accessible overview of the *learnt harmonic mean estimator* please see this `Towards Data Science article `_. -While ``harmonic`` requires only posterior samples, and so is agnostic to the technique used to perform Markov chain Monte Carlo (MCMC) sampling, ``harmonic`` works exceptionally well with MCMC sampling techniques that naturally provide samples from multiple chains by their ensemble nature, such as affine invariant ensemble samplers. We therefore advocate use of `harmonic` with the popular `emcee `_ code implementing the affine invariant sampler of `Goodman & Weare (2010) `_. +While ``harmonic`` requires only posterior samples, and so is agnostic to the technique used to perform Markov chain Monte Carlo (MCMC) sampling, ``harmonic`` works well with MCMC sampling techniques that naturally provide samples from multiple chains by their ensemble nature, such as affine invariant ensemble samplers. For instance, `harmonic` can be used with the popular `emcee `_ code implementing the affine invariant sampler of `Goodman & Weare (2010) `_, or the `NumPyro `_ code implementing various MCMC algorithms. Basic usage is highlighted in this `interactive demo `_. From 978cf27b133fd1402247b6eb50e972a0560739c3 Mon Sep 17 00:00:00 2001 From: alicjapolanska Date: Tue, 14 May 2024 12:26:42 -0400 Subject: [PATCH 7/7] Correct typo. --- .pip_readme.rst | 2 +- README.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/.pip_readme.rst b/.pip_readme.rst index d9a25b2..b2359c5 100644 --- a/.pip_readme.rst +++ b/.pip_readme.rst @@ -26,7 +26,7 @@ harmonic ``harmonic`` is an open source, well tested and documented Python implementation of the *learnt harmonic mean estimator* (`McEwen et al. 2021 `_) to compute the marginal likelihood (Bayesian evidence), required for Bayesian model selection. -While ``harmonic`` requires only posterior samples, and so is agnostic to the technique used to perform Markov chain Monte Carlo (MCMC) sampling, ``harmonic`` works well with MCMC sampling techniques that naturally provide samples from multiple chains by their ensemble nature, such as affine invariant ensemble samplers. For instance, `harmonic` can be used with the popular `emcee `_ code implementing the affine invariant sampler of `Goodman & Weare (2010) `_, or the `NumPyro `_ code implementing various MCMC algorithms. +While ``harmonic`` requires only posterior samples, and so is agnostic to the technique used to perform Markov chain Monte Carlo (MCMC) sampling, ``harmonic`` works well with MCMC sampling techniques that naturally provide samples from multiple chains by their ensemble nature, such as affine invariant ensemble samplers. For instance, ``harmonic`` can be used with the popular `emcee `_ code implementing the affine invariant sampler of `Goodman & Weare (2010) `_, or the `NumPyro `_ code implementing various MCMC algorithms. Basic usage is highlighted in this `interactive demo `_. diff --git a/README.rst b/README.rst index 00e941a..e8068d5 100644 --- a/README.rst +++ b/README.rst @@ -36,7 +36,7 @@ For an accessible overview of the *learnt harmonic mean estimator* please see this `Towards Data Science article `_. -While ``harmonic`` requires only posterior samples, and so is agnostic to the technique used to perform Markov chain Monte Carlo (MCMC) sampling, ``harmonic`` works well with MCMC sampling techniques that naturally provide samples from multiple chains by their ensemble nature, such as affine invariant ensemble samplers. For instance, `harmonic` can be used with the popular `emcee `_ code implementing the affine invariant sampler of `Goodman & Weare (2010) `_, or the `NumPyro `_ code implementing various MCMC algorithms. +While ``harmonic`` requires only posterior samples, and so is agnostic to the technique used to perform Markov chain Monte Carlo (MCMC) sampling, ``harmonic`` works well with MCMC sampling techniques that naturally provide samples from multiple chains by their ensemble nature, such as affine invariant ensemble samplers. For instance, ``harmonic`` can be used with the popular `emcee `_ code implementing the affine invariant sampler of `Goodman & Weare (2010) `_, or the `NumPyro `_ code implementing various MCMC algorithms. Basic usage is highlighted in this `interactive demo `_.