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), scatter plots, and heatmaps. There are several examples and a short tutorial below.
Most ternary functions expect the simplex to be partititioned into some number of steps, determined by the scale parameter. A few functions will do this partitioning for you, but when working with real data or simulation output, you may have partitioned already. if you are working with probability distributions, just use scale=1 (the default). Otherwise the scale parameter effectively controls the resolution of many plot types (e.g. heatmaps).
To install clone the repository and run setup.py in the usual manner:
get clone git@github.com:marcharper/python-ternary.git
cd python-ternary
sudo python setup.py install
New features are still being added to python-ternary. A stable release is upcoming.
The easiest way to use python-ternary is with the wrapper class TernaryAxesSubplot,
which mimics Matplotlib's AxesSubplot. Start with
figure, tax = ternary.figure()
With a ternary axes object tax you can use many of the usual matplotlib
axes object functions:
tax.set_title("Scatter Plot", fontsize=20)
tax.scatter(points, marker='s', color='red', label="Red Squares")
tax.legend()
Most drawing functions can take standard matplotlib keyword arguments such as linestyle and linewidth. You can use LaTeX in titles and labels.
If you need to act directly on the underyling matplotlib axes, you can access them:
ax = tax.get_axes()
You can also wrap a Matplotlib AxesSubplot object:
figure, ax = pyplot.subplots()
tax = ternary.TernaryAxesSubplot(ax=ax)
This is useful if you want to use ternary as part of another figure, such as
pyplot.figure()
gs = gridspec.GridSpec(2,2)
ax = pyplot.subplot(gs[0,0])
figure, tax = ternary.figure(ax=ax)
...
TernaryAxesSubplot objects keep track of the scale and supply this parameter to other functions as needed.
The following code draws a boundary for the simplex and gridlines.
from matplotlib import pyplot
import ternary
## Boundary and Gridlines
scale = 40
figure, tax = ternary.figure(scale=scale)
# Draw Boundary and Gridlines
tax.boundary(color="black", linewidth=2.0)
tax.gridlines(color="blue", multiple=5) # Every 5th gridline, can be fractional
# Set Axis labels and Title
fontsize = 20
tax.set_title("Simplex Boundary and Gridlines", fontsize=fontsize)
tax.left_axis_label("Left label $\\alpha^2$", fontsize=fontsize)
tax.right_axis_label("Right label $\\beta^2$", fontsize=fontsize)
tax.bottom_axis_label("Bottom label $\\Gamma - \\Omega$", fontsize=fontsize)
# Remove default Matplotlib Axes
tax.clear_matplotlib_ticks()
pyplot.show()
You can draw individual lines between any two points with line and lines parallel to the axes with horizonal_line, left_parallel_line, and right_parallel_line:
import ternary
scale = 40
figure, tax = ternary.figure(scale=scale)
# Draw Boundary and Gridlines
tax.boundary(color="black", linewidth=2.0)
tax.gridlines(color="blue", multiple=5)
# Set Axis labels and Title
fontsize = 20
tax.set_title("Various Lines", fontsize=20)
tax.left_axis_label("Left label $\\alpha^2$", fontsize=fontsize)
tax.right_axis_label("Right label $\\beta^2$", fontsize=fontsize)
tax.bottom_axis_label("Bottom label $\\Gamma - \\Omega$", fontsize=fontsize)
# Draw lines parallel to the axes
tax.horizontal_line(16)
tax.left_parallel_line(10, linewidth=2., color='red', linestyle="--")
tax.right_parallel_line(20, linewidth=3., color='blue')
# Draw an arbitrary line, ternary will project the points for you
p1 = (12,8,10)
p2 = (2, 26, 2)
tax.line(p1, p2, linewidth=3., marker='s', color='green', linestyle=":")
tax.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)], e.g. as in the sample data.
import ternary
## Sample trajectory plot
figure, tax = ternary.figure(scale=1.0)
tax.boundary(color='black')
tax.gridlines(multiple=0.2, color="black")
tax.set_title("Plotting of sample trajectory data", fontsize=20)
points = []
# Load some data, tuples (x,y,z)
with open("curve.txt") as handle:
for line in handle:
points.append(map(float, line.split(' ')))
# Plot the data
tax.plot(points, linewidth=2.0, label="Curve")
tax.legend()
tax.show()
There are many more examples in this paper.
You can also color the curves with a Matplotlib heatmap using:
plot_colored_trajectory(points, cmap="hsv", linewidth=2.0)
Similarly, ternary can make scatter plots:
import ternary
### Scatter Plot
scale = 40
figure, tax = ternary.figure(scale=scale)
tax.set_title("Scatter Plot", fontsize=20)
tax.boundary(color="black", linewidth=2.0)
tax.gridlines(multiple=5, color="blue")
# Plot a few different styles with a legend
points = random_points(30, scale=scale)
tax.scatter(points, marker='s', color='red', label="Red Squares")
points = random_points(30, scale=scale)
tax.scatter(points, marker='D', color='green', label="Green Diamonds")
tax.legend()
tax.show()
Ternary can plot heatmaps in two ways and two styles. Given a function, ternary will evaluate the function at the specified number of steps (determined by the scale, expected to be an integer in this case). The simplex can be split up into triangles or hexagons (thanks to btweinstein for the hexagonal heatmap functionality). There is a large set of examples here.
Let's define a function on the simplex for illustration, the Shannon entropy of a probability distribution:
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:
import ternary
scale = 60
figure, tax = ternary.figure(scale=scale)
tax.set_title("Scatter Plot", fontsize=20)
tax.heatmapf(shannon_entropy, boundary=True, style="triangular")
tax.boundary(linewidth=2.0)
tax.set_title("Shannon Entropy Heatmap")
tax.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. Large scalings can use a lot of RAM (the number of polygons rendered is O(n^2) ).
You may specify a matplotlib colormap (an instance or the colormap name) in the cmap argument.
Ternary can also make heatmaps from data. In this case you need to supply a dictionary mapping (i,j) for i + j + k = scale to a float as input for a heatmap, using the function
ternary.heatmap(d, scale, ax=None, cmap=None)
or
tax.heatmap(d, cmap=None)
This can produces images such as:
It is not necessary to include k in the dictionary keys since it can be determined from scale, i, and j. This reduces the memory requirements when the partition is very fine (significant when scale >= 500).
You can run the test suite as follows:
python -m unittest discover tests
Contributions are welcome! Please share any nice example plots, contribute features, and add unit tests! Use the pull request and issue systems to contribute.
Please cite as follows:
Marc Harper, Python-ternary: A python library for ternary plots, 2011-2015, available at: https://github.com/marcharper/python-ternary
- Marc Harper marcharper
- Bryan Weinstein btweinstein: Hexagonal heatmaps, colored trajectory plots