JSS Journal of Statistical Software December 2018, Volume 87, Code Snippet 3. doi: 10.18637/jss.v087.c03 ggtern: Ternary Diagrams Using ggplot2 Nicholas E. Hamilton Michael Ferry The University of New South Wales The University of New South Wales Abstract This paper presents the ggtern package for R, which has been developed for the ren- dering of ternary diagrams. Based on the well-established ggplot2 package (Wickham 2009), the present package adopts the familiar and convenient programming syntax of its parent. We demonstrate that ggplot2 can be used as the basis for producing special- ized plotting packages and, in the present case, a package has been developed specifically for the production of high quality ternary diagrams. In order to produce ggtern, it was necessary to overcome a number of design issues, such as finding a means to modify ex- isting geometries designed for a 2D Cartesian coordinate system and permitting them to function in an environment that requires an additional spatial aesthetic mapping. In the present paper, we provide examples of this package in its most basic form followed by a demonstration of its ease of use, particularly if one is familiar with, and has a predilection towards using ggplot2 on a regular basis. Keywords: plotting software, ternary diagrams, R, ggplot2. 1. Introduction ggtern is a package for the statistical language R (R Core Team 2018), born out of the need to create ternary diagrams to an equivalent (superior) standard of the well established ggplot2 package (Wickham 2009). Ternary diagrams, not being addressed by the default ggplot2 implementation, are one of the tools held within the standard toolbox at the disposal of practitioners of several fields such as mineralogy (Flemming 2000), metallurgy & materials science (Baker 1992), politics (Katz and King 1999) as well as other physical sciences, where appropriate. ggplot2 is an implementation of The Grammar of Graphics (Wilkinson 2005) and rigorously enforces Wilkinson’s series of grammatical rules for creating perceivable graphs, therefore, by using ggplot2 as a basis for the present work, we inherit this compelling philosophy, perhaps, from time-to-time, allowing the user to create graphical poetry (Wickham 2010). 2 ggtern: Ternary Diagrams Using ggplot2 Sample Points on a Ternary Plot Paths of Constant Y Concentration Y X=10% Y Z 100 Y=80% X=33% Y=60% 80 Y=40% X=50% Y=20% 60 Y ●A Y=33% ●C Y=30% 40 ●B Y=20% 20 X Z Z=20% Z=33% Z=70% X (a) Sample Points. (b) Constant Y. Figure 1: Primitive ternary diagrams, containing (a) three (3) individual points, illustrating how compositions are interpreted, and, (b) paths of constant Y concentration in increments of 20%. Additionally, in these figures, we demonstrate both (a) anticlockwise and (b) clockwise axis precession directions. Finally, the plot rotation feature can be seen in (b), which has been rotated by 60◦ counterclockwise. Under peer-review, ggtern has already been utilized in various publications and fields, includ- ing for example, works by Witte, Bradley, Enright, and Muljo(2015), Milani, Ghiselli, Pecci, Maurizii, and Passamonti(2015); Wenger, Buzgariu, and Galliot(2016); Kalenitchenko et al. (2016); Chu, Ma, Prince, Antony, Seferovic, and Aagaard(2017) and Nesbitt et al. (2017). 2. Basics of ternary diagrams For the readers that are not particularly familiar with ternary diagrams, they are a form of graphical data representation where the total of the respective variables sum to unity (100%), forming what is known as a ‘simplex’. Using this approach is common for the handling of compositional data, for example, we could say that a liquid sugar/salt solution contains 90%H2O, 5%NaCl and 5%C12H22O11 – such a composition could be represented using the methodology described in the present work. Ternary diagrams are a special case, where apparently three (3) variables have been projected onto a 2D surface, and this is only made possible since the 3rd component is entirely dependent on the first two (2), in essence, it is not a variable at all. This is intuitive since if we have an arbitrary ternary composition made up of, say, 25% A and 25% B, with a balancing amount of C, then this third component can only represent 50% of the overall composition – any value less than 50% would suggest that something is missing, and anything above 50% is simply nonsensical unless we are referring to relative ratios, in which case we know that these proportions must sum to unity. This type of system is referred to as an Aichison simplex, the likes of which can be enforced via the compositions package (van den Boogaart, Tolosana, and Bren 2018). Journal of Statistical Software – Code Snippets 3 By the above logic, simplexes comprised of two (2) components (binary composition) have one (1) variable, and can be represented on a ‘line’, and simplexes in four (4) components (quaternary compositions) have three (3) variables, and can be described in 3D space using a tetrahedron. Taking this to the general case, if we were able to visually represent a simplex made up of n components, then we would be able to represent this in (n − 1)D space. The most common and accepted form of ternary diagram, is one which is rendered on an equilateral ‘triangle’. A point somewhere within this triangular region indicates an individual composition (a·X +b·Y +c·Z = 100%), such that the three apexes represent 100%X, 100%Y and 100%Z respectively. The centroid of the triangle indicates equal amounts of X, Y and Z. In reference to Figure 1a, three (3) points have been plotted to demonstrate reading of composition, namely, point A, representing the point of equal concentration between the X, Y and Z species, point B, having concentration (10%, 20% and 70%), and finally point C, having concentration (50%, 30% and 20%). If we note that within the Cartesian coordinate system, the path of constant x (x = k) is a line which is parallel to the y axis having an x-intercept of k, similarly, the path of constant y (y = j) is the line which is parallel to the x axis having a y-intercept of j, then, it is intuitive to understand that for ternary diagrams, the path which is parallel to Y − Z indicates compositions which have constant amounts of X, and the paths parallel to X − Z, and X − Y represent constant amounts of Y and Z respectively. To illustrate this, paths of constant Y concentration, at 20% increments, have been plotted in Figure 1b. Points outside the triangular region are ‘mathematically sound’, however in reality are non- sensical when dealing with physical compositions, implying that one or more of the simplex components have negative concentrations. Sometimes however, negative concentrations can be of value, say for example in Figure3 where the text annotation in the lower-right hand corner has been positioned this way. Ternary plots are limited in the sense that they are constricted to simplex problems using three compositional variables. Higher orders can be visualized using ternary ‘slices’, but this becomes arduous for more than four compositional variables. The obvious problem with ternary diagrams, is the counter-intuitive nature of reading the information, which is why reading ternary figures forms part of educational syllabus in many tertiary institutions within fields that regularly use such techniques, such as materials science and geology for instance – consider for instance the AMS handbook (Baker 1992), which as a reference book contains hundreds of compositions represented using ternary diagrams. 3. Features ggtern is an open-source package for the statistical computational language R, which extends the functionality of ggplot2, best described by the following set of features: • Creation of a new (ternary) coordinate system, which behind the scenes includes all the necessary transformations and inverse transformations between the Cartesian and ternary spaces. • Implementation of a dedicated clipping mask geometry, which permits fine control of its exact point of placement (final layer as default, if not specified). See for example Figure3. 4 ggtern: Ternary Diagrams Using ggplot2 • Necessary modifications to the specific plot assembly and rendering routines to account for axes that cannot be defined within columns or rows in a rectangular grid. • Adaptation of the hierarchical theme-element structure as the building-blocks for cus- tomization of plot appearance. Indeed the present work includes over fifty (50) new theme elements specific to the ternary plot. • Given the previous item, extensions to the existing base themes, permitting seamless use of both ggplot2 and ggtern figures in close proximity to each other, as per Figure2. • Also included are four (4) new preset themes, which are unique to ggtern. For examples of these, please refer to Figures 4a to 4d. • Incorporation of a mechanism to prevent the attempted use of geometries, stats or positional adjustments that would otherwise be nonsensical for ternary diagrams (e.g., violin plots or bar charts etc.). • Adaptation of the base geometries (point, path, line, segment, smooth, density 2d, text, labels, annotations etc.) for compatibility with the ternary coordinate system. • Adaptation of some of the base positional adjustment functions (identity, nudge or jitter) for compatibility with the ternary coordinate system. • Creation of several new geometries, such as ternary error bars, isoproportion lines, crosshairs, interpolation models and confidence regions using isometric log-ratio trans- formation (Egozcue, Pawlowsky-Glahn, Mateu-Figueras, and Barcelo-Vidal 2003) and the Mahalanobis distance (Mahalanobis 1936). Additionally, ggtern includes modified text and label geometries, which permit convenient positioning based on fractional co- ordinates relative to the limits of the panel viewport, these last two geometries function equally in ggplot2. • Creation of several new stats (confidence, density, interpolate), to accompany the re- spective geometries mentioned in the previous point.