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