API¶
pygtc
only has one userfacing 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()¶

pygtc.
plotGTC
(chains, **kwargs)¶ Make a great looking Giant Triangle Confusogram (GTC) with one line of code! A GTC is a lot like a triangle (or corner) plot, but you get to put as many sets of data, and overlay as many truths as you like. That’s what can make it so confusing!
Parameters: chains (arraylike[nSamples,nDims] or a) – list[[nSamples1,nDims], [nSamples2,nDims], …] All chains (where a chain is [nSamples,nDims]) in the list must have the same number of dimensions. Note: If you are using
emcee
(http://dan.iel.fm/emcee/current/)  and you should!  each element of chains is anEnsembleSampler.flatchain
object.Keyword Arguments:  weights (arraylike[nSamples] or a list[[nSamples1], ..]) – Weights for the sample points. The number of 1d arrays passed must correspond to the number of chains, and each weights array must have the same length nSamples as its corresponding chain.
 chainLabels (arraylike[nChains]) – A list of text labels describing each chain passed to chains.
len(chainLabels) must equal len(chains). chainLabels supports LaTex
commands enclosed in $..$. Additionally, you can pass None as a label.
Default is
None
.  paramNames (listlike[nDims]) – A list of text labels describing each dimension of chains.
len(paramNames) must equal nDims=chains[0].shape[1]. paramNames supports
LaTex commands enclosed in $..$. Additionally, you can pass None as a
label. Default is None, however if you pass a
pandas.DataFrame
object, paramNames defaults to theDataFrame
column names.  truths (listlike[nDims] or [[nDims], ..]) – A list of parameter values, one for each parameter in chains to
highlight in the GTC parameter space, or a list of lists of values to
highlight in the parameter space. For each set of truths passed to
truths, there must be a value corresponding to every dimension in
chains, although any value may be
None
. Default isNone
.  truthLabels (listlike[nTruths]) – A list of labels, one for each list passed to truths. truthLabels
supports LaTex commands enclosed in $..$. Additionally, you can pass
None
as a label. Default isNone
.  truthColors (listlike[nTruths]) – Userdefined colors for the truth lines, must be one per set of truths
passed to truths. Default color is gray
#4d4d4d
for up to three lines.  truthLineStyles (listlike[nTruths]) – Userdefined line styles for the truth lines, must be one per set of
truths passed to truths. Default line styles are
['',':','dashdot']
.  priors (list of tuples [(mu1, sigma1), ..]) – Each tuple describes a Gaussian to be plotted over that parameter’s
histogram. The number of priors must equal the number of dimensions in
chains. Default is
None
.  plotName (string) – A path to save the GTC to in pdf form. Default is
None
.  nContourLevels (int) – The number of contour levels to plot in the 2d histograms. May be 1, 2, or 3. Default is 2.
 sigmaContourLevels (bool) – Whether you want 2d “sigma” contour levels (39%, 86%, 99%) instead of
the standard contour levels (68%, 95%, 99%). Default is
False
.  nBins (int) – An integer describing the number of bins used to compute the histograms. Default is 30.
 smoothingKernel (float) – Size of the Gaussian smoothing kernel in bins. Default is 1. Set to 0 for no smoothing.
 filledPlots (bool) – Whether you want the 2d contours and the 1d histograms to be filled.
Default is
True
.  plotDensity (bool) – Whether you want to see the 2d density of points. Default is
False
.  figureSize (float or string) – A number in inches describing the length = width of the GTC, or a string
indicating a predefined journal setting and whether the figure will span
one column or the full page width. Default is 70/dpi where
dpi = plt.rcParams['figure.dpi']
. Options to choose from are'APJ_column'
,'APJ_page'
,'MNRAS_column'
,'MNRAS_page'
,'AandA_column'
,'AandA_page'
.  panelSpacing (string) – Options are
'loose'
or'tight'
. Determines whether there is some space between the subplots of the GTC or not. Default is'tight'
.  legendMarker (string) – Options are
'All'
,'None'
,'Auto'
.'All'
and'None'
forceshow or forcehide all label markers.'Auto'
shows label markers if two or more truths are plotted.  paramRanges (list of tuples [nDim]) – Set the boundaries of each parameter range. Must provide a tuple for
each dimension of chains. If
None
is provided for a parameter, the range defaults to the width of the histogram.  labelRotation (tuple [2]) – Rotate the tick labels by 45 degrees for less overlap. Sets the x and
yaxis separately. Options are
(True,True)
,(True,False)
,(False,True)
,(False,False)
,None
. UsingNone
sets to default(True,True)
.  tickShifts (tuple [2]) – Shift the x/y tick labels horizontally/vertically by a fraction of the tick spacing. Example tickShifts = (0.1, 0.05) shifts the xtick labels right by ten percent of the tick spacing and shifts the ytick labels up by five percent of the tick spacing. Default is (0.1, 0.1). If tick rotation is turned off for either axis, then the corresponding shift is set to zero.
 colorsOrder (listlike[nDims]) – The color order for chains passed to chains. Default is
['blues', 'oranges','greens', 'reds', 'purples', 'browns', 'pinks', 'grays', 'yellows', 'cyans']
. Currently,pygtc
is limited to these color values, so you can reorder them, but can’t yet define your own colors. If you really love the old colors, you can get at them by calling:['blues_old', 'greens_old', ...]
.  do1dPlots (bool) – Whether or not 1d histrograms are plotted on the diagonal. Default is
True
.  doOnly1dPlot (bool) – Plot only ONE 1d histogram. If this is True, then chains must have shape
(samples,1)
. Default isFalse
.  mathTextFontSet (string) – Set font family for rendering LaTex. Default is
'stixsans'
. Set toNone
to use the default setting in your matplotlib rc. See Notes for known issues regarding this keyword.  customLabelFont (
matplotlib.fontdict
) – Full customization of label fonts. See matplotlib for full documentation. Default is{'family':'Arial', 'size':9}
.  customLegendFont (
matplotlib.fontdict
) – Full customization of legend fonts. See matplotlib for full documentation. Default is{'family':'Arial', 'size':9}
.  customTickFont (
matplotlib.fontdict
) – Full customization of tick label fonts. See matplotlib for full documentation. Default is{'family':'Arial', 'size':6}
. Attempting to set the color will result in an error.  holdRC (bool) – Whether or not to reset rcParams back to default. You may wish to set
this to
True
if you are working in interactive mode (ie with IPython or in a JuPyter notebook) and you want the plots that display to be identical to the plots that save in the pdf. See Notes below for more information. Default isFalse
.
Returns: fig – You can do all sorts of fun things with this in terms of customization after it gets returned. If you are using a
JuPyter
notebook with inline plotting enabled, you should assign a variable to catch the return or else the figure will plot twice.Return type: matplotlib.figure
objectNote
If you are calling
plotGTC
from within an interactive python session (ie via IPython or in a JuPyter notebook), the label font in the saved pdf may differ from the plot that appears when callingmatplotlib.pyplot.show()
.This will happen if the mathTextFontSet keyword sets a value that is different than the one stored in
rcParams['mathtext.fontset']
and you are using equations in your labels by enclosing them in $..$. The output pdf will display correctly, but the interactive plot will use whatever is stored in the rcParams default to render the text that is inside the $..$. Unfortunately, this is an oversight in matplotlib’s design, which only allows one global location for specifying this setting. As a workaround, you can setholdRC = True
when callingplotGTC
and it will not reset your rcParams back to their default state. Thus, when the figure renders in interactive mode, it will match the saved pdf. If you wish to reset your rcParams back to default at any point, you can callmatplotlib.rcdefaults()
. However, if you are in a jupyter notebook and have set%matplotlib inline
, then callingmatplotlib.rcdefaults()
may not set things back the way they were, but rerunning the line magic will.This is all due to a bug in matplotlib that is slated to be fixed in the upcoming 2.0 release.
Helper functions¶
__plot2d()¶

pygtc.pygtc.
__plot2d
()¶ Plot a 2D histogram in a an axis object and return the axis with plot.
Parameters:  ax (matplotlib.pyplot.axis) – The axis on which to plot the 2D histogram
 nChains (int) – The number of chains to plot.
 chains2d (listlike) – A list of pairs of sample points in the form: [[chain1_x, chain1_y], [chain2_x, chain2_y], …].
 weights (listlike) – Weights for the chains2d.
 nBins (int) – Number of bins (per side) for the 2d histogram.
 smoothingKernel (int) – Size of the Gaussian smoothing kernel in bins. Set to 0 for no smoothing.
 filledPlots (bool) – Just contours, or filled contours?
 colors (listlike) – List of nChains tuples. Each tuple must have at least nContourLevels colors.
 nContourLevels (int {1,2,3}) – How many contour levels?
 confLevels (listlike) – List of at least nContourLevels values for contour levels.
 truths2d (listlike) – A list of nChains tuples of the form: [(truth1_x, truth1_y), etc…].
 truthColors (listlike) – A list of colors for the truths.
 truthLineStyles (listlike) – A list of matplotlib linestyle descriptors, one for each truth.
 plotDensity (bool) – Whether to show points density in addition to contours.
 myColorMap (listlike) – A list of nChains matplotlib colormap specifiers, or actual colormaps.
Note
You should really just call this from the plotGTC function unless you have a strong need to work only with an axis instead of a figure…
__plot1d()¶

pygtc.pygtc.
__plot1d
()¶ Plot the 1d histogram and optional prior.
Parameters:  ax (matplotlib.pyplot.axis) – Axis on which to plot the histogram(s)
 nChains (int) – How many chains are you passing?
 chains1d (listlike) – A list of nChains 1d chains: [chain1, chain2, etc…]
 weights (listlike) – A list of nChains weights.
 nBins (int) – How many histogram bins?
 smoothingKernel (int) – Number of bins to smooth over, 0 for no smoothing.
 filledPlots (bool) – Want the area under the curve filled in?
 colors (listlike) – List of nChains tuples. Each tuple must have at least two colors.
 truths1d (listlike) – List of truths to overplot on the histogram.
 truthColors (listlike) – One color for each truth.
 truthLineStyles (listlike) – One matplotlib linestyle specifier per truth.
 prior1d (tuple) – Normal distribution paramters (mu, sigma)
 priorColor (color) – The color to plot the prior.
Note
You should really just call this from the plotGTC function unless you have a strong need to work only with an axis instead of a figure…