Learn R Programming

ggplot2

Overview

ggplot2 is a system for declaratively creating graphics, based on The Grammar of Graphics. You provide the data, tell ggplot2 how to map variables to aesthetics, what graphical primitives to use, and it takes care of the details.

Installation

# The easiest way to get ggplot2 is to install the whole tidyverse:
install.packages("tidyverse")

# Alternatively, install just ggplot2:
install.packages("ggplot2")

# Or the development version from GitHub:
# install.packages("pak")
pak::pak("tidyverse/ggplot2")

Cheatsheet

Usage

It’s hard to succinctly describe how ggplot2 works because it embodies a deep philosophy of visualisation. However, in most cases you start with ggplot(), supply a dataset and aesthetic mapping (with aes()). You then add on layers (like geom_point() or geom_histogram()), scales (like scale_colour_brewer()), faceting specifications (like facet_wrap()) and coordinate systems (like coord_flip()).

library(ggplot2)

ggplot(mpg, aes(displ, hwy, colour = class)) + 
  geom_point()

Lifecycle

ggplot2 is now over 10 years old and is used by hundreds of thousands of people to make millions of plots. That means, by-and-large, ggplot2 itself changes relatively little. When we do make changes, they will be generally to add new functions or arguments rather than changing the behaviour of existing functions, and if we do make changes to existing behaviour we will do them for compelling reasons.

If you are looking for innovation, look to ggplot2’s rich ecosystem of extensions. See a community maintained list at https://exts.ggplot2.tidyverse.org/gallery/.

Learning ggplot2

If you are new to ggplot2 you are better off starting with a systematic introduction, rather than trying to learn from reading individual documentation pages. Currently, there are three good places to start:

  1. The Data Visualization and Communication chapters in R for Data Science. R for Data Science is designed to give you a comprehensive introduction to the tidyverse, and these two chapters will get you up to speed with the essentials of ggplot2 as quickly as possible.

  2. If you’d like to take an online course, try Data Visualization in R With ggplot2 by Kara Woo.

  3. If you’d like to follow a webinar, try Plotting Anything with ggplot2 by Thomas Lin Pedersen.

  4. If you want to dive into making common graphics as quickly as possible, I recommend The R Graphics Cookbook by Winston Chang. It provides a set of recipes to solve common graphics problems.

If you’ve mastered the basics and want to learn more, read ggplot2: Elegant Graphics for Data Analysis. It describes the theoretical underpinnings of ggplot2 and shows you how all the pieces fit together. This book helps you understand the theory that underpins ggplot2, and will help you create new types of graphics specifically tailored to your needs.

Getting help

There are two main places to get help with ggplot2:

  1. The RStudio community is a friendly place to ask any questions about ggplot2.

  2. Stack Overflow is a great source of answers to common ggplot2 questions. It is also a great place to get help, once you have created a reproducible example that illustrates your problem.

Copy Link

Version

Install

install.packages('ggplot2')

Monthly Downloads

1,654,148

Version

3.5.0

License

MIT + file LICENSE

Issues

Pull Requests

Stars

Forks

Last Published

February 23rd, 2024

Functions in ggplot2 (3.5.0)

coord_fixed

Cartesian coordinates with fixed "aspect ratio"
binned_scale

Binning scale constructor
autolayer

Create a ggplot layer appropriate to a particular data type
discrete_scale

Discrete scale constructor
coord_munch

Munch coordinates data
annotation_map

Annotation: a map
coord_polar

Polar coordinates
as.list.ggproto

Convert a ggproto object to a list
coord_map

Map projections
coord_flip

Cartesian coordinates with x and y flipped
coord_cartesian

Cartesian coordinates
coord_trans

Transformed Cartesian coordinate system
cut_interval

Discretise numeric data into categorical
element

Theme elements
expansion

Generate expansion vector for scales
expand_limits

Expand the plot limits, using data
draw_key

Key glyphs for legends
facet_wrap

Wrap a 1d ribbon of panels into 2d
faithfuld

2d density estimate of Old Faithful data
element_grob

Generate grid grob from theme element
diamonds

Prices of over 50,000 round cut diamonds
bidirection

Utilities for working with bidirectional layers
check_device

