ggplot2 v3.2.1

0

Monthly downloads

0th

Percentile

Create Elegant Data Visualisations Using the Grammar of Graphics

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.

Readme

ggplot2

Travis Build
Status AppVeyor Build
Status Coverage
Status CRAN\_Status\_Badge

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 the development version from GitHub:
# install.packages("devtools")
devtools::install_github("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

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 http://www.ggplot2-exts.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 visualisation and graphics for 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 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. The book is not available for free, but you can find the complete source for the book at https://github.com/hadley/ggplot2-book.

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.

Functions in ggplot2

Name Description
aes_auto Automatic aesthetic mapping
annotation_custom Annotation: Custom grob
coord_map Map projections
annotate Create an annotation layer
coord_flip Cartesian coordinates with x and y flipped
aes_colour_fill_alpha Colour related aesthetics: colour, fill and alpha
aes_group_order Aesthetics: grouping
autoplot Create a complete ggplot appropriate to a particular data type
combine_vars Take input data and define a mapping between faceting variables and ROW, COL and PANEL keys
benchplot Benchmark plot creation time. Broken down into construct, build, render and draw times.
annotation_raster Annotation: high-performance rectangular tiling
coord_munch Munch coordinates data
facet_wrap Wrap a 1d ribbon of panels into 2d
faithfuld 2d density estimate of Old Faithful data
draw_key Key glyphs for legends
find_panel Find panels in a gtable
coord_polar Polar coordinates
fortify-multcomp Fortify methods for objects produced by multcomp
economics US economic time series
expand_limits Expand the plot limits, using data
continuous_scale Continuous scale constructor.
geom_density_2d Contours of a 2d density estimate
geom_dotplot Dot plot
as.list.ggproto Convert a ggproto object to a list
annotation_logticks Annotation: log tick marks
coord_cartesian Cartesian coordinates
coord_fixed Cartesian coordinates with fixed "aspect ratio"
annotation_map Annotation: a maps
diamonds Prices of 50,000 round cut diamonds
cut_interval Discretise numeric data into categorical
fortify.map Fortify method for map objects
coord_trans Transformed Cartesian coordinate system
borders Create a layer of map borders
calc_element Calculate the element properties, by inheriting properties from its parents
ggplot2-package ggplot2: Create Elegant Data Visualisations Using the Grammar of Graphics
ggplot2-ggproto Base ggproto classes for ggplot2
geom_segment Line segments and curves
geom_rug Rug plots in the margins
geom_count Count overlapping points
margin Theme elements
element_grob Generate grid grob from theme element
geom_density Smoothed density estimates
geom_errorbarh Horizontal error bars
geom_hex Hexagonal heatmap of 2d bin counts
fortify Fortify a model with data.
discrete_scale Discrete scale constructor.
expand_scale Generate expansion vector for scales.
geom_abline Reference lines: horizontal, vertical, and diagonal
geom_freqpoly Histograms and frequency polygons
fortify.lm Supplement the data fitted to a linear model with model fit statistics.
geom_bar Bar charts
geom_jitter Jittered points
geom_boxplot A box and whiskers plot (in the style of Tukey)
facet_grid Lay out panels in a grid
hmisc A selection of summary functions from Hmisc
position_nudge Nudge points a fixed distance
guides Set guides for each scale
fortify.sp Fortify method for classes from the sp package.
facet_null Facet specification: a single panel.
geom_quantile Quantile regression
position_stack Stack overlapping objects on top of each another
geom_bin2d Heatmap of 2d bin counts
geom_ribbon Ribbons and area plots
geom_crossbar Vertical intervals: lines, crossbars & errorbars
geom_blank Draw nothing
geom_point Points
geom_contour 2d contours of a 3d surface
geom_path Connect observations
geom_polygon Polygons
geom_qq_line A quantile-quantile plot
geom_label Text
geom_raster Rectangles
geom_violin Violin plot
scale_size Scales for area or radius
stat_ellipse Compute normal confidence ellipses
render_axes Render panel axes
stat_function Compute function for each x value
render_strips Render panel strips
scale_type Determine default scale type
+.gg Add components to a plot
ggplotGrob Generate a ggplot2 plot grob.
vars Quote faceting variables
waiver A waiver object.
ggplot_build Build ggplot for rendering.
guide_colourbar Continuous colour bar guide
position_dodge Dodge overlapping objects side-to-side
limits Generate correct scale type for specified limits
is.ggplot Reports whether x is a ggplot object
guide_legend Legend guide
position_identity Don't adjust position
lims Set scale limits
is.rel Reports whether x is a rel object
ggplot_gtable Build a plot with all the usual bits and pieces.
ggproto Create a new ggproto object
geom_map Polygons from a reference map
is.facet Is this object a faceting specification?
geom_spoke Line segments parameterised by location, direction and distance
layer_sf Create a new sf layer that auto-maps geometry data
ggplot Create a new ggplot
layer Create a new layer
geom_smooth Smoothed conditional means
is.Coord Is this object a coordinate system?
merge_element Merge a parent element into a child element
gg_dep Give a deprecation error, warning, or message, depending on version number.
midwest Midwest demographics
ggsave Save a ggplot (or other grid object) with sensible defaults
ggtheme Complete themes
CoordSf Visualise sf objects
graphical-units Graphical units
is.theme Reports whether x is a theme object
label_bquote Label with mathematical expressions
guide-exts S3 generics for guides.
max_height Get the maximal width/length of a list of grobs
mean_se Calculate mean and standard error
print.ggproto Format or print a ggproto object
scale_colour_viridis_d Viridis colour scales from viridisLite
tidyeval Tidy eval helpers
qplot Quick plot
scale_colour_continuous Continuous colour scales
theme_get Get, set, and modify the active theme
scale_colour_gradient Gradient colour scales
scale_x_discrete Position scales for discrete data
scale_colour_brewer Sequential, diverging and qualitative colour scales from colorbrewer.org
seals Vector field of seal movements
reexports Objects exported from other packages
update_geom_defaults Modify geom/stat aesthetic defaults for future plots
update_labels Update axis/legend labels
stat Calculated aesthetics
summary.ggplot Displays a useful description of a ggplot object
translate_qplot_lattice Translating between qplot and lattice
txhousing Housing sales in TX
remove_missing Convenience function to remove missing values from a data.frame
stat_ecdf Compute empirical cumulative distribution
theme Modify components of a theme
ggplot_add Add custom objects to ggplot
labs Modify axis, legend, and plot labels
labeller Construct labelling specification
scale_manual Create your own discrete scale
position_jitter Jitter points to avoid overplotting
luv_colours colors() in Luv space
sec_axis Specify a secondary axis
labellers Useful labeller functions
map_data Create a data frame of map data
scale_shape Scales for shapes, aka glyphs
position_jitterdodge Simultaneously dodge and jitter
scale_alpha Alpha transparency scales
resolution Compute the "resolution" of a numeric vector
scale_identity Use values without scaling
stat_identity Leave data as is
should_stop Used in examples to illustrate when errors should occur.
scale_linetype Scale for line patterns
standardise_aes_names Standardise aesthetic names
stat_sf_coordinates Extract coordinates from 'sf' objects
mpg Fuel economy data from 1999 and 2008 for 38 popular models of car
msleep An updated and expanded version of the mammals sleep dataset
presidential Terms of 11 presidents from Eisenhower to Obama
last_plot Retrieve the last plot to be modified or created.
print.ggplot Explicitly draw plot
set_last_plot Set the last plot to be fetched by lastplot()
stat_unique Remove duplicates
scale_continuous Position scales for continuous data (x & y)
scale_date Position scales for date/time data
scale_colour_grey Sequential grey colour scales
summarise_plot Summarise built plot objects
stat_summary_bin Summarise y values at unique/binned x
wrap_dims Arrange 1d structure into a grid
zeroGrob The zero grob draws nothing and has zero size.
scale_colour_hue Evenly spaced colours for discrete data
stat_summary_2d Bin and summarise in 2d (rectangle & hexagons)
translate_qplot_ggplot Translating between qplot and ggplot
transform_position Convenience function to transform all position variables.
absoluteGrob Absolute grob
add_theme Modify properties of an element in a theme object
aes_position Position related aesthetics: x, y, xmin, xmax, ymin, ymax, xend, yend
aes_linetype_size_shape Differentiation related aesthetics: linetype, size, shape
aes Construct aesthetic mappings
aes_ Define aesthetic mappings programmatically
aes_all Given a character vector, create a set of identity mappings
as_labeller Coerce to labeller function
autolayer Create a ggplot layer appropriate to a particular data type
No Results!

Vignettes of ggplot2

Name
car.png
extending-ggplot2.Rmd
ggplot2-specs.Rmd
profiling.Rmd
No Results!

Last month downloads

Details

License GPL-2 | file LICENSE
URL http://ggplot2.tidyverse.org, https://github.com/tidyverse/ggplot2
BugReports https://github.com/tidyverse/ggplot2/issues
LazyData true
Collate 'ggproto.r' 'ggplot-global.R' 'aaa-.r' 'aes-calculated.r' 'aes-colour-fill-alpha.r' 'aes-group-order.r' 'aes-linetype-size-shape.r' 'aes-position.r' 'compat-plyr.R' 'utilities.r' 'aes.r' 'legend-draw.r' 'geom-.r' 'annotation-custom.r' 'annotation-logticks.r' 'geom-polygon.r' 'geom-map.r' 'annotation-map.r' 'geom-raster.r' 'annotation-raster.r' 'annotation.r' 'autolayer.r' 'autoplot.r' 'axis-secondary.R' 'backports.R' 'bench.r' 'bin.R' 'coord-.r' 'coord-cartesian-.r' 'coord-fixed.r' 'coord-flip.r' 'coord-map.r' 'coord-munch.r' 'coord-polar.r' 'coord-quickmap.R' 'coord-sf.R' 'coord-transform.r' 'data.R' 'facet-.r' 'facet-grid-.r' 'facet-null.r' 'facet-wrap.r' 'fortify-lm.r' 'fortify-map.r' 'fortify-multcomp.r' 'fortify-spatial.r' 'fortify.r' 'stat-.r' 'geom-abline.r' 'geom-rect.r' 'geom-bar.r' 'geom-bin2d.r' 'geom-blank.r' 'geom-boxplot.r' 'geom-col.r' 'geom-path.r' 'geom-contour.r' 'geom-count.r' 'geom-crossbar.r' 'geom-segment.r' 'geom-curve.r' 'geom-defaults.r' 'geom-ribbon.r' 'geom-density.r' 'geom-density2d.r' 'geom-dotplot.r' 'geom-errorbar.r' 'geom-errorbarh.r' 'geom-freqpoly.r' 'geom-hex.r' 'geom-histogram.r' 'geom-hline.r' 'geom-jitter.r' 'geom-label.R' 'geom-linerange.r' 'geom-point.r' 'geom-pointrange.r' 'geom-quantile.r' 'geom-rug.r' 'geom-sf.R' 'geom-smooth.r' 'geom-spoke.r' 'geom-text.r' 'geom-tile.r' 'geom-violin.r' 'geom-vline.r' 'ggplot2.r' 'grob-absolute.r' 'grob-dotstack.r' 'grob-null.r' 'grouping.r' 'guide-colorbar.r' 'guide-legend.r' 'guides-.r' 'guides-axis.r' 'guides-grid.r' 'hexbin.R' 'labeller.r' 'labels.r' 'layer.r' 'layer-sf.R' 'layout.R' 'limits.r' 'margins.R' 'performance.R' 'plot-build.r' 'plot-construction.r' 'plot-last.r' 'plot.r' 'position-.r' 'position-collide.r' 'position-dodge.r' 'position-dodge2.r' 'position-identity.r' 'position-jitter.r' 'position-jitterdodge.R' 'position-nudge.R' 'position-stack.r' 'quick-plot.r' 'range.r' 'save.r' 'scale-.r' 'scale-alpha.r' 'scale-brewer.r' 'scale-colour.r' 'scale-continuous.r' 'scale-date.r' 'scale-discrete-.r' 'scale-gradient.r' 'scale-grey.r' 'scale-hue.r' 'scale-identity.r' 'scale-linetype.r' 'scale-manual.r' 'scale-shape.r' 'scale-size.r' 'scale-type.R' 'scale-viridis.r' 'scales-.r' 'stat-bin.r' 'stat-bin2d.r' 'stat-bindot.r' 'stat-binhex.r' 'stat-boxplot.r' 'stat-contour.r' 'stat-count.r' 'stat-density-2d.r' 'stat-density.r' 'stat-ecdf.r' 'stat-ellipse.R' 'stat-function.r' 'stat-identity.r' 'stat-qq-line.R' 'stat-qq.r' 'stat-quantile.r' 'stat-sf-coordinates.R' 'stat-sf.R' 'stat-smooth-methods.r' 'stat-smooth.r' 'stat-sum.r' 'stat-summary-2d.r' 'stat-summary-bin.R' 'stat-summary-hex.r' 'stat-summary.r' 'stat-unique.r' 'stat-ydensity.r' 'summarise-plot.R' 'summary.r' 'theme-elements.r' 'theme.r' 'theme-defaults.r' 'theme-current.R' 'translate-qplot-ggplot.r' 'translate-qplot-lattice.r' 'utilities-break.r' 'utilities-grid.r' 'utilities-help.r' 'utilities-matrix.r' 'utilities-resolution.r' 'utilities-table.r' 'utilities-tidy-eval.R' 'zxx.r' 'zzz.r'
VignetteBuilder knitr
RoxygenNote 6.1.1
Encoding UTF-8
NeedsCompilation no
Packaged 2019-08-09 20:11:46 UTC; thomas
Repository CRAN
Date/Publication 2019-08-10 22:30:13 UTC

Include our badge in your README

[![Rdoc](http://www.rdocumentation.org/badges/version/ggplot2)](http://www.rdocumentation.org/packages/ggplot2)