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