Documentation

ggtern, An extension to ggplot2, for the creation of ternary diagrams.

ggtern is a package that extends the functionality of ggplot2, giving the capability to plot ternary diagrams for (subset of) the ggplot2 proto geometries. 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.

ggtern is a package that is based on (extends) the very popular ggplot2, 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 ggtern.

Installation

Install the latest release on CRAN, install just like any other R package:

  install.packages('ggtern')

To install the development / working version, use the devtools package:

  devtools::install_git('https://bitbucket.org/nicholasehamilton/ggtern')

Citations

Please cite this package as follows:

citation('ggtern')

## 
## To cite package 'ggtern' in publications use:
## 
##   Nicholas Hamilton (2018). ggtern: An Extension to 'ggplot2', for
##   the Creation of Ternary Diagrams. R package version 2.2.2.
##   https://CRAN.R-project.org/package=ggtern
## 
## A BibTeX entry for LaTeX users is
## 
##   @Manual{,
##     title = {ggtern: An Extension to 'ggplot2', for the Creation of Ternary Diagrams},
##     author = {Nicholas Hamilton},
##     year = {2018},
##     note = {R package version 2.2.2},
##     url = {https://CRAN.R-project.org/package=ggtern},
##   }

Help topics

Please see the following sections, which describe the various features of the ggtern 2.2.2 package.

Starting Points

Introductory material

  • ggtern_package(ggtern-package)
    Ternary Diagrams in R
  • ggtern(constructor)
    ggtern Constructor
  • ggplot(ggplot.data.frame, ggplot.default, plot.ggplot, print.ggplot)
    Create a new ggplot plot.

Ternary Coordinates

Definitions for the ternary coordinate system.

Ternary Scales

Definitions for the ternary axes.

  • scale_X_continuous(scale_L_continuous, scale_R_continuous, scale_T_continuous)
    Ternary Position Scales
  • tern_limits(limit_tern, limits_tern, tern_limit)
    Restrict Ternary Limits

Approved Layers

Information on the layers which are available and approve for use.

  • approved_layers(approved_geom, approved_position, approved_stat)
    Approved Geoms, Stats and Positions

Geoms

Geoms, short for geometric objects, describe the type of plot you will produce. Several of the geoms are accompanied by dedicated stats.

  • geom_crosshair_tern(GeomCrosshairTern, GeomLmark, GeomRmark, GeomTmark, geom_Lmark, geom_Rmark, geom_Tmark)
    Ternary Crosshairs
  • geom_confidence_tern(GeomConfidenceTern, GeomMeanEllipse, StatConfidenceTern, geom_confidence, stat_confidence, stat_confidence_tern)
    Confidence Interval
  • geom_density_tern(GeomDensityTern, StatDensityTern, stat_density_tern)
    Density Estimate (ggtern version)
  • geom_interpolate_tern(GeomInterpolateTern, StatInterpolateTern, stat_interpolate_tern)
    Ternary Interpolation
  • geom_Xline(GeomLline, GeomRline, GeomTline, Lline, Rline, Tline, geom_Lline, geom_Rline, geom_Tline, lline, rline, tline)
    Fixed Value Lines
  • geom_Xisoprop(GeomLisoprop, GeomRisoprop, GeomTisoprop, geom_Lisoprop, geom_Risoprop, geom_Tisoprop)
    Fixed Value Isoproportion Lines
  • geom_errorbarX(GeomErrorbarl, GeomErrorbarr, GeomErrorbart, geom_errorbarL, geom_errorbarR, geom_errorbarT)
    Ternary Error Bars
  • geom_smooth_tern(GeomSmoothTern, StatSmoothTern, stat_smooth_tern)
    Add a Smoothed Conditional Mean.
  • geom_point_swap(GeomPointSwap)
    Points (Colour and Fill Swapped), as for a scatterplot
  • geom_mask(GeomMask)
    Apply Manual Clipping Mask
  • geom_label_viewport(GeomLabelViewport)
    Draw Label at Relative Position on Viewport
  • geom_text_viewport(GeomTextViewport)
    Draw Text at Relative Position on Viewport
  • geom_mean_ellipse(StatMeanEllipse, stat_mean_ellipse)
    Mean Ellipse
  • geom_hex_tern(GeomHexTern, GeomTriTern, StatHexTern, stat_hex_tern)
    Hexbin (ggtern version).
  • geom_tri_tern(StatTriTern, stat_tri_tern)
    Tribin (ggtern version).
  • geom_polygon_closed(GeomPolygonClosed)
    Closed Polygons

Annotation

Specialised functions for adding annotations to a plot.

  • annotate
    Create an annotation layer (ggtern version).
  • annotation_raster_tern(GeomRasterAnnTern)
    Annotation: High-performance rectangular tiling (ggtern version)

Positional Adjustments

Position adjustments can be used to fine tune positioning of objects to achieve effects like dodging, jittering and stacking.

Calculations

