Plot basics

All ggplot2 plots with a call to ggplot(), supplying default data and aesthethic mappings, specified by aes(). You then add layers, scales, coords and facets with +. To save a plot to disk, use ggsave().

Construct aesthetic mappings

Add components to a plot

Create a new ggplot

Save a ggplot (or other grid object) with sensible defaults

Quick plot

Layer: geoms

A layer combines data, aesthetic mapping, a geom (geometric object), a stat (statistical transformation), and a position adjustment. Typically, you will create layers using a geom_ function, overriding the default position and stat if needed.

Reference lines: horizontal, vertical, and diagonal

Bars charts

Heatmap of 2d bin counts

Draw nothing

A box and whiskers plot (in the style of Tukey)

2d contours of a 3d surface

Count overlapping points

Contours of a 2d density estimate

Smoothed density estimates

Dot plot

Horizontal error bars

Hexagonal heatmap of 2d bin counts

Histograms and frequency polygons

Jittered points

Vertical intervals: lines, crossbars & errorbars

Polygons from a reference map

Connect observations



A quantile-quantile plot

Quantile regression

Ribbons and area plots

Rug plots in the margins

Line segments and curves

Smoothed conditional means

Line segments parameterised by location, direction and distance



Violin plot

Layer: stats

A handful of layers are more easily specified with a stat_ function, drawing attention to the statistical transformation rather than the visual appearance.

Compute empirical cumulative distribution

Compute normal confidence ellipses

Compute function for each x value

Leave data as is

Bin and summarise in 2d (rectangle & hexagons)

Summarise y values at unique/binned x

Remove duplicates

Layer: position adjustment

All layers have a position adjustment that resolves overlapping geoms. Override the default by using the position argument to the geom_ or stat_ function.

Dodge overlapping objects side-to-side

Don't adjust position

Jitter points to avoid overplotting

Simultaneously dodge and jitter

Nudge points a fixed distance

Stack overlapping objects on top of each another

Layer: annotations

Annotation are special types of layer than don’t inherit global settings from the plot. Rhey are used to add fixed reference data to plot.

Create an annotation layer

Annotation: Custom grob

Annotation: log tick marks

Annotation: a maps

Annotation: high-performance rectangular tiling

Create a layer of map borders

Reference lines: horizontal, vertical, and diagonal


The following help topics give a broad overview of some of the ways you can use each aesthetic

Colour related aesthetics: colour, fill and alpha

Aesthetics: grouping

Differentiation related aesthetics: linetype, size, shape

Position related aesthetics: x, y, xmin, xmax, ymin, ymax, xend, yend


Scales control the details of how data values are translated to visual properties. Override the default scales to tweak details like the axis labels or legend keys, or to use a completely different translation from data to aesthetic. labs() and lims() are convenient helpers for the most common adjustments to the labels and limits.

Expand the plot limits, using data

Modify axis, legend, and plot labels

Set scale limits

Alpha transparency scales

Sequential, diverging and qualitative colour scales from

Position scales for continuous data (x & y)

Position scales for date/time data

Position scales for discrete data

Gradient colour scales

Sequential grey colour scales

Evenly spaced colours for discrete data

Use values without scaling

Scale for line patterns

Create your own discrete scale

Scales for shapes, aka glyphs

Scales for area or radius

Guides: axes and legends

The guides (the axes and legends) help readers interpret your plots. Guides are mostly controlled via the scale (e.g. with the limits, breaks, and labels arguments), but sometimes you will need additional cover over the guide apperance. Use guides() or the guide argument to individual scales along with guide_colourbar() or guide_legend().

Continuous colour bar guide

Legend guide

Set guides for each scale

Specify a secondary axis


Facetting generates small multiples, each displaying a different subset of the data. Facets are an alternative to aesthetics for displaying additional discrete variables.

Lay out panels in a grid

Wrap a 1d ribbon of panels into 2d

Facetting: labels

These functions provide a flexible toolkit for controlling the display of the “strip” labels on facets.

Label with mathematical expressions

Construct labelling specification

Useful labeller functions

Coordinate systems

The coordinate system determines how the x and y aesthetics combine to position elements in the plot. The default coordinate system is Cartesian (coord_cartesian()), which can be tweaked with coord_map(), coord_fixed(), coord_flip(), and coord_trans(), or completely replaced with coord_polar().

Cartesian coordinates

Cartesian coordinates with fixed "aspect ratio"

Cartesian coordinates with x and y flipped

Map projections

Polar coordinates

Transformed Cartesian coordinate system


Themes control the display of all non-data elements of the plot. You can override all settings with a complete theme like theme_bw(), or choose to tweak individual settings by using theme() and the element_ functions. Use theme_set() to modify the active theme, affecting all future plots.

Theme elements

Complete themes

Get, set, and modify the active theme

Modify components of a theme

Programming with ggplot2

These functions provides tools to help you program with ggplot2, creating functions and for-loops that generate plots for you.

Define aesthetic mappings programatically

Explicitly draw plot

Extending ggplot2

To create your own geoms, stats, scales, and facets, you’ll need to learn a bit about the object oriented system that ggplot2 uses. Start by reading vignette("extending-ggplot2") then consult these functions for more details.

Create a new ggproto object

Format or print a ggproto object

Vector helpers

ggplot2 also provides a handful of helpers that are useful for creating visualisations.

Discretise numeric data into categorical

A selection of summary functions from Hmisc

Calculate mean and standard error

Compute the "resolution" of a numeric vector


ggplot2 comes with a selection of built-in datasets that are used in examples to illustrate various visualisation challenges.

Prices of 50,000 round cut diamonds

US economic time series

2d density estimate of Old Faithful data


Midwest demographics

Fuel economy data from 1999 and 2008 for 38 popular models of car

An updated and expanded version of the mammals sleep dataset

Terms of 11 presidents from Eisenhower to Obama

Vector field of seal movements

Housing sales in TX

Autoplot and fortify

autoplot() is an extension mechansim for ggplot2 it provides a way for package authors to add methods that work like the base plot() function, generating useful default plots with little user interaction. fortify() turns objects into tidy data frames: it has largely been superceded by the broom package.

Create a complete ggplot appropriate to a particular data type

Fortify a model with data.

Create a data frame of map data