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