Check graphics device capabilities
geom_bar

Bar charts
fortify

Fortify a model with data.
economics

US economic time series
datetime_scale

Date/time scale constructor
facet_grid

Lay out panels in a grid
geom_bin_2d

Heatmap of 2d bin counts
geom_abline

Reference lines: horizontal, vertical, and diagonal
fill_alpha

Modify fill transparency
fortify-multcomp

Fortify methods for objects produced by multcomp
find_panel

Find panels in a gtable
fortify.sp

Fortify method for classes from the sp package.
facet_null

Facet specification: a single panel.
benchplot

Benchmark plot creation time. Broken down into construct, build, render and draw times.
fortify.map

Fortify method for map objects
geom_blank

Draw nothing
geom_count

Count overlapping points
geom_dotplot

Dot plot
geom_contour

2D contours of a 3D surface
geom_function

Draw a function as a continuous curve
element_render

Render a specified theme element into a grob
fortify.lm

Supplement the data fitted to a linear model with model fit statistics.
geom_density

Smoothed density estimates
geom_hex

Hexagonal heatmap of 2d bin counts
geom_density_2d

Contours of a 2D density estimate
geom_boxplot

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

Quantile regression
geom_ribbon

Ribbons and area plots
geom_crossbar

Vertical intervals: lines, crossbars & errorbars
geom_jitter

Jittered points
geom_errorbarh

Horizontal error bars
geom_freqpoly

Histograms and frequency polygons
geom_polygon

Polygons
geom_path

Connect observations
geom_map

Polygons from a reference map
geom_point

Points
geom_qq_line

A quantile-quantile plot
geom_smooth

Smoothed conditional means
geom_spoke

Line segments parameterised by location, direction and distance
geom_segment

Line segments and curves
get_guide_data

Extract tick information from guides
geom_raster

Rectangles
geom_violin

Violin plot
geom_label

Text
get_alt_text

Extract alt text from a plot
+.gg

Add components to a plot
geom_rug

Rug plots in the margins
ggplotGrob

Generate a ggplot2 plot grob.
ggplot2-package

ggplot2: Create Elegant Data Visualisations Using the Grammar of Graphics
ggsave

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

Create a new ggproto object
ggplot

Create a new ggplot
ggplot2-ggproto

Base ggproto classes for ggplot2
gg_dep

Give a deprecation error, warning, or message, depending on version number.
ggplot_gtable

Build a plot with all the usual bits and pieces.
ggplot_add

Add custom objects to ggplot
ggplot_build

Build ggplot for rendering.
ggtheme

Complete themes
CoordSf

Visualise sf objects
guide_axis

Axis guide
guide_axis_logticks

Axis with logarithmic tick marks
guide_coloursteps

Discretized colourbar guide
guide_axis_theta

Angle axis guide
guide_colourbar

Continuous colour bar guide
guide_bins

A binned version of guide_legend
graphical-units

Graphical units
guide_axis_stack

Stacked axis guides
guide_none

Empty guide
guide_legend

Legend guide
is.ggplot

Reports whether x is a ggplot object
ignoring_data

Ignoring and exposing data
guides

Set guides for each scale
hmisc

A selection of summary functions from Hmisc
guide_custom

Custom guides
label_bquote

Label with mathematical expressions
labs

Modify axis, legend, and plot labels
is.Coord

Is this object a coordinate system?
is.facet

Is this object a faceting specification?
is.rel

Reports whether x is a rel object
labellers

Useful labeller functions
labeller

Construct labelling specification
lims

Set scale limits
layer

Create a new layer
is.theme

Reports whether x is a theme object
mpg

Fuel economy data from 1999 to 2008 for 38 popular models of cars
map_data

Create a data frame of map data
new_guide

Guide constructor
last_plot

Retrieve the last plot to be modified or created.
position_identity

Don't adjust position
msleep

An updated and expanded version of the mammals sleep dataset
midwest

Midwest demographics
luv_colours

colors() in Luv space
merge_element

Merge a parent element into a child element
limits

Generate correct scale type for specified limits
layer_sf

Create a new sf layer that auto-maps geometry data
position_stack

Stack overlapping objects on top of each another
print.ggproto

