This is a plotting library for use with matplotlib to make ternary plots, plots in the two dimensional simplex projected onto a two dimensional plane.

The library provides functions for plotting projected lines, curves (trajectories), and heatmaps.

Most ternary functions expect the simplex to be partititioned into some number of steps. A few functions will do this partitioning for you, but when working with real data or simulation output, you may have partitioned already.

The following code draws a boundary for the simplex and gridlines.

from matplotlib import pyplot
import ternary

steps = 30

ax = ternary.draw_boundary(steps)
ternary.draw_gridlines(steps, ax=ax)
ax.set_title("Simplex Boundary and Gridlines")

pyplot.show()

You can draw individual lines between any two points with draw_line and lines parallel to the axes with draw_horizonal_line, draw_left_parallel_line, and draw_right_parallel_line:

from matplotlib import pyplot

import ternary
steps = 30

ax = ternary.draw_boundary(steps)
ternary.draw_horizontal_line(ax, steps, 10)
ternary.draw_left_parallel_line(ax, steps, 15, linewidth=2., color='red')
ternary.draw_right_parallel_line(ax, steps, 15, linewidth=3., color='blue')

ax.set_title("Various Lines")

pyplot.show()

The line drawing functions accept the matplotlib keyword arguments of Line2D

Curves can be plotted by specifying the points of the curve, just like matplotlib's plot. Simply use:

ternary.plot(points)

Points is a list of tuples or numpy arrays, e.g. [(0.5, 0.25, 0.25), (1./3, 1./3, 1//3)]. Ternary assumes that the points are probability distributions (e.g. x+y+z=1) unless you specify otherwise. Again you can specify axes and line options:

ternary.plot(points, ax=ax, steps=100, linewidth=2.0)

There are many more examples in this paper.

Ternary can plot heatmaps in two ways and two styles. Given a function, ternary will evaluate the function at the specified number of steps. The simplex can be split up into triangles or hexagons (thanks to contributor btweinstein for the hexagonal heatmap functionality). There is a large set of examples here.

For example:

def shannon_entropy(p):
    """Computes the Shannon Entropy at a distribution in the simplex."""
    s = 0.
    for i in range(len(p)):
        try:
            s += p[i] * math.log(p[i])
        except ValueError:
            continue
    return -1.*s

We can get a heatmap of this function as follows:

from matplotlib import pyplot

import ternary
pyplot.figure()
ax = ternary.function_heatmap(func, steps=steps, boundary=True, style="triangular")
ternary.draw_boundary(steps, ax=ax)
ax.set_title("Shannon Entropy Heatmap")

pyplot.show()

In this case the keyword argument boundary indicates whether you wish to evaluate points on the boundary of the partition (which is sometimes undesirable). Specify style="hexagonal" for hexagons.

Ternary can also take a dictionary mapping (i,j) for i + j + k = steps to a float as input for a heatmap, using the function

ternary.heatmap(d, steps, cmap_name=None, ax=None, scientific=False)

You may specify a matplotlib colormap in the cmap_name argument.

Please cite as follows:

Marc Harper, Python-ternary: A python library for ternary plots, 2011, available at: https://github.com/marcharper/python-ternary

• Marc Harper marcharper
• Bryan Weinstein btweinstein: Hexagonal heatmaps