Superplot (arXiv:1603.00555)

This package provides three utilities: superplot_gui, superplot_summary and super_command. There is a manual, arXiv:1603.00555, and extended documentation.

superplot_gui is a Python GUI that makes plots from MultiNest or PolyChord results (or programs that utilize them). It can calculate and plot:

• One- and two-dimensional marginalised posterior pdf and credible regions (including Gaussian kernel density estimation).
• One- and two-dimensional marginalised profile likelihood and confidence intervals.
• Best-fit points.
• Posterior means, medians and modes.
• Three-dimensional scatter plots.

superplot_gui can also:

• Save a plot as a PDF document.
• Write a summary text file containing plot-specific information.
• Export the plot as a pickled object, which can be imported and manipulated in a Python interpreter.

superplot_summary is a command line tool that outputs a table of summary statistics - best-fit, posterior mean and credible regions for each parameter, and overall minimum chi-squared and p-value. super_command is a command-line interface to the plotting functionality in superplot_gui.

If you use Superplot, please cite:

@article{Fowlie:2016hew,
      author         = "Fowlie, Andrew and Bardsley, Michael Hugh",
      title          = "{Superplot: a graphical interface for plotting and analysing MultiNest output}",
      year           = "2016",
      eprint         = "1603.00555",
      archivePrefix  = "arXiv",
      primaryClass   = "physics.data-an",
      reportNumber   = "COEPP-MN-16-5",
      SLACcitation   = "%%CITATION = ARXIV:1603.00555;%%"

}

Installing

Superplot is hosted on the Pypi server. It can be installed via pip:

pip install superplot

Superplot requires Python 2.7+ and uses the following libraries:

• prettytable
• simpleyaml
• appdirs
• pygtk
• numpy
• scipy
• matplotlib
• pandas
• joblib

While pip will attempt to download and build these libraries if they are not installed (with the exception of matplotlib), this can be a lengthy and/or fragile process for pygtk and the scientific libraries. Installation of pygtk, numpy, scipy, matplotlib and pandas via your operating system's package manager, or by installing a scientific python distribution such as Python(x,y) before installing superplot is recommended (and in the case of matplotlib, required).

On Ubuntu, this can be accomplished with the following commands:

sudo apt-get install git python-pip python-numpy python-scipy python-pandas  libfreetype6-dev python-gtk2-dev python-matplotlib

The version of matplotlib supplied by Ubuntu may not be compiled with GTK support. If this is the case, building matplotlib via pip could fix the problem:

pip install --force-reinstall --upgrade matplotlib

Note that Python(x,y) on Windows also ships matplotlib without GTK support - running the above command after installing Python(x,y) also fixes this issue.

Installing on macOS

On macOS, you will need to use homebrew. Specifically, you must install pygtk and matplotlib in homebrew to have proper GTK support:

brew install pygtk
brew install homebrew/python/matplotlib --with-pygtk

Then you should be able to install superplot as usual via pip:

pip install superplot

Running

To run superplot_gui:

python -m superplot.super_gui

To run superplot_summary:

python -m superplot.summary

To run super_command:

python -m superplot.super_command

Superplot will also attempt to install launcher scripts in an OS-appropriate location, i.e. on Ubuntu, ~/.local/bin/superplot_gui and ~/.local/bin/superplot_summary are alternative ways of launching the tools.

Using superplot_gui

A GUI window will appear to select a chain file. Select e.g. the .txt file in the /examples sub-directory. A second GUI window will appear to select an information file. Select e.g. the .info file in the /examples sub-directory. Finally, select the variables and the plot type in the resulting GUI, and click Make Plot.

The buttons etc in the GUI should be self-explanatory. You do not require an .info file - if you don't have one, press cancel when asked for one, and the chain will be labelled in integers (within the GUI, you can change the axis labels etc anyway).

Using superplot_summary

superplot_summary is a command line tool that takes two arguments:

• --data_file: chain file, e.g. the .txt file in the /examples sub-directory
• --info_file: information file, e.g. the .info file in the /examples sub-directory

superplot_summary will then print a table of summary statistics.

Using super_command

super_command is a command line interface to the plotting functionality in superplot_gui that takes multiple arguments; see:

python -m superplot.super_command --help

for usage.

Configuring superplot

On Ubuntu, the superplot configuration files are installed to ~/.local/share/superplot. On windows they can be found in $HOME\AppData\Local\superplot. The location may be platform-dependent. To place files in a directory of your choice:

python -m superplot.create_home_dir -d <path_to_directory>

config.yml contains a range of options controlling the appearance and labelling of plot elements, as well as technical plot options.

The styles/ folder contains a family of matplotlib style sheets giving finer grained control over the appearance of each plot type. default.mplstyle contains the base settings, which can be overridden for individual plot types by editing the corresponding files.

Note that copies of these configuration files are also installed alongside the source code, and will be used if the above files are unavailable.