Various calculation routines.

Theme Elements

New theme elements, unique to ggtern.

Themes

Complete themes available for use.

  • theme_complete
    List of Available Themes
  • ggtern_themes(theme_bluedark, theme_bluelight, theme_bvbg, theme_bvbw, theme_bw, theme_classic, theme_custom, theme_dark, theme_darker, theme_ggtern, theme_gray, theme_light, theme_linedraw, theme_matrix, theme_minimal, theme_rgbg, theme_rgbw, theme_tropical, theme_void)
    ggtern themes

Convenience Functions

Functions for the rapid customization of plot appearance.

  • theme_convenience_functions(convenience_functions, theme_convenience)
    Theme Convenience Functions
  • theme_arrowlength(theme_arrowcustomlength, theme_arrowdefault, theme_arrowlarge, theme_arrowlong, theme_arrownormal, theme_arrowshort, theme_arrowsmall)
    Change the Length of the Ternary Arrows
  • theme_gridsontop(theme_gridsonbottom)
    Render Grids on Top
  • theme_bordersontop(theme_bordersonbottom)
    Render Borders on Top
  • theme_clockwise(tern_anticlockwise, tern_clockwise, tern_counterclockwise, theme_anticlockwise, theme_counterclockwise)
    Direction of Ternary Rotation
  • theme_legend_position
    Position Legend in Convenient Locations
  • theme_noarrows(theme_hidearrows, theme_showarrows)
    Show or Hide the Ternary Arrows
  • theme_nomask(theme_hidemask, theme_showmask)
    Show or Hide the Clipping Mask
  • theme_novar_tern
    Blank one variable's annotations in ternary plot
  • theme_rotate
    Rotate Ternary Diagram
  • theme_showgrid(theme_hidegrid, theme_hidegrid_major, theme_hidegrid_minor, theme_nogrid, theme_nogrid_major, theme_nogrid_minor, theme_showgrid_major, theme_showgrid_minor, theme_tern_nogrid, theme_tern_nogrid_major, theme_tern_nogrid_minor)
    Show or Hide Grid
  • theme_showlabels(theme_hidelabels, theme_nolabels)
    Show or Hide Axis Ticklabels
  • theme_showprimary(theme_hideprimary, theme_hidesecondary, theme_hideticks, theme_noprimary, theme_nosecondary, theme_noticks, theme_showsecondary, theme_showticks)
    Show or Hide the Primary/Secondary Ticks
  • theme_showtitles(theme_hidetitles, theme_notitles)
    Show or Hide the Axis (Apex) Titles
  • theme_ticksoutside(theme_ticksinside)
    Place Ticks Inside or Outside
  • theme_ticklength(theme_ticklength_major, theme_ticklength_minor)
    Modify the Ticklengths
  • theme_mesh
    Create Grid Mesh
  • theme_latex(theme_hidelatex, theme_nolatex, theme_showlatex)
    Parse Labels w Latex Markup
  • theme_zoom_X(theme_zoom, theme_zoom_L, theme_zoom_M, theme_zoom_R, theme_zoom_T, theme_zoom_center)
    Zoom on Plot Region

Labels

Ternary-specific Labels.

  • ggtern_labels(Larrowlab, Llab, Rarrowlab, Rlab, Tarrowlab, Tlab, Wlab, ggtern-labels, larrowlab, llab, rarrowlab, rlab, tarrowlab, tlab, wlab, zlab)
    Change Axis labels and legend titles
  • ggtern_labels_arrow_suffix(atomic_percent, custom_percent, percent_atomic, percent_custom, percent_weight, weight_percent)
    Atomic, Weight or Custom Percentage Suffix
  • label_formatter
    label_formatter
  • breaks_tern(getBreaks)
    Generate Axis Breaks
  • labels_tern(getLabels)
    Generate Axis Labels

Data

The following datasets have been included in the present package.

Legend Keys

Functions related to the renderin of legend keys.

  • draw_key_tern(draw_key_Liso, draw_key_Lline, draw_key_Lmark, draw_key_Riso, draw_key_Rline, draw_key_Rmark, draw_key_Tiso, draw_key_Tline, draw_key_Tmark, draw_key_crosshair_tern, draw_key_point_swap)
    Key drawing functions

Arrangement & Saving

The following funcions are useful for saving and printing.

  • arrangeGrob(grid.arrange)
    Arrange multiple grobs on a page (ggtern version)
  • ggsave(grid.draw.ggplot)
    Save a ggplot (or other grid object) with sensible defaults (ggtern version)

Other

  • +.gg(%+%)
    Plot Construction
  • aes
    Modified Aesthetic Mappings
  • predictdf2d
    Prediction data frame
  • strip_unapproved
    Strip Unapproved Layers
  • zzz-depreciated(clipPolygons, element_ternary, ggtern.multi, multi, multiplot, point.in.sequence, polyclip, tern_stop, theme_arrowbaseline)
    Depreciated Functions