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