Package: getdist
GetDist:MCMC sample analysis, plotting and GUIAuthor:Antony LewisHomepage:https://getdist.readthedocs.ioSource:https://github.com/cmbant/getdistReference:https://arxiv.org/abs/1910.13970DescriptionGetDist is a Python package for analysing Monte Carlo samples, including correlated samples
from Markov Chain Monte Carlo (MCMC).Point and click GUI- select chain files, view plots, marginalized constraints, LaTeX tables and morePlotting library- make custom publication-ready 1D, 2D, 3D-scatter, triangle and other plotsNamed parameters- simple handling of many parameters using parameter names, including LaTeX labels and prior boundsOptimized Kernel Density Estimation- automated optimal bandwidth choice for 1D and 2D densities (Botev et al. Improved Sheather-Jones method), with boundary and bias correctionConvergence diagnostics- including correlation length and diagonalized Gelman-Rubin statisticsLaTeX tablesfor marginalized 1D constraintsSee thePlot Gallery and tutorial(run online)
andGetDist Documentation.Getting StartedInstall getdist using pip:$ pip install getdistor from source files using:$ python setup.py installor:$ pip install -e /path/to/source/You can test if things are working using the unit test by running:$ python -m unittest getdist.tests.getdist_testCheck the dependencies listed in the next section are installed. You can then use the getdist module from your scripts, or
use the GetDist GUI (getdist-guicommand).Once installed, the best way to get up to speed is probably to read through
thePlot Gallery and tutorial.DependenciesPython 3.7+matplotlibscipyPySide6 or PySide2 - optional, only needed for GUIWorking LaTeX installation (not essential, only for some plotting/table functions)Python distributions like Anaconda have most of what you need (except for LaTeX).To use theGUIyou need PySide.
See theGUI docsfor suggestions on how to install.Algorithm detailsDetails of kernel density estimation (KDE) algorithms and references are give in the GetDist notesarXiv:1910.13970.Samples file formatGetDist can be used in scripts and interactively with standard numpy arrays
(as in theexamples).
Scripts and theGetDist GUIcan also read parameter sample/chain files in plain text format
(or in the format output by theCobayasampling program).
In general plain text files of the form:xxx_1.txt
xxx_2.txt
...
xxx.paramnames
xxx.rangeswhere “xxx” is some root file name.The .txt files are separate chain files (there can also be just one xxx.txt file). Each row of each sample .txt file is in the formatweight like param1 param2 param3…Theweightgives the number of samples (or importance weight) with these parameters.likegives -log(likelihood), andparam1, param2…are the values of the parameters at the sample point. The first two columns can be 1 and 0 if they are not known or used.The .paramnames file lists the names of the parameters, one per line, optionally followed by a LaTeX label. Names cannot include spaces, and if they end in “*” they are interpreted as derived (rather than MCMC) parameters, e.g.:x1   x_1
y1   y_1
x2   x_2
xy*  x_1+y_1The .ranges file gives hard bounds for the parameters, e.g.:x1  -5 5
x2   0 NNote that not all parameters need to be specified, and “N” can be used to denote that a particular upper or lower limit is unbounded. The ranges are used to determine densities and plot bounds if there are samples near the boundary; if there are no samples anywhere near the boundary the ranges have no affect on plot bounds, which are chosen appropriately for the range of the samples.There can also optionally be a .properties.ini file, which can specifyburn_removed=Tto ensure no burn in is removed, orignore_rows=xto ignore the first
fractionxof the file rows (or ifx > 1, the specified number of rows).Loading samplesTo load an MCSamples object from text files do:from getdist import loadMCSamples
samples = loadMCSamples('/path/to/xxx', settings={'ignore_rows':0.3})Heresettingsgives optional parameter settings for the analysis.ignore_rowsis useful for MCMC chains where you want to
discard some fraction from the start of each chain as burn in (use a number >1 to discard a fixed number of sample lines rather than a fraction).
The MCSamples object can be passed to plot functions, or used to get many results. For example, to plot marginalized parameter densities
for parameter namesx1andx2:from getdist import plots
g = plots.get_single_plotter()
g.plot_2d(samples, ['x1', 'x2'])When you have many different chain files in the same directory,
plotting can work directly with the root file names. For example to comparexandyconstraints
from two chains with root namesxxxandyyy:from getdist import plots
g = plots.get_single_plotter(chain_dir='/path/to/', analysis_settings={'ignore_rows':0.3})
g.plot_2d(['xxx','yyy'], ['x', 'y'])MCSamples objects can also be constructed directly from numpy arrays in memory, see the example
in thePlot Gallery.GetDist scriptIf you have chain files on on disk, you can also quickly calculate convergence and marginalized statistics using thegetdistscript:usage: getdist [-h] [–ignore_rows IGNORE_ROWS] [-V] [ini_file] [chain_root]GetDist sample analyserpositional arguments:ini_file.ini file with analysis settings (optional, if omitted uses defaultschain_rootRoot name of chain to analyse (e.g. chains/test), required unless file_root specified in ini_fileoptional arguments:-h,--helpshow this help message and exit--ignore_rowsIGNORE_ROWSset initial fraction of chains to cut as burn in
(fraction of total rows, or >1 number of rows);
overrides any value in ini_file if set--make_param_fileMAKE_PARAM_FILEProduce a sample distparams.ini file that you can edit
and use when running GetDist-V,--versionshow program’s version number and exitwhereini_fileis optionally a .ini file listingkey=valueparameter option values, and chain_root is the root file name of the chains.
For example:getdist distparams.ini chains/test_chainThis produces a set of files containing parameter means and limits (.margestats), N-D likelihood contour boundaries and best-fit sample (.likestats),
convergence diagnostics (.converge), parameter covariance and correlation (.covmat and .corr), and optionally various simple plotting scripts.
If noini_fileis given, default settings are used. Theignore_rowsoption allows some of the start of each chain file to be removed as burn in.To customize settings you can run:getdist --make_param_file distparams.inito produce the setting file distparams.ini, edit it, then run with your custom settings.GetDist GUIRungetdist-guito run the graphical user interface. This requires PySide, but will run on Windows, Linux and Mac.
It allows you to open a folder of chain files, then easily select, open, plot and compare, as well as viewing standard GetDist outputs and tables.
See theGUI Readme.Using with CosmoMC and CobayaThis GetDist package is general, but is mainly developed for analysing chains from theCosmoMCandCobayasampling programs.
No need to install this package separately if you have a full CosmoMC installation; the Cobaya installation will also install GetDist as a dependency.
Detailed help is available for plotting Planck chains
and using CosmoMC parameter grids in theReadme.CitationYou can refer to the notes:@article{Lewis:2019xzd,
 author         = "Lewis, Antony",
 title          = "{GetDist: a Python package for analysing Monte Carlo
                   samples}",
 year           = "2019",
 eprint         = "1910.13970",
 archivePrefix  = "arXiv",
 primaryClass   = "astro-ph.IM",
 SLACcitation   = "%%CITATION = ARXIV:1910.13970;%%",
 url            = "https://getdist.readthedocs.io"
}and references therein as appropriate.