ggtern (version 3.5.0)

ggtern_package: Ternary Diagrams in R

Description

Ternary diagrams are used frequently in a number of disciplines to graph compositional features for mixtures of three different elements or compounds. It is possible to represent a coordinate system having three (3) degrees of freedom, in 2D space, since the third dimention is linear and depends only on the other two.

The ggtern package is based on (extends) the very popular ggplot2 package, which is an implementation of Wilkinsons "The Grammar of Graphics", and, makes provision for a highly methodical construction process for the development of meaningful (graphical) data representations. Of course, the above book by Wilkinson outlines the theory, whilst Hadley Wickhams ggplot2 implementation is where much of the magic happens, and, an ideal base-platform for the ggtern package.

In this document, some of the main features are highlighted, however, current examples (and corresponding outputs) can be viewed at http://ggtern.com

<code>ggtern</code> Constructor

Plots in ggtern are instigated via the default constructor: ggtern(...), for additional information, click HERE:

<code>ggtern</code> Ternary Coordinate System

The foundation of this package, is the ternary coordinate system, which can be produced with the coord_tern(...) command and added to an existing ggplot object. The ggtern(...) constructor adds the coord_tern(...) coordinate system by default. For further information on the coord_tern(...) coordinate system, click HERE.

<code>ggtern</code> Valid Geometries

ggplot2, using the grid and proto architectures, makes provision for a many number of geometries to be added progressively in 'layers' to a given base plot. Due to the nature of the ternary coordinate system, some of the geometries which are available in ggplot2, are not relevant (or won't function) with ternary plots and as such, a limited number of 'approved' geometries can be used. Click HERE for the full list of approved geometries.

Notably, ggtern includes novel geometries not available to ggplot2 which include:

1. Confidence Intervals via the Mahalnobis Distance

2. Ternary Errorbars

3. Ternary Constant-Lines

<code>ggtern</code> Handling Non-Approved Geometries

If a geometric layer is added that is NOT contained in the approved list, IT WILL BE STRIPPED / IGNORED from the ternary diagram when rendering takes place (notifying the user to such effect). The reason for this is that subtle 'patches' have been applied, which are mainly to do with the transformation procedures when incorporating a 'third' dimention. NB: In the future, others may be made available once patched.

<code>ggtern</code> New Theme Elements and Heirarchies

ggtern implements many new theme elements and heirarchies which can be tailored on a case-by-case basis. The full list of new elements can is provided HERE.

<code>ggtern</code> Theme Element Convenience Functions

ggtern has made available a number of convenience functions, for rapid tweaking of common theme elements, for a comprehensive list, see HERE.

<code>ggtern</code> Modification to Required Aesthetics

Each geometry has a pre-determined set of required aesthetics. These have been modifid such that where x and y were previously required, now an additional z aesthetic is required (geom_segment now requires z and zend). This is made possible without affecting the standard ggplot2 behaviour because ggtern distinuishes between ggplot2 and ggtern objects, distinguished by the presence of the coord_tern(...) coordinate system.

<code>ggtern</code> Provided Datasets

ggtern ships with a number of datasets, including:

1. Elkin and Groves Feldspar Data

2. USDA Textural Classification Data

3. Grantham and Valbel Rock Fragment Data

Author

Nicholas Hamilton

References

To cite this package, please use the following:

Hamilton NE and Ferry M (2018). "ggtern: Ternary Diagrams Using ggplot2." Journal of Statistical Software, Code Snippets, 87(3), pp. 1-17. doi: 10.18637/jss.v087.c03 (URL:http://doi.org/10.18637/jss.v087.c03)

A bibtex entry can be obtained by executing the following command: citation('ggtern')

Examples

##-----------------------------------------------
## Basic Usage
##-----------------------------------------------
df = data.frame(x = runif(50),
                y = runif(50),
                z = runif(50),
                Value = runif(50,1,10),
                Group = as.factor(round(runif(50,1,2))))
ggtern(data=df,aes(x,y,z,color=Group)) + 
  theme_rgbw() + 
  geom_point() + geom_path() + 
  labs(x="X",y="Y",z="Z",title="Title")