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