Merge pull request #1 from SebastianBocquet/bigUpdate

Big update: version 0.2.0

CHANGELOG.rst

@@ -1,3 +1,16 @@
+Version 0.2.0:
+  * Option to turn off tick label rotation
+  * Long tick labels are now lined up correctly with their ticks
+  * Option to fine tune position of label relative to tick
+  * Can choose to use 1d or 2d Gaussian sigma contours
+  * scipy is now an optional dependency
+  * Can choose to fill contours and 1d histograms independently
+  * Can plot the actual data-point density underneath the contours
+  * Full control over fonts for labels, ticks, and legend
+  * Use built-in matplotlib LaTex renderer for equations in labels so no LaTex
+    installation is required locally.
+  * Added a new example to the documentation
+
 Version 0.1.1:
   * Prettier truth colors
   * Parameter labels line up even if parameter numbers are very different in size

MANIFEST.in

@@ -1,2 +1,3 @@
 include README.rst
 include LICENSE.txt
+include VERSION.txt

README.rst

@@ -1,14 +1,53 @@
 pygtc.py
 =========
 
-Make a sweet giant triangle confusogram (GTC) plot with just one line of code. A
-GTC is basically a corner (or triangle) plot, but more exciting!
+**What is a Giant Triangle Confusogram?**
 
-Read `the documentation <http://pygtc.readthedocs.io/>`_, or check out `demo.ipynp <https://github.com/SebastianBocquet/pygtc/blob/master/demo.ipynb>`_.
+A Giant-Triangle-Confusogram (GTC, aka triangle plot) is a way of
+displaying the results of a Monte-Carlo Markov Chain (MCMC) sampling or similar
+analysis. (For a discussion of MCMC analysis, see the excellent ``emcee``
+package.) The recovered parameter constraints are displayed on a grid in which
+the diagonal shows the one-dimensional posteriors (and, optionally, priors) and
+the lower-left triangle shows the pairwise projections. You might want to look
+at a plot like this if you are fitting a model to data and want to see the
+parameter covariances along with the priors.
 
-Works great with the output from ``emcee``.
+Here's an example of a GTC with some random data and arbitrary labels::
 
-Install with pip: ``pip install pygtc``
+  pygtc.plotGTC(chains=[samples1,samples2],
+                paramNames=names,
+                chainLabels=chainLabels,
+                truths=truths,
+                truthLabels=truthLabels,
+                priors=priors,
+                paramRanges=paramRanges,
+                figureSize='MNRAS_page')
+
+.. image:: ./docs/_static/demo_files/demo_9_0.png
+
+**But doesn't this already exist in ``corner.py``, ``distUtils``, etc...?**
+
+Although several other packages exists to make such a plot, we were unsatisfied
+with the amount of extra work required to massage the result into something we
+were happy to publish. With ``pygtc``, we hope to take that extra legwork out of
+the equation by providing a package that gives a figure that is publication
+ready on the first try! You should try all the packages and use the one you like
+most; for us, that is ``pygtc``!
+
+Installation
+------------
+For a quick start, you can just use ``pip``. It will install the required
+dependencies for you (``numpy`` and ``matplotlib``)::
+
+  pip install pygtc
+
+For more installation details, see the `documentation <http://pygtc.readthedocs.io/>`_.
+
+Documentation
+-------------
+Documentation is hosted at `ReadTheDocs <http://pygtc.readthedocs.io/>`_,
+or check out `demo.ipynp <https://github.com/SebastianBocquet/pygtc/blob/master/demo.ipynb>`_,
+in this repository, for a working example.
 
 
 Copyright 2016, Sebastian Bocquet and Faustin W. Carter

VERSION.txt

@@ -0,0 +1 @@
+0.2.0

docs/_build/html/.buildinfo

@@ -1,4 +1,4 @@
 # Sphinx build info version 1
 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done.