Format or print a ggproto object
mean_se

Calculate mean and standard error of the mean
qplot

Quick plot
max_height

Get the maximal width/length of a list of grobs
presidential

Terms of 12 presidents from Eisenhower to Trump
old_guide

The previous S3 guide system
print.ggplot

Explicitly draw plot
position_jitter

Jitter points to avoid overplotting
position_dodge

Dodge overlapping objects side-to-side
position_jitterdodge

Simultaneously dodge and jitter
position_nudge

Nudge points a fixed distance
reexports

Objects exported from other packages
render_axes

Render panel axes
pattern_alpha

Modify transparency for patterns
resolution

Compute the "resolution" of a numeric vector
scale_alpha

Alpha transparency scales
scale_colour_brewer

Sequential, diverging and qualitative colour scales from ColorBrewer
scale_binned

Positional scales for binning continuous data (x & y)
render_strips

Render panel strips
register_theme_elements

Define and register new theme elements
remove_missing

Convenience function to remove missing values from a data.frame
scale_colour_grey

Sequential grey colour scales
scale_colour_hue

Evenly spaced colours for discrete data
scale_identity

Use values without scaling
scale_colour_discrete

Discrete colour scales
scale_colour_continuous

Continuous and binned colour scales
scale_x_discrete

Position scales for discrete data
scale_linetype

Scale for line patterns
scale_continuous

Position scales for continuous data (x & y)
scale_date

Position scales for date/time data
scale_colour_gradient

Gradient colour scales
scale_colour_steps

Binned gradient colour scales
sec_axis

Specify a secondary axis
seals

Vector field of seal movements
scale_manual

Create your own discrete scale
scale_size

Scales for area or radius
scale_linewidth

Scales for line width
scale_colour_viridis_d

Viridis colour scales from viridisLite
scale_shape

Scales for shapes, aka glyphs
set_last_plot

Set the last plot to be fetched by lastplot()
scale_type

Determine default scale type
should_stop

Used in examples to illustrate when errors should occur.
stat_summary_bin

Summarise y values at unique/binned x
stat_summary_2d

Bin and summarise in 2d (rectangle & hexagons)
stat_identity

Leave data as is
stat_ellipse

Compute normal data ellipses
stat_unique

Remove duplicates
stat_ecdf

Compute empirical cumulative distribution
stat_sf_coordinates

Extract coordinates from 'sf' objects
standardise_aes_names

Standardise aesthetic names
sf_transform_xy

Transform spatial position data
transform_position

Convenience function to transform all position variables.
theme_get

Get, set, and modify the active theme
theme

Modify components of a theme
tidyeval

Tidy eval helpers
txhousing

Housing sales in TX
summarise_plot

Summarise built plot objects
translate_shape_string

Translating shape strings
update_geom_defaults

Modify geom/stat aesthetic defaults for future plots
vars

Quote faceting variables
wrap_dims

Arrange 1d structure into a grid
update_labels

Update axis/legend labels
waiver

A waiver object.
zeroGrob

The zero grob draws nothing and has zero size.
summary.ggplot

Displays a useful description of a ggplot object
aes_

Define aesthetic mappings programmatically
aes_eval

Control aesthetic evaluation
aes_group_order

Aesthetics: grouping
aes_colour_fill_alpha

Colour related aesthetics: colour, fill, and alpha
absoluteGrob

Absolute grob
add_theme

Modify properties of an element in a theme object
aes

Construct aesthetic mappings
aes_linetype_size_shape

Differentiation related aesthetics: linetype, size, shape
aes_auto

Automatic aesthetic mapping
aes_all

Given a character vector, create a set of identity mappings
aes_position

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

Create a complete ggplot appropriate to a particular data type
annotation_custom

Annotation: Custom grob
as_labeller

Coerce to labeller function
annotation_raster

Annotation: high-performance rectangular tiling
annotate

Create an annotation layer
annotation_logticks

Annotation: log tick marks
combine_vars

Take input data and define a mapping between faceting variables and ROW, COL and PANEL keys
borders

Create a layer of map borders
calc_element

Calculate the element properties, by inheriting properties from its parents
continuous_scale

Continuous scale constructor