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