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()

pygtc.plotGTC(chains, **kwargs)

Make a great looking Giant Triangle Confusogram (GTC) with one line of code! A GTC is 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 (array-like[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 an EnsembleSampler.flatchain object.

Keyword Arguments:

  • weights (array-like[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 (array-like[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 (list-like[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 the DataFrame column names.

  • truths (list-like[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 is None.

  • truthLabels (list-like[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 is None.

  • truthColors (list-like[nTruths]) – User-defined 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 (list-like[nTruths]) – User-defined 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' force-show or force-hide 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 y-axis separately. Options are (True,True), (True,False), (False,True), (False,False), None. Using None 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 x-tick labels right by ten percent of the tick spacing and shifts the y-tick 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 (list-like[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 is False.

  • mathTextFontSet (string) – Set font family for rendering LaTex. Default is 'stixsans'. Set to None to use the default setting in your matplotlib rc.

  • 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.

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 object

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 (list-like) – A list of pairs of sample points in the form: [[chain1_x, chain1_y], [chain2_x, chain2_y], …].

  • weights (list-like) – 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 (list-like) – List of nChains tuples. Each tuple must have at least nContourLevels colors.

  • nContourLevels (int {1,2,3}) – How many contour levels?

  • confLevels (list-like) – List of at least nContourLevels values for contour levels.

  • truths2d (list-like) – A list of nChains tuples of the form: [(truth1_x, truth1_y), etc…].

  • truthColors (list-like) – A list of colors for the truths.

  • truthLineStyles (list-like) – A list of matplotlib linestyle descriptors, one for each truth.

  • plotDensity (bool) – Whether to show points density in addition to contours.

  • myColorMap (list-like) – 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 (list-like) – A list of nChains 1d chains: [chain1, chain2, etc…]

  • weights (list-like) – 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 (list-like) – List of nChains tuples. Each tuple must have at least two colors.

  • truths1d (list-like) – List of truths to overplot on the histogram.

  • truthColors (list-like) – One color for each truth.

  • truthLineStyles (list-like) – 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…