-config: ae5ccc1fb2c28c8ad29ca4e7dca71a1a
+config: 0758ab82f252a1117865db724ae2a216
 tags: 645f666f9bcd5a90fca523b33c5a78b7

docs/_build/html/_sources/api.txt

@@ -0,0 +1,23 @@
+===
+API
+===
+
+``pygtc`` only has one user-facing function ``pygtc.plotGTC()``, which generates
+the GTC/triangle plot. There are some helper functions that generate the individual
+panels in the main GTC, but ``plotGTC`` has options to access these, so they
+are only minimally documented here.
+
+plotGTC()
+~~~~~~~~~
+.. autofunction :: pygtc.plotGTC
+
+Helper functions
+~~~~~~~~~~~~~~~~
+
+__plot2d()
+----------
+.. autofunction :: pygtc.pygtc.__plot2d()
+
+__plot1d()
+----------
+.. autofunction :: pygtc.pygtc.__plot1d()

docs/_build/html/_sources/demo.txt

@@ -0,0 +1,222 @@
+==============================================
+Example 1: Making a GTC/triangle plot with pygtc
+==============================================
+This example was generated from an IPython notebook!
+
+
+Import dependencies
+===================
+
+.. code:: python
+
+    #If not using a JuPyter notebook, comment out the next two lines
+    %matplotlib inline
+    %config InlineBackend.figure_format = 'retina' # For mac users with Retina display
+
+    from matplotlib import pyplot as plt
+    import numpy as np
+    import pygtc
+
+Generate fake data
+==================
+
+Let's create two sets of fake sample points with 8 dimensions each. Note
+that chains are allowed to have different lengths.
+
+.. code:: python
+
+    # Create Npoints samples from random multivariate, nDim-dimensional Gaussian
+    def create_random_samples(nDim, Npoints):
+        means = np.random.rand(nDim)
+        cov = .5 - np.random.rand(nDim**2).reshape((nDim,nDim))
+        cov = np.triu(cov)
+        cov += cov.T - np.diag(cov.diagonal())
+        cov = np.dot(cov,cov)
+        samples =  np.random.multivariate_normal(means, cov, Npoints)
+        return samples
+
+    # Create two sets of fake data with 8 parameters
+    np.random.seed(0) # To be able to create the same fake data over and over again
+    samples1 = create_random_samples(8, 50000)
+    samples2 = 1+create_random_samples(8, 70000)
+
+Minimal example
+===============
+
+.. code:: python
+
+    GTC = pygtc.plotGTC(chains=[samples1,samples2])
+
+
+
+.. image:: _static/demo_files/demo_5_0.png
+
+
+Complete the figure
+===================
+
+Now let's add: \* axis and data labels \* lines marking some important
+points in parameter space \* Gaussian distributions on the 1d histograms
+that could indicate Gaussian priors we assumed
+
+Note that all these must match number of parameters!
+
+.. code:: python
+
+    # List of parameter names, supports latex
+    # NOTE: For capital greek letters in latex mode, use \mathsf{}
+    names = ['param name',
+             '$B_\mathrm{\lambda}$',
+             '$E$', '$\\lambda$',
+             'C',
+             'D',
+             '$\mathsf{\Omega}$',
+             '$\\gamma$']
+
+    # Labels for the different chains
+    chainLabels = ["data1 $\lambda$",
+                   "data 2"]
+
+    # List of Gaussian curves to plot
+    #(to represent priors): mean, width
+    # Empty () or None if no prior to plot
+    priors = ((2, 1),
+              (-1, 2),
+              (),
+              (0, .4),
+              None,
+              (1,1),
+              None,
+              None)
+
+    # List of truth values, to mark best-fit or input values
+    # NOT a python array because of different lengths
+    # Here we choose two sets of truth values
+    truths = ((4, .5, None, .1, 0, None, None, 0),
+              (None, None, .3, 1, None, None, None, None))
+
+    # Labels for the different truths
+    truthLabels = ( 'the truth',
+                   'also true')
+
+    # Do the magic
+    GTC = pygtc.plotGTC(chains=[samples1,samples2],
+                        paramNames=names,
+                        chainLabels=chainLabels,
+                        truths=truths,
+                        truthLabels=truthLabels,
+                        priors=priors)
+
+
+
+.. image:: _static/demo_files/demo_7_0.png
+
+
+Make figure publication ready
+=============================
+
+-  See how the prior for :math:`B_{\lambda}` is cut off on the left?
+   Let's display :math:`B_\lambda` in the range (-5,4). Also, we could
+   show a narrower range for :math:`\lambda` like (-3,3).
+-  Given that we're showing two sets of truth lines, let's show the line
+   styles in the legend (``legendMarker=True``).
+-  Finally, let's make the figure size publication ready for MNRAS.
+   Given that we're showing eight parameters, we'll want to choose
+   ``figureSize='MNRAS_page'`` and show a full page-width figure.
+-  Save the figure as ``fullGTC.pdf`` and paste it into your
+   publication!
+
+.. code:: python
+
+    # List of parameter ranges to show,
+    # empty () or None to let pyGTC decide
+    paramRanges = (None,
+                   (-5,4),
+                   (),
+                   (-3,3),
+                   None,
+                   None,
+                   None,
+                   None)
+
+    # Do the magic
+    GTC = pygtc.plotGTC(chains=[samples1,samples2],
+                        paramNames=names,
+                        chainLabels=chainLabels,
+                        truths=truths,
+                        truthLabels=truthLabels,
+                        priors=priors,
+                        paramRanges=paramRanges,
+                        figureSize='MNRAS_page',
+                        plotName='fullGTC.pdf')
+
+
+
+.. image:: _static/demo_files/demo_9_0.png
+
+
+Single 2d panel
+===============
+
+See how the covariance between C and D is a ground-breaking result?
+Let's look in more detail! Here, we'll want single-column figures.
+
+.. code:: python
+
+    # Redefine priors and truths
+    priors2d = (None,(1,1))
+    truths2d = (0,None)
+
+    # The 2d panel and the 1d histograms
+    GTC = pygtc.plotGTC(chains=[samples1[:,4:6], samples2[:,4:6]],
+                        paramNames=names[4:6],
+                        chainLabels=chainLabels,
+                        truths=truths2d,
+                        truthLabels=truthLabels[0],
+                        priors=priors2d,
+                        figureSize='MNRAS_column')
+
+    # Only the 2d panel
+    Range2d = ((-3,5),(-3,7)) # To make sure there's enough space for the legend
+
+    GTC = pygtc.plotGTC(chains=[samples1[:,4:6],samples2[:,4:6]],
+                        paramNames=names[4:6],
+                        chainLabels=chainLabels,
+                        truths=truths2d,
+                        truthLabels=truthLabels[0],
+                        priors=priors2d,
+                        paramRanges=Range2d,
+                        figureSize='MNRAS_column',
+                        do1dPlots=False)
+
+
+
+.. image:: _static/demo_files/demo_11_0.png
+
+
+
+.. image:: _static/demo_files/demo_11_1.png
+
+
+Single 1d panel
+===============
+
+Finally, let's just plot the posterior on C
+
+.. code:: python
+
+    # Bit tricky, but remember each data set needs shape of (Npoints, nDim)
+    inputarr = [np.array([samples1[:,4]]).T,
+                np.array([samples2[:,4]]).T]
+    truth1d = [0.]
+    GTC = pygtc.plotGTC(chains=inputarr,
+                        paramNames=names[4],
+                        chainLabels=chainLabels,
+                        truths=truth1d,
+                        truthLabels=truthLabels[0],
+                        figureSize='MNRAS_column',
+                        doOnly1dPlot=True)
+
+
+
+.. image:: _static/demo_files/demo_13_0.png