Gleipnir

<p align="center"> <img width="100" height="100" src="./images/gleipnir_logo_2.png"> </p>

Gleipnir is a python toolkit that provides an easy to use interface for Bayesian parameter inference and model selection using Nested Sampling. It has a built-in implementation of the Nested Sampling algorithm but also provides a common interface to the Nested Sampling implementations MultiNest, PolyChord, dyPolyChord, DNest4, and Nestle. Although Gleipnir provides a general framework for running Nested Sampling simulations, it was created with biological models in mind. It therefore supplies additional tools for working with biological models in the PySB format (see the PySB Utilities section). Likewise, Gleipnir's API was designed to be familiar to users of PyDREAM and simplePSO, which are primarily used for biological model calibration.

What is Nested Sampling?

Nested Sampling is a numerical integration scheme for estimating the marginal likelihood, or in Nested Sampling parlance, the 'evidence' of high-dimensional models. As a side-effect of the evidence calculation, estimates of the posterior probability distributions of model parameters can also be generated.

In particular, Nested Sampling was designed to handle evaluate the evidence of high-dimensional models where the likelihood is exponentially localized in the prior probability mass. In the Nested Sampling approach, the evidence is first converted from a (possibly) multi-dimensional integral into a one-dimensional integral taken over a mapping of the likelihood function to elements of the unit prior probability mass (X). In principle, this is achieved by using a top-down approach in which sample points are drawn according to the prior distribution, and the unit prior probability is subdivided into equal fractional elements from X = 1 down to X = 0 and mapped to the likelihood function, L(X), via a likelihood sorting routine.

The Nested Sampling method was originally developed by John Skilling; see the following references:

1. Skilling, John. "Nested sampling." AIP Conference Proceedings. Vol. 735. No. 1. AIP, 2004.
2. Skilling, John. "Nested sampling for general Bayesian computation." Bayesian analysis 1.4 (2006): 833-859.
3. Skilling, John. "Nested sampling’s convergence." AIP Conference Proceedings. Vol. 1193. No. 1. AIP, 2009.

---

Install

| ! Warning | | :--- | | Gleipnir is still under heavy development and may rapidly change. |

Gleipnir installs as the gleipnir package. It is compatible with Python 3.6.

conda install

Although not absolutely required, we recommend using the Anaconda Python distribution and the conda package manager.

gleipnir can be installed from the terminal using conda:

conda intall -c blakeaw gleipnir

Note that gleipnir has the following core dependencies which will also be installed:

• NumPy
• SciPy
• pandas

Alternatively, for convenience, a gleipnir environment can be downloaded/created that has gleipnir, its core dependencies, as well as several optional/recommended packages; the optional/recommended packages include pysb, hypbuilder, matplotlib, seaborn, and jupyter. From the terminal:

conda env create blakeaw/gleipnir

and then activate it with:

conda activate gleipnir

Additionally, there is another gleipnir environment for linux-64 that can be downloaded/created that has gleipnir, its core dependencies, as well as most of the recommended additional software packages; note that the versions of packages are pinned to exact version numbers in this environment file. From the terminal:

conda env create blakeaw/gleipnir-all-linux64

and then activate it with:

conda activate gleipnir

pip install

You can pip install the gleipnir package from its PyPI package using

pip install gleipnir-ns

or it can be directly sourced from the GitHub repo:

pip install -e git+https://github.com/LoLab-VU/Gleipnir@v0.26.2#egg=gleipnir

However, sourcing from the GitHub repo will not automatically install the core dependencies. You would have to do that separately:

pip install numpy scipy pandas

Recommended additional software

The following software is not required for the basic operation of Gleipnir, but provides extra capabilities and features when installed.

PySB

PySB is needed to run PySB models and it is needed if you want to use the gleipnir.pysb_utilities module:

conda install -c alubbock pysb

HypBuilder

If you want use the HypSelector class from gleipnir.pysb_utilities then you need to have HypBuilder:

conda install -c blakeaw hypbuilder

Jupyter

If you want to run the Jupyter IPython notebooks that come with Gleipnir then you need to install Jupyter:

conda install jupyter

Plotting packages:

We recommend installing Matplotlib and seaborn to generate plots. Note that some of the Gleipnir examples will use these packages if they are installed to generate sample plots. Matplotlib is also needed for one of the Jupyter notebooks.

conda install matplotlib seaborn

MultiNest

If you want to run Nested Sampling simulations using Gleipnir's MultiNest interface class object, MultiNestNestedSampling (from the gleipnir.multinest module), then you will need to install PyMultiNest and MultiNest. Build and install instructions for getting PyMultiNest and MultiNest from source can be found at: http://johannesbuchner.github.io/PyMultiNest/install.html

PyMultiNest is available on PyPI:

pip install pymultinest

Note that in addition to MultiNest, pymultinest requires numpy, scipy, and matplotlib to run. It also optionally requires mpi4py to run MultiNest with MPI parallelization.

You can get a linux-64 conda build of MultiNest from the blakeaw conda channel:

conda install -c blakeaw multinest

Note that this conda build of MultiNest requires packages from the anaconda and conda-forge channels, so you'll need to add them to the channel list in your conda config (.condarc) file. You can also install a build of mpi4py that is compatible with this build of multinest from the blakeaw conda channel:

conda install -c blakeaw mpi4py

Additionally, a separate set of third party instructions for building and installing on Mac OS can be found at: http://astrobetter.com/wiki/MultiNest+Installation+Notes

Also, this PyMultiNest GitHub issue may be helpful if you run into library path problems on Mac OS: https://github.com/JohannesBuchner/PyMultiNest/issues/89

PolyChord

If you want run Nested Sampling simulations using PolyChord via the PolyChordNestedSampling class from the gleipnir.polychord, then you will need to install pypolychord (for PolyChordLite version >= 1.16). Build and install instructions are in the README at: https://github.com/PolyChord/PolyChordLite

However, as per PolyChordLite GitHub Issue 11 there is a version of pypolychord on PyPI which should work for linux-64:

pip install pypolychord

But note that the current version of pypolychord on PyPI (as of 07-01-2019) is not the most recent version, and some of the extra functionality provided by Gleipnir will not work with it.

Special Notes for builds from source on linux-64:

• Installs into your .local/lib python site-packages.
• Requires gfortran (f77 compiler) and lipopenmpi-dev (development libraries for MPI) to build the code.

dyPolyChord

If you want to run Nested Sampling simulations using dyPolyChord using Gleipnir's interface object, dyPolyChordNestedSampling (from the gleipnir.dypolychord module), then you will need to install dyPolyChord (available on PyPI):

pip install dyPolyChord

Note that dyPolyChord requires PolyChord to run, so its use via Gleipnir requires the pypolychord package; see the the previous section. Also note that in addition to PolyChord, dyPolyChord requires numpy, scipy, and nestcheck to run. It also optionally requires mpi4py to run with MPI parallelization. For additional information check out the dyPolyChord documentation.

DNest4

If you want run Nested Sampling simulations using DNest4 via the DNest4NestedSampling class from the gleipnir.dnest4 module, then you will need to get DNest4 and its Python bindings. Instructions for building and installing from source can be