Movatterモバイル変換

Title:	Create Elegant Data Visualisations Using the Grammar of Graphics
Version:	4.0.1
Description:	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.
License:	MIT + file LICENSE
URL:	https://ggplot2.tidyverse.org,https://github.com/tidyverse/ggplot2
BugReports:	https://github.com/tidyverse/ggplot2/issues
Depends:	R (≥ 4.1)
Imports:	cli, grDevices, grid, gtable (≥ 0.3.6), isoband, lifecycle (>1.0.1), rlang (≥ 1.1.0), S7, scales (≥ 1.4.0), stats, vctrs(≥ 0.6.0), withr (≥ 2.5.0)
Suggests:	broom, covr, dplyr, ggplot2movies, hexbin, Hmisc, hms, knitr,mapproj, maps, MASS, mgcv, multcomp, munsell, nlme, profvis,quantreg, quarto, ragg (≥ 1.2.6), RColorBrewer, roxygen2,rpart, sf (≥ 0.7-3), svglite (≥ 2.1.2), testthat (≥ 3.1.5),tibble, vdiffr (≥ 1.0.6), xml2
Enhances:	sp
VignetteBuilder:	quarto
Config/Needs/website:	ggtext, tidyr, forcats, tidyverse/tidytemplate
Config/testthat/edition:	3
Config/usethis/last-upkeep:	2025-04-23
Encoding:	UTF-8
LazyData:	true
RoxygenNote:	7.3.3
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' 'all-classes.R' 'compat-plyr.R' 'utilities.R''aes.R' 'annotation-borders.R' 'utilities-checks.R''legend-draw.R' 'geom-.R' 'annotation-custom.R''annotation-logticks.R' 'scale-type.R' 'layer.R''make-constructor.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-radial.R''coord-sf.R' 'coord-transform.R' 'data.R' 'docs_layer.R''facet-.R' 'facet-grid-.R' 'facet-null.R' 'facet-wrap.R''fortify-map.R' 'fortify-models.R' 'fortify-spatial.R''fortify.R' 'stat-.R' 'geom-abline.R' 'geom-rect.R''geom-bar.R' 'geom-tile.R' 'geom-bin2d.R' 'geom-blank.R''geom-boxplot.R' 'geom-col.R' 'geom-path.R' 'geom-contour.R''geom-point.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-freqpoly.R''geom-function.R' 'geom-hex.R' 'geom-histogram.R''geom-hline.R' 'geom-jitter.R' 'geom-label.R''geom-linerange.R' 'geom-pointrange.R' 'geom-quantile.R''geom-rug.R' 'geom-sf.R' 'geom-smooth.R' 'geom-spoke.R''geom-text.R' 'geom-violin.R' 'geom-vline.R''ggplot2-package.R' 'grob-absolute.R' 'grob-dotstack.R''grob-null.R' 'grouping.R' 'properties.R' 'margins.R''theme-elements.R' 'guide-.R' 'guide-axis.R''guide-axis-logticks.R' 'guide-axis-stack.R''guide-axis-theta.R' 'guide-legend.R' 'guide-bins.R''guide-colorbar.R' 'guide-colorsteps.R' 'guide-custom.R''guide-none.R' 'guide-old.R' 'guides-.R' 'guides-grid.R''hexbin.R' 'import-standalone-obj-type.R''import-standalone-types-check.R' 'labeller.R' 'labels.R''layer-sf.R' 'layout.R' 'limits.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' '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-linewidth.R' 'scale-manual.R''scale-shape.R' 'scale-size.R' 'scale-steps.R' 'scale-view.R''scale-viridis.R' 'scales-.R' 'stat-align.R' 'stat-bin.R''stat-summary-2d.R' 'stat-bin2d.R' 'stat-bindot.R''stat-binhex.R' 'stat-boxplot.R' 'stat-connect.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-manual.R''stat-qq-line.R' 'stat-qq.R' 'stat-quantilemethods.R''stat-sf-coordinates.R' 'stat-sf.R' 'stat-smooth-methods.R''stat-smooth.R' 'stat-sum.R' 'stat-summary-bin.R''stat-summary-hex.R' 'stat-summary.R' 'stat-unique.R''stat-ydensity.R' 'summarise-plot.R' 'summary.R' 'theme.R''theme-defaults.R' 'theme-current.R' 'theme-sub.R''utilities-break.R' 'utilities-grid.R' 'utilities-help.R''utilities-patterns.R' 'utilities-resolution.R''utilities-tidy-eval.R' 'zxx.R' 'zzz.R'
NeedsCompilation:	no
Packaged:	2025-11-13 07:39:29 UTC; thomas
Author:	Hadley Wickham [aut], Winston Chang [aut], Lionel Henry [aut], Thomas Lin Pedersen [aut, cre], Kohske Takahashi [aut], Claus Wilke [aut], Kara Woo [aut], Hiroaki Yutani [aut], Dewey Dunnington [aut], Teun van den Brand [aut], Posit, PBC [cph, fnd]
Maintainer:	Thomas Lin Pedersen <thomas.pedersen@posit.co>
Repository:	CRAN
Date/Publication:	2025-11-14 09:20:02 UTC

ggplot2: Create Elegant Data Visualisations Using the Grammar of Graphics

Description

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.

Author(s)

Maintainer: Thomas Lin Pedersenthomas.pedersen@posit.co (ORCID)

Authors:

• Hadley Wickhamhadley@posit.co (ORCID)

• Winston Chang (ORCID)

• Lionel Henry

• Kohske Takahashi

• Claus Wilke (ORCID)

• Kara Woo (ORCID)

• Hiroaki Yutani (ORCID)

• Dewey Dunnington (ORCID)

• Teun van den Brand (ORCID)

Other contributors:

• Posit, PBC (ROR) [copyright holder, funder]

See Also

Useful links:

• https://ggplot2.tidyverse.org

• https://github.com/tidyverse/ggplot2

• Report bugs athttps://github.com/tidyverse/ggplot2/issues

Coords

Description

All⁠coord_*()⁠ functions (likecoord_transform()) return a⁠Coord*⁠ object(likeCoordTransform). These objects contain methods that support thecoordinate systems in ggplot2.

Details

Each of the⁠Coord*⁠ objects is aggproto() object, descended from thetop-levelCoord, and each implements various methods and fields.The object and its parameters are chaperoned by theLayout class.

To create a new type of Coord object, it is recommendedto extend not the baseCoord class, but one of its children likeCoordCartesian.

When overriding thetransform() method, it may be necessary to adapt theimplementation ofrender_bg() and possibly axis placement too.

An important data structure that coordinate systems create is thepanel_params structure. When overriding that structure, many methods mayneed to be adapted as well.

Fields

default

Scaler boolean indicating whether this is the defaultcoordinate system. Non-default coordinate systems raise a message whena new system replaces it.

clip

A scalar string grid setting controlling whether layers shouldbe clipped to the extent of the plot panel extent. Can be"on" toperform clipping,"off" to not clip, or"inherit" to take on thesetting of the parent viewport.

reverse

A scalar string giving which directions to reverse. ForCartesian systems, can be⁠"none⁠,"x","y" or"xy" for both.Non-Cartesian may define their own settings.

setup_params

Description

A function method for modifying or checking the parameters based on thedata. The default method parses theexpand parameter.

Usage

Coord$setup_params(data)

Arguments

data

A list of data frames. The first item is the global data,which is followed by layer data in subsequent items.

Value

A list of parameters

setup_data

Description

A function method for modifying or checking the data prior to addingdefaults. The default method returns data unaltered.

Usage

Coord$setup_data(data, params)

Arguments

data

A list of data frames. The first item is the global data,which is followed by layer data in subsequent items.

params

A list of parameters coming from thesetup_params()method.

Value

A list of data frames of the same length as thedata argument

setup_layout

Description

A function method that acts as a hook for the coordinate system to haveinput on the layout computed by facets.

Usage

Coord$setup_layout(layout, params)

Arguments

layout

A data frame computed byFacet$compute_layout().Typically contains the faceting variables,ROW,COL,PANEL,SCALE_X andSCALE_Y variables.

params

A list of parameters coming from thesetup_params()method.

Value

A data frame from the modifiedlayout argument. The default creates anewCOORD column to identify unique combinations of x and y scales forefficiency purposes. It should never remove columns.

modify_scales

Description

A function method for modifying scales in place. This is optional andcurrently used by CoordFlip and CoordPolar to ensure axis positions areconforming to the coordinate system.

Usage

Coord$modify_scales(scales_x, scales_y)

Arguments

scales_x,scales_y

A list of trained scales for thex andyaesthetics respectively.

Value

Nothing, this is called for the side effect of modifying scales.

setup_panel_params

Description

This function method is used to setup panel parameters per panel.For efficiency reasons, this method is called once per combination ofx andy scales. It is used to instantiate ViewScale class objects andranges for position aesthetics and optionally append additionalparameters needed for thetransform() method and rendering axes.

Usage

Coord$setup_panel_params(scale_x, scale_y, params)

Arguments

scale_x,scale_y

A list of trained scales for thex andyaesthetics respectively.

params

A list of parameters coming from thesetup_params()method.

Value

A named list of view scales, ranges and other optional parameters.

setup_panel_guides

Description

This function method is used to initiate position guides for each panel.For efficiency reasons, this method is called once per combination ofxandy scales. For the primary and secondary positions, it should resolveguides coming from theplot$guides field andScale$guide fields andset appropriateGuide$params$position parameters.

Usage

Coord$setup_panel_guides(panel_params, guides, params)

Arguments

panel_params

A list of ViewScale class objects and additionalparameters from thesetup_panel_params() method.

guides

A⁠<Guides>⁠ ggproto class.

params

A list of parameters coming from thesetup_params()method.

Value

Thepanel_params object but with a Guides class object appended withthe name 'guides'.

setup_panel_guides

Description

This function method is used to train and transform position guides for eachpanel. For efficiency reasons, this method is called once per combinationofx andy scales.

Usage

Coord$train_panel_guides(panel_params, layers, params)

Arguments

panel_params

A list of ViewScale class objects, a Guides classobject and additional parameters from thesetup_panel_params() method.

layers

A list of layers fromplot$layers.

params

A list of parameters coming from thesetup_params()method.

Value

Thepanel_params object, but with trained and transformedguidesparameter.

transform

Description

This function method is used to apply transformations and rescale positionaesthetics. This method is used in several places:

• The Geom drawing code, used throughcoord_munch() in many Geoms.

• The Guide transform method

• Panel grid transformation inrender_bg()

Usage

Coord$transform(data, panel_params)

Arguments

data

A data frame with columns for numeric position aesthetics.

panel_params

A list of ViewScale class objects and additionalparameters from thesetup_panel_params() method.

Value

Thedata argument with rescaled and transformed position aesthetics.

distance

Description

This function method is used to calculate distances between subsequentdata points.coord_munch() uses this method determine how many pointsshould be used to interpolate.

Usage

Coord$distance(x, y, panel_params)

Arguments

x,y

x and y coordinates of a set of points in data space.

panel_params

A list of ViewScale class objects and additionalparameters from thesetup_panel_params() method.

Value

Thedata argument with rescaled and transformed position aesthetics.

backtransform_range

Description

This function method is used to convert ranges from transformed coordinatesback into data coordinates. The data coordinates may possibly be scale-transformed. It is used incoord_munch() to ensure limits are in datacoordinates.

The back-transformation may be needed for coords such ascoord_transform(),where the range in the transformed coordinates differs from the range inthe untransformed coordinates.

Usage

Coord$backtransform_range(panel_params)

Arguments

panel_params

A list of ViewScale class objects and additionalparameters from thesetup_panel_params() method.

Value

A list containing numeric ranges forx andy in data coordinates.

range

Description

This function method is a small helper method to extract ranges from thepanel_params object. It exists becausepanel_params can be opaque attimes.

Usage

Coord$range(panel_params)

Arguments

panel_params

A list of ViewScale class objects and additionalparameters from thesetup_panel_params() method.

Value

A list containing numeric ranges forx andy.

draw_panel

Description

This function method is used to orchestrate decorating panel drawings withforeground and background drawings. It is called once per panel, invokestherender_fg() andrender_bg() methods and enforces theclip field.

Usage

Coord$draw_panel(panel, params, theme)

Arguments

panel

A grob containing drawn layers and facet foreground andbackground.

params

A list of ViewScale class objects and additionalparameters from thesetup_panel_params() method.

theme

Acomplete theme

Value

A grob with panel content.

render_fg

Description

This function method is used to draw the panel foreground. For allintents and purposes is just thepanel.border theme element, but you canrepurpose this method.

Usage

Coord$render_fg(panel_params, theme)

Arguments

panel_params

A list of ViewScale class objects and additionalparameters from thesetup_panel_params() method.

theme

Acomplete theme

Value

A grob with panel foreground.

render_bg

Description

This function method is used to draw the panel background. Typicallythis is a combination of thepanel.background andpanel.grid themeelements.

Usage

Coord$render_bg(panel_params, theme)

Arguments

panel_params

A list of ViewScale class objects and additionalparameters from thesetup_panel_params() method.

theme

Acomplete theme

Value

A grob with panel background.

labels

Description

This function method is used to format axis titles. It is used in somecoordinate systems to (conditionally) swap x and y labels.

Usage

Coord$labels(labels, panel_params)

Arguments

labels

A named list containing anx list and ay list. Thex andy lists haveprimary andsecondary labels.

panel_params

A list of ViewScale class objects and additionalparameters from thesetup_panel_params() method.

Value

A list with the same structure and names as thelabels argument.

aspect

Description

This function method that gives the aspect ratio for panels. It allows forCoordFixed to compute an aspect ratio based on data ranges.

Usage

Coord$render_bg(panel_params, theme)

Arguments

ranges

A list of ViewScale class objects and additionalparameters from thesetup_panel_params() method. If there aremultiple panels, the parameters for the first panel is used.

Value

A scalar numeric

render_axis_h,render_axis_v

Description

These function methods are used to render axes to place at the outside edgeof panels. Interior axes should not be rendered here. Therender_axis_h()methods produces the horizontal axes for the top and bottom position.Therender_axis_v() method renders the vertical axes for the left andright position.

Usage

Coord$render_axis_h(panel_params, themeCoord$render_axis_v(panel_params, theme)

Arguments

panel_params

A list of ViewScale class objects, a Guides classobject and additional parameters from thesetup_panel_params() method.

theme

Acomplete theme

Value

Forrender_axis_h() a named list where"top" and"bottom" are grobswith an axis. Forrender_axis_v() a named list where"left" and"right" are grobs with an axis. These grobs should bezeroGrob()when no axes should be rendered.

is_linear

Description

This function method is used to signal whether a coordinate system islinear. Incoord_munch() and several Geom drawing methods, it is used todetermine whether points should be interpolated.

Usage

Coord$is_linear()

Value

A scalar boolean.

is_free

Description

This function method is used to signal whether a coordinate system supportsfree scaling of axes in faceted plots. This should generally returnFALSEfor coordinate systems that enforce a fixed aspect ratio.

Usage

Coord$is_free()

Value

A scalar boolean.

Conventions

The object name that a new class is assigned to is typically the same as theclass name. Coord class names are in UpperCamelCase and start with the⁠Coord*⁠ prefix, likeCoordNew.

A constructor function is usually paired with a Coord class. The constructorcopies the coord class and populates parameters. The constructor function nameshould take the Coord class name and be formatted with snake_case,so thatCoordNew becomescoord_new().

See Also

Thenew coords section of the online ggplot2 book.

Other Layout components:Facet,Layout

Examples

# Extending the classCoordJitter <- ggproto(  "CoordJitter", CoordCartesian,  # Fields  amount = 0,  # Methods  is_linear = function() FALSE,  transform = function(self, data, panel_params) {    data   <- ggproto_parent(CoordCartesian, self)$transform(data, panel_params)    data$x <- jitter(data$x, amount = self$amount)    data$y <- jitter(data$y, amount = self$amount)    data  })# Building a constructorcoord_jitter <- function(amount = 0.005, xlim = NULL, ylim = NULL, expand = TRUE,                         clip = "on", reverse = "none") {  ggproto(    NULL, CoordJitter,    amount = amount,    limits = list(x = xlim, y = ylim),    reverse = reverse, expand = expand, clip = clip  )}# Use new coord in plotset.seed(42)ggplot(mpg, aes(drv, displ)) +  geom_boxplot() +  coord_jitter()

Visualise sf objects

Description

This set of geom, stat, and coord are used to visualise simple feature (sf)objects. For simple plots, you will only needgeom_sf() as itusesstat_sf() and addscoord_sf() for you.geom_sf() isan unusual geom because it will draw different geometric objects dependingon what simple features are present in the data: you can get points, lines,or polygons.For text and labels, you can usegeom_sf_text() andgeom_sf_label().

Usage

coord_sf(  xlim = NULL,  ylim = NULL,  expand = TRUE,  crs = NULL,  default_crs = NULL,  datum = sf::st_crs(4326),  label_graticule = waiver(),  label_axes = waiver(),  lims_method = "cross",  ndiscr = 100,  default = FALSE,  clip = "on",  reverse = "none")geom_sf(  mapping = aes(),  data = NULL,  stat = "sf",  position = "identity",  na.rm = FALSE,  show.legend = NA,  inherit.aes = TRUE,  ...)geom_sf_label(  mapping = aes(),  data = NULL,  stat = "sf_coordinates",  position = "nudge",  ...,  parse = FALSE,  label.padding = unit(0.25, "lines"),  label.r = unit(0.15, "lines"),  label.size = deprecated(),  border.colour = NULL,  border.color = NULL,  text.colour = NULL,  text.color = NULL,  na.rm = FALSE,  show.legend = NA,  inherit.aes = TRUE,  fun.geometry = NULL)geom_sf_text(  mapping = aes(),  data = NULL,  stat = "sf_coordinates",  position = "nudge",  ...,  parse = FALSE,  check_overlap = FALSE,  na.rm = FALSE,  show.legend = NA,  inherit.aes = TRUE,  fun.geometry = NULL)stat_sf(  mapping = NULL,  data = NULL,  geom = "rect",  position = "identity",  na.rm = FALSE,  show.legend = NA,  inherit.aes = TRUE,  ...)

Arguments

Geometry aesthetic

geom_sf() uses a unique aesthetic:geometry, giving ancolumn of classsfc containing simple features data. Thereare three ways to supply thegeometry aesthetic:

• Do nothing: by defaultgeom_sf() assumes it is stored inthegeometry column.

• Explicitly pass ansf object to thedata argument.This will use the primary geometry column, no matter what it's called.

• Supply your own usingaes(geometry = my_column)

Unlike other aesthetics,geometry will never be inherited fromthe plot.

CRS

coord_sf() ensures that all layers use a common CRS. You caneither specify it using thecrs param, orcoord_sf() willtake it from the first layer that defines a CRS.

Combining sf layers and regular geoms

Most regular geoms, such asgeom_point(),geom_path(),geom_text(),geom_polygon() etc. will work fine withcoord_sf(). Howeverwhen using these geoms, two problems arise. First, what CRS should be usedfor the x and y coordinates used by these non-sf geoms? The CRS applied tonon-sf geoms is set by thedefault_crs parameter, and it defaults toNULL, which means positions for non-sf geoms are interpreted as projectedcoordinates in the coordinate system set by thecrs parameter. This settingallows you complete control over where exactly items are placed on the plotcanvas, but it may require some understanding of how projections work and howto generate data in projected coordinates. As an alternative, you can setdefault_crs = sf::st_crs(4326), the World Geodetic System 1984 (WGS84).This means that x and y positions are interpreted as longitude and latitude,respectively. You can also specify any other valid CRS as the default CRS fornon-sf geoms.

The second problem that arises for non-sf geoms is how straight linesshould be interpreted in projected space whendefault_crs is not set toNULL.The approachcoord_sf() takes is to break straight lines into small pieces(i.e., segmentize them) and then transform the pieces into projected coordinates.For the default setting where x and y are interpreted as longitude and latitude,this approach means that horizontal lines follow the parallels and vertical linesfollow the meridians. If you need a different approach to handling straight lines,then you should manually segmentize and project coordinates and generate the plotin projected coordinates.

See Also

Thesimple feature maps section of the online ggplot2 book.

stat_sf_coordinates()

Examples

if (requireNamespace("sf", quietly = TRUE)) {nc <- sf::st_read(system.file("shape/nc.shp", package = "sf"), quiet = TRUE)ggplot(nc) +  geom_sf(aes(fill = AREA))# If not supplied, coord_sf() will take the CRS from the first layer# and automatically transform all other layers to use that CRS. This# ensures that all data will correctly line upnc_3857 <- sf::st_transform(nc, 3857)ggplot() +  geom_sf(data = nc) +  geom_sf(data = nc_3857, colour = "red", fill = NA)# Unfortunately if you plot other types of feature you'll need to use# show.legend to tell ggplot2 what type of legend to usenc_3857$mid <- sf::st_centroid(nc_3857$geometry)ggplot(nc_3857) +  geom_sf(colour = "white") +  geom_sf(aes(geometry = mid, size = AREA), show.legend = "point")# You can also use layers with x and y aesthetics. To have these interpreted# as longitude/latitude you need to set the default CRS in coord_sf()ggplot(nc_3857) +  geom_sf() +  annotate("point", x = -80, y = 35, colour = "red", size = 4) +  coord_sf(default_crs = sf::st_crs(4326))# To add labels, use geom_sf_label().ggplot(nc_3857[1:3, ]) +   geom_sf(aes(fill = AREA)) +   geom_sf_label(aes(label = NAME))}# Thanks to the power of sf, a geom_sf nicely handles varying projections# setting the aspect ratio correctly.if (requireNamespace('maps', quietly = TRUE)) {library(maps)world1 <- sf::st_as_sf(map('world', plot = FALSE, fill = TRUE))ggplot() + geom_sf(data = world1)world2 <- sf::st_transform(  world1,  "+proj=laea +y_0=0 +lon_0=155 +lat_0=-90 +ellps=WGS84 +no_defs")ggplot() + geom_sf(data = world2)}

Facets

Description

All⁠facet_*()⁠ functions returns aFacet object or an object of aFacet subclass. This object describes how to assign data to differentpanels, how to apply positional scales and how to lay out the panels, oncerendered.

Details

Extending facets can range from the simple modifications of current facets,to very laborious rewrites with a lot ofgtable()manipulation.For some examples of both, please see the extension vignette.The object and its parameters are chaperoned by theLayout class.

Facet subclasses, like other extendible ggproto classes, have a rangeof methods that can be modified. Some of these are required for all newsubclasses, while other only need to be modified if need arises.

The required methods are:

• compute_layout

• map_data()

• draw_panels() or its subsidiaries:

  • init_gtable()

  • attach_axes()

  • attach_strips()

In addition to the methods above, it can be useful to override the defaultbehaviour of one or more of the following methods:

• setup_params()

• init_scales()

• train_scale()

• finish_data()

• draw_back(),draw_front() ordraw_labels()

All extension methods receive the content of the params field as the paramsargument, so the constructor function will generally put all relevantinformation into this field.

Fields

shink

A scalar boolean which whenTRUE, will shrink scales tofit output statistics rather than raw data. IfFALSE, will only includeraw data before statistical summary. By exception this is not part of theparams field.

params

A named list of parameters populated by the constructorfunction.

setup_params

Description

A function method for modifying or checking the parameters based on thedata. The default method includes a.possible_columns variable givingcolumn names.

Usage

Facet$setup_params(data, params)

Arguments

data

A list of data frames. The first item is the global data,which is followed by layer data in subsequent items.

params

A list of current parameters.

Value

A list of parameters

setup_data

Description

A function method for modifying or checking the data prior to addingdefaults. The default method returns data unaltered.

Usage

Facet$setup_data(data, params)

Arguments

data

A list of data frames. The first item is the global data,which is followed by layer data in subsequent items.

params

A list of parameters coming from thesetup_params()method.

Value

A list of data frames of the same length as thedata argument

compute_layout

Description

A function method for creating the correspondence between facetingvariable levels, panels and position scales. It places panels like cellsin a matrix.

Usage

Facet$compute_layout(data, params)

Arguments

data

A list of data frames. The first item is the global data,which is followed by layer data in subsequent items.

params

A list of parameters coming from thesetup_params()method.

Value

A data frame with 1 row per panel, containing at least integer columnsROW,COL,PANEL,SCALE_X andSCALE_Y. Can contain additionalinformation in terms of columns, typically faceting variables.

map_data

Description

A function method for to create thePANEL variable in layer data. ThePANEL variable is a special variable that tracks the relationship betweenrows in the layer data and the panels described in thelayout input.

In addition, #' this function may copy or discard rows as needed, forexample when adding margins in FacetGrid.

Usage

Facet$map_data(data, layout, params)

Arguments

data

A list of data frames containing layer data.

layout

A data frame computed by thecompute_layout() method.Typically contains the faceting variables,ROW,COL,PANEL,SCALE_X andSCALE_Y variables.

params

A list of parameters coming from thesetup_params()method.

Value

A list of data frames containing layer data including aPANEL variable.

init_scales

Description

A function method for initialising position scales. Given a prototype scaleforx andy, creates layout specific scales to accommodatethe relationships between panels and scales. By default, the prototypescales are cloned for eachSCALE_X andSCALE_Y level. The function iscalled separately; once forx and once fory.

Usage

Facet$init_scales(layout, x_scale, y_scale, params)

Arguments

layout

A data frame computed by thecompute_layout() method.Typically contains the faceting variables,ROW,COL,PANEL,SCALE_X andSCALE_Y variables.

x_scale,y_scale

A position scale for thex andyaesthetics respectively.

params

A list of parameters coming from thesetup_params()method.

Value

A named list withx andy elements containing a list of panel scalesfor eachSCALE_X and/orSCALE_Y level respectively.

train_scales

Description

A function method for training position scales. The default trains eachscale on the data related to its panels.

Usage

Facet$train_scales(x_scales, y_scales, layout, data, params)

Arguments

x_scales,y_scales

A list of panel scales for eachSCALE_XandSCALE_Y level respectively.

layout

A data frame computed by thecompute_layout() method.Typically contains the faceting variables,ROW,COL,PANEL,SCALE_X andSCALE_Y variables.

data

A list of data frames containing layer data.

params

A list of parameters coming from thesetup_params()method.

Value

Nothing, this method is called for its side-effect of training the scales.

setup_panel_params

Description

A function method as a hook to give facets input over panel parameters. Bydefault, returns panel parameters unaltered.

Usage

Facet$setup_panel_params(panel_params, coord, ...)

Arguments

panel_params

A named list of view scales, ranges and otheroptional parameters fromCoord$setup_panel_params().

coord

A⁠<Coord>⁠ ggproto object.

...

Currently not in use. For future expansion.

Value

A list of panel parameters.

finish_data

Description

A function method as a hook for making last-minute modifications to layerdata before it is rendered by Geoms. The default is to not modify the data.

Usage

Facet$finish_data(data, layout, x_scales, y_scales, params)

Arguments

data

A data frame containing layer data of a single layer.

layout

A data frame computed by thecompute_layout() method.Typically contains the faceting variables,ROW,COL,PANEL,SCALE_X andSCALE_Y variables.

x_scales,y_scales

A list of panel scales for eachSCALE_XandSCALE_Y level respectively.

params

A list of parameters coming from thesetup_params()method.

Value

A data frame containing layer data.

draw_panel_content

Description

A function method to assemble the panel contents. It delegates thedraw_back() anddraw_front() methods, as well asCoord$draw_panel().

Usage

Facet$draw_panel_content(  panels,  layout,  x_scales,  y_scales,  ranges,  coord,  theme,  params,  ...)

Arguments

panels

A list parallel to layers. Each element is another listwith grobs for each panel, generated byLayer$draw_geom().

layout

A data frame computed by thecompute_layout() method.Typically contains the faceting variables,ROW,COL,PANEL,SCALE_X andSCALE_Y variables.

x_scales,y_scales

A list of panel scales for eachSCALE_XandSCALE_Y level respectively.

ranges

A list of panel parameters from thesetup_panel_params() augmented with position guides.

coord

A⁠<Coord>⁠ ggproto object.

data

A list of data frames containing layer data.

theme

Acomplete theme object.

params

A list of parameters coming from thesetup_params()method.

...

Currently not in use.

Value

A list of grobs, one for each level of thePANEL layout variable. Grobcan bezeroGrob() to draw nothing.

draw_back,draw_front

Description

A function method draw facet background (back) and foreground (front) forpanels. The front and back will sandwich the grobs created by layers. Thedefault methods draw nothing.

Usage

Facet$draw_back(data, layout, x_scales, y_scales, theme, params)Facet$draw_front(data, layout, x_scales, y_scales, theme, params)

Arguments

data

A list of data frames containing layer data.

layout

A data frame computed by thecompute_layout() method.Typically contains the faceting variables,ROW,COL,PANEL,SCALE_X andSCALE_Y variables.

x_scales,y_scales

A list of panel scales for eachSCALE_XandSCALE_Y level respectively.

theme

Acomplete theme object.

params

A list of parameters coming from thesetup_params()method.

Value

A list of grobs, one for each level of thePANEL layout variable. Grobcan bezeroGrob() to draw nothing.

draw_panels

Description

A function method that orchestrates the majority of facet drawing. It isresponsible for assembling a gtable with panel content decorated with axesand strips. The resulting gtable is the basis for the plot in its entirety.It delegates these tasks to theinit_gtable(),attach_axes() andattach_strips() methods.

Usage

Facet$draw_panels(  panels,  layout,  x_scales,  y_scales,  ranges,  coord,  data,  theme,  params)

Arguments

panels

A list of grobs, one per panel.

layout

A data frame computed by thecompute_layout() method.Typically contains the faceting variables,ROW,COL,PANEL,SCALE_X andSCALE_Y variables.

x_scales,y_scales

A list of panel scales for eachSCALE_XandSCALE_Y level respectively.

ranges

A list of panel parameters from thesetup_panel_params() augmented with position guides.

coord

A⁠<Coord>⁠ ggproto object.

data

A list of data frames containing layer data.

theme

Acomplete theme object.

params

A list of parameters coming from thesetup_params()method.

Value

Agtable object.

init_gtable

Description

A function method that initiates a gtable object containing panels setat the appropriateROW andCOL cells from the layout. The panels areseparated by the⁠panel.spacing.{x/y}⁠ spacing.

Usage

Facet$init_gtable(panels, layout, theme, ranges, params, aspect_ratio)

Arguments

panels

A list of grobs, one per panel.

layout

A data frame computed by thecompute_layout() method.Typically contains the faceting variables,ROW,COL,PANEL,SCALE_X andSCALE_Y variables.

theme

Acomplete theme object.

ranges

A list of panel parameters from thesetup_panel_params() augmented with position guides.

aspect_ratio

A scalar numeric for the panel aspect ratio orNULL for no aspect ratio.

Value

Agtable object containing panel grobs prefixed with"panel".

attach_axes

Description

A function method that renders position guides (axes) and attaches theseto the gtable with panels. The default method returns the gtable unaltered.

Usage

Facet$attach_axes(table, layout, ranges, coord, theme, params)

Arguments

table

Agtable object populated with panels from theinit_gtable() method.

layout

A data frame computed by thecompute_layout() method.Typically contains the faceting variables,ROW,COL,PANEL,SCALE_X andSCALE_Y variables.

ranges

A list of panel parameters from thesetup_panel_params() augmented with position guides.

coord

A⁠<Coord>⁠ ggproto object.

theme

Acomplete theme object.

params

A list of parameters coming from thesetup_params()method.

Value

Agtable object.

attach_strips

Description

A function method that renders strips and attaches these to the gtablewith panels and axes. Theformat_strip_labels() method is used to formatthe strip text. The default method returns the gtable unaltered.

Usage

Facet$attach_strips(table, layout, ranges, coord, theme, params)

Arguments

table

Agtable object from theattach_axes()method.

layout

A data frame computed by thecompute_layout() method.Typically contains the faceting variables,ROW,COL,PANEL,SCALE_X andSCALE_Y variables.

params

A list of parameters coming from thesetup_params()method.

theme

Acomplete theme object.

Value

Agtable object.

format_strip_labels

Description

A function method that formats the text for strips. It is used in theattach_strips methods, but also theget_strip_labels() function.The default method returnsNULL.

Usage

Facet$format_strip_labels(layout, params)

Arguments

layout

A data frame computed by thecompute_layout() method.Typically contains the faceting variables,ROW,COL,PANEL,SCALE_X andSCALE_Y variables.

params

A list of parameters coming from thesetup_params()method.

Value

A list containing a data frame with strip labels.

set_panel_size

Description

A function method that enforces thepanel.widths andpanel.heightstheme settings.

Usage

Facet$set_panel_size(table, theme)

Arguments

table

Agtable object populated by thedraw_panels() method.

theme

Acomplete theme object.

Value

Thetable object, optionally with differentwidths andheightsproperties.

attach_axes

Description

A function method that renders axis titles and adds them to the gtable.The default is to add one title at each side depending on the positionand presence of axes.

Usage

Facet$draw_labels(  panels,  layout,  x_scales,  y_scales,  ranges,  coord,  data,  theme,  labels,  params)

Arguments

panels

Agtable object initiated by thedraw_panels() method.

layout

A data frame computed by thecompute_layout() method.Typically contains the faceting variables,ROW,COL,PANEL,SCALE_X andSCALE_Y variables.

x_scales,y_scales

A list of panel scales for eachSCALE_XandSCALE_Y level respectively.

ranges

A list of panel parameters from thesetup_panel_params() augmented with position guides.

coord

A⁠<Coord>⁠ ggproto object.

data

A list of data frames containing layer data.

theme

Acomplete theme object.

labels

A named list containing anx list andy list. Thex andy lists haveprimary andsecondary labels.

params

A list of parameters coming from thesetup_params()method.

Value

Agtable object.

vars

Description

A function method that returns the names of faceting variables. Thedefault method returns an character vector with 0 length.

Usage

Facet$vars()

Value

A character vector

Conventions

The object name that a new class is assigned to is typically the same as theclass name. Facet class names are in UpperCamelCase and start with the⁠Facet*⁠ prefix, likeFacetNew.

A constructor function is usually paired with a Facet class. The constructorcopies the facet class and populates theparams field. The constructorfunction name should take the Facet class name and be formatted withsnake_case, so thatFacetNew becomesfacet_new().

See Also

The thenew facets section of the online ggplot2 book.

Runvignette("extending-ggplot2"), in particular the "Creating anew faceting" section.

Other Layout components:Coord,Layout

Examples

# Please see extension vignetteNULL

Geoms

Description

All⁠geom_*()⁠ functions (likegeom_point()) return a layer thatcontains a⁠Geom*⁠ object (likeGeomPoint). The⁠Geom*⁠object is responsible for rendering the data in the plot.

Details

Each of the⁠Geom*⁠ objects is aggproto() object, descendedfrom the top-levelGeom, and each implements various methods andfields. The object and its parameters are chaperoned by theLayer class.

Compared toStat andPosition,Geom is a littledifferent because the execution of the setup and compute functions issplit up.setup_data runs before position adjustments, anddraw_layer() is not run until render time, much later.

When creating a new Geom class, you may want to consider override one ormore of the following:

• Therequired_aes anddefault_aes fields.

• Thesetup_data() andsetup_params() functions.

• Either thedraw_panel() ordraw_group() function.

• Thedraw_key field.

Fields

required_aes

A character vector naming aesthetics that are necessaryto render the geom.

non_missing_aes

A character vector naming aesthetics that will causeremoval if they have missing values.

optional_aes

A character vector naming aesthetics that will beaccepted bylayer(), but are not required or described in thedefault_aes field.

default_aes

Amapping of default values for aesthetics.Aesthetics can be set toNULL to be included as optional aesthetic.

rename_size

A scalar boolean: whether to renamesize aesthetics tolinewidth.

extra_params

A character vector of parameter names in addition tothose imputed from thedraw_panel() ordraw_groups() methods. Thisfield can be set to include parameters forsetup_data() orhandle_na()methods. By default, this only contains"na.rm".

draw_key

A function generating a single legend glyph for the geom.Typically one of the functions prefixed bydraw_key_.

setup_params

Description

A function method for modifying or checking the parameters based on thedata. The default method returns the parameters unaltered.

Usage

Geom$setup_params(data, params)

Arguments

data

A data frame with the layer's data.

params

A list of current parameters.

Value

A list of parameters

setup_data

Description

A function method for modifying or checking the data prior to addingdefaults. The default method returns data unaltered.

Usage

Geom$setup_data(data, params)

Arguments

data

A data frame with the layer's data.

params

A list of parameters coming from thesetup_params()method.

Value

A data frame with layer data

use_defaults

Description

A function method for completing the layer data by filling in defaultaesthetics that are not present. It is not recommended to use as anextension point.

It takes on these tasks:

• Evaluation of default aesthetics from thedefault_aes field.

• Handling theafter_scale()/stage(after_scale) stage of delayedevaluation.

• Fill in fixed, unmapped aesthetics passed as parameters.

Usage

Geom$use_defaults(data, params, modifiers, default_aes, theme, ...)

Arguments

data

A data frame of the layer's data, coming from thesetup_data() method. Can beNULL, in which case resolved defaultsshould be returned.

params

A list of fixed aesthetic parameters

modifiers

Amapping with delayed evaluations.

default_aes

Amapping with default aesthetics.

theme

Acompleted theme.

Value

A data frame with completed layer data.

handle_na

Description

A function method to handle missing values. The default method willremove rows that have missing values for the aesthetics listed in therequired_aes andnon_missing_aes fields. It is not recommended touse this method as an extension point.

Usage

Geom$handle_na(data, params)

Arguments

data

A data frame with the layer's data coming from theupdate_defaults() method.

params

A list of parameters coming from thesetup_params()method

Value

A data frame with layer data

draw_layer

Description

A function method orchestrating the drawing of the entire layer. Thedefault method splits the data and passes on drawing tasks to thepanel-leveldraw_panel() method. It is not recommended to use this methodas an extension point.

Usage

Geom$draw_layer(data, params, layout, coord)

Arguments

data

A data frame with the layer's data.

params

A list of parameters

layout

A completed⁠<Layout>⁠ ggproto object.

coord

A⁠<Coord>⁠ ggproto object.

Value

A list of grobs, one per panel

draw_panel,draw_group

Description

A function method orchestrating the drawing of the layer for a singlepanel or group. The defaultdraw_panel() method splits the data into groups,passes on the drawing tasks to the group-leveldraw_group() method andfinally assembles these into a single grob. The defaultdraw_group methodis not implemented.

Usage

Geom$draw_panel(data, panel_params, coord, ...)Geom$draw_group(data, panel_params, coord, ...)

Arguments

data

A data frame with the layer's data.

panel_params

A list of per-panel parameters constructed byCoord$setup_panel_params(). This should be considered an opaque datastructure that is just passed along when calling coord methods.

coord

A⁠<Coord>⁠ ggproto object. To correctly scale theposition data, one should always callcoord$transform(data, panel_params). When working with non-linearcoordinate systems, data should be converted to fit a primitive geom(e.g. point, path or polygon) and passed on to the corresponding drawmethod formunching.

...

Reserved for extensions. By default, this is passed on tothedraw_group() method.

Value

A single grob orzeroGrob() when there is nothing to draw. Fordraw_panel() this can be agTree holding individual grobsfrom thedraw_group() method.

parameters

Description

A function method for listing out all acceptable parameters for this geom.

Usage

Geom$parameters(extra)

Arguments

extra

A boolean: whether to include theextra_params field.

Value

A character vector of parameter names.

aesthetics

Description

A function method for listing out all acceptable aesthetics for this geom.

Usage

Geom$aesthetics()

Value

A character vector of aesthetic names.

Conventions

The object name that a new class is assigned to is typically the same asthe class name. Geom class names are in UpperCamelCase and start with the⁠Geom*⁠ prefix, likeGeomNew.

A constructor function is usually paired with a Geom class. The constructorwraps a call tolayer(), where e.g.layer(geom = GeomNew). The constructorfunction name is formatted by taking the Geom class name and formatting itwith snake_case, so thatGeomNew becomesgeom_new().

See Also

Thenew geoms section of the online ggplot2 book.

Runvignette("extending-ggplot2"), in particular the "Creating anew geom" section.

Other Layer components:Layer-class,Position,Stat

Examples

# Extending the classGeomSimplePoint <- ggproto(  "GeomSimplePoint", Geom,  # Fields  required_aes = c("x", "y"),  draw_key     = draw_key_point,  # Methods  draw_panel = function(data, panel_params, coord) {    data <- coord$transform(data, panel_params)    grid::pointsGrob(data$x, data$y)  })# Building a constructorgeom_simple_point <- function(mapping = NULL, data = NULL, stat = "identity",                              position = "identity", ..., na.rm = FALSE,                              show.legend = NA, inherit.aes = TRUE) {  layer(    mapping = mapping, data = data,    geom = GeomSimplePoint, stat = stat, position = position,    show.legend = show.legend, inherit.aes = inherit.aes,    params = list(na.rm = na.rm, ...)  )}# Use new geom in plotggplot(mpg, aes(displ, hwy)) +  geom_simple_point()

Guides

Description

The⁠guide_*⁠ functions (likeguide_legend()) return⁠Guide*⁠ objects(likeGuideLegend). The⁠Guide*⁠ object is responsible for rendering theguide for at least one aesthetic.

Details

Each of the⁠Guide*⁠ objects is aggproto() object, descended from thetop-levelGuide, and each implements various methods and fields.

Building a guide has three stages:

1. The guide extracts the relevant information from scales.

2. The guide interacts with other parts of the plot, like coords or layers tosupplement information.

3. The guide is rendered.

When creating a new Guide class, you may want to consider overriding one ormore of the following:

• Theparams,elements,hashables andavailable_aes fields.

• Theextract_key(),extract_decor() andextract_params() methods.

• Thetransform() orget_layer_key() methods.

• Thesetup_params() andoverride_elements() methods.

• Any of the⁠build_*⁠ methods.

• As a last resort themeasure_grobs(),arrange_layout(), andassemble_drawing() methods.

Fields

params

A list of initial parameters that the guide needs tofunction. The baseGuide$params contains mandatory parameters,but extensions can add new parameters. It has the following roles:

• It provides the default values for parameters.

• names(params) determines what are valid arguments fornew_guide().

• During build stages, a mutable copy ofparams holds informationabout the guide.

available_aes

A character vector of aesthetic names for which theguide is appropriate. Can use keyword"any" to indicate all non-positionaesthetics.

elements

A named list of strings stating which theme elements thisguide uses. By default, strings will be translated inGuide$setup_elements() usingcalc_element(). Strings are expected tooccur innames(get_element_tree()), like"legend.text" for example.Position guides typically append the⁠{aes}.{position}⁠ suffix in thesetup_elements() method when the position is known.

hashables

A list of calls or names constructed byrlang::exprs()indicating objects in theparams field. These will be evaluated in thecontext of theparams field and the resulting list will be hashed. Thehash uniquely identify guides that can merge. Guides that have differenthashes will not merge. For extensions, you should include objects thatclearly mark two guides from one another that cannot be merged.

train

Description

A function method for orchestrating the training of a guide, which extractsnecessary information from a Scale object. As orchestrator, this method isnot intended for extension.

Usage

Guide$train(params, scale, aesthetic, ...)

Arguments

params

A list of parameters initiated by theparams field.

scale

A⁠<Scale>⁠ ggproto object. In the case of positionguides, can be a⁠<ViewScale>⁠ ggproto object.

aesthetic

A scalar string specifying the aesthetic.If missing (default), it will use the first aesthetic specified in thescale.

...

Additional parameters passed on to theextract_params()method.

Value

A modified list of parameters

extract_key

Description

A function method for extracting break information from the scale calledthe 'key'. It retrieves breaks, maps these breaks and derives labels. Theseform the basis for tick marks and labels in some guides. It is appropriateto override in extensions.

Usage

Guide$extract_key(scale, aesthetic, ...)

Arguments

scale

A⁠<Scale>⁠ ggproto object. In the case of positionguides, can be a⁠<ViewScale>⁠ ggproto object.

aesthetic

A scalar string specifying the aesthetic.

...

Optional arguments from theparams field.

Value

A 'key' data frame containing annotated scale breaks, including at least acolumn for the aesthetic,.label and.value. If there are no breaks,returnsNULL.

extract_decor

Description

A function method for extracting 'decor' from the scale. The 'decor' actsas a wildcard for anything the guide may need to render that is not basedon the key. For this reason, it has guide specific meaning that indicatesdifferent things for different guides. Inguide_colourbar() it is thecolour gradient, but inguide_axis() it is the axis line information.It is appropriate to override in extensions.

Usage

Guide$extract_decor(scale, aesthetic, ...)

Arguments

scale

A⁠<Scale>⁠ ggproto object. In the case of positionguides, can be a⁠<ViewScale>⁠ ggproto object.

aesthetic

A scalar string specifying the aesthetic.

...

Optional arguments from theparams field.

Value

Undefined.NULL by default.

extract_params

Description

A function method for extracting any other information from the scale thatthe guide may need. A typical example is to derive the title from the scale,or apply any edits to thekey ordecor variables.

Usage

Geom$extract_params(scale, params, ...)

Arguments

scale

A⁠<Scale>⁠ ggproto object. In the case of positionguides, can be a⁠<ViewScale>⁠ ggproto object.

params

A list of parameters initiated by theparams field,which at this point includes thekey anddecor from previousextractors.

...

Additional arguments passed from thetrain() method. Fornon-position guides, often includestitle as derived from theplot$labels field.

Value

A modified list of parameters

transform

Description

A function method to apply coord transformation and munching to the'key' and 'decor' parameters. This method only applies to position guideslikeguide_axis() and is not called for non-position guides. It isrecommended to override this method if you have a position guide thatdoes not inherit fromGuideAxis or has custom key' or 'decor' structuresthatGuideAxis$transform() does not handle well.

Usage

Guide$transform(params, coord, ...)

Arguments

params

A list of parameters initiated by theparams field.

coord

A⁠<Coord>⁠ ggproto object.

...

Optional arguments, typicallypanel_params for mostposition guides.

Value

A list of parameters. The default throws an error.

merge

Description

A function method for combining information from two guides. When twoguides have the same computedhash parameter derived from thehashablesfield, this function will be called to merge them. If more than two guidesneed to be merged, they are merged successively in aReduce()-likefashion.

Merging guides is the mechanism by whichguide_legend() can take oneguide trained on theshape scale, another trained on thecolour scaleand display them together in the same guide, for example.

Overriding this method is recommended if the extension descends directlyfromGuide and not its children. Otherwise, it should be overridden ifpresented with no superior options.

Usage

Guide$merge(params, new_guide, new_params)

Arguments

params

A list of parameters derived from theparams field ofthis guide.

new_guide

A⁠<Guide>⁠ ggproto object representing the other guide class

new_params

A list of parameters derived from theparams fieldof the other guide

Value

A named list containingguide andparams, whereguide is a⁠<Guide>⁠ggproto object andparams is a list with parameters. By default, returnsthe new guide and its parameters.

process_layers,get_layer_key

Description

These function methods extract information from layers that the guide mayneed. Theprocess_layers() method is tasked with selecting layers thatare represented by the guide and are to be included. The selected layersshould be passed on to theget_layer_key() method.

Typical use of these methods is forguide_legend() to extract theGeom$draw_key function to render glyphs in addition to any default orfixed aesthetics. While these methods are called in position guides,thelayers anddata arguments are empty as these are unavailable atthat point.

You can overrideget_layer_key(), butprocess_layers() shouldprobably only be overridden if the extension does not inherit fromGuideLegend.

Usage

Guide$process_layers(params, layers, data, theme)Guide$get_layer_key(params, layers, data, theme)

Arguments

params

A list of parameters initiated by theparams field.

layers

A list of layers fromplot$layers.

data

A list of layer data frames.

theme

Acompleted theme object.

Value

A list of parameters

draw

Description

A function method is the main orchestrator for drawing the guide. It setsup the final pieces in context of the position, direction and themeand. Subsequenty, it renders the individual components like titles, ticks,labels and decor. Finally, it arranges these components into a guide.

This method should only be overridden if the extension has non standardcomponents that do not fit into 'decor' or when this method can be greatlysimplified for humble guides. All subsidiaries are fine to override.

Usage

Geom$setup_params(theme, position, direction, params)

Arguments

theme

Acomplete theme object.

position

A scalar string indicating the position wherethe guide should be drawn. Typically"top","right","bottom"or"left", unless it is a position guide for an exotic coord. Can beNULL, in which caseparams$position should be used.

direction

A scalar string indicating the legend direction.Can beNULL, in which caseparams$direction should be used.

params

A list of parameters initiated by theparams field.

Value

A grob with the guide.

draw_early_exit

Description

A function method that determines what should be drawn when the guide 'key'is empty. The default method returnszeroGrob(). You can overridethis method if an empty key should draw anything. Used inguide_axis()to render theaxis.line part even if no ticks or labels should be drawn.

Usage

Guide$draw_early_exit(params, elements)

Arguments

params

A list of parameters initiated by theparams field.

elements

A list of elements or resolved theme settings fromtheoverride_elements() method.

Value

A grob.

setup_params

Description

A function method for finalising parameters. Typically used to make checkson theparams object or to make any position or direction basedadjustments.

Usage

Guide$setup_params(params)

Arguments

params

A list of parameters initiated by theparams field.

Value

A list of parameters

setup_elements,override_elements

Description

A function method for resolving required theme elements. Thesetup_elements() method joins local guide theme with global theme andcalculates the necessary theme elements. Theoverride_elements() methodis a hook to edit elements after they've been calculated.

You can override thesetup_elements() method if you need more complicatedtheme handling before calculating elements or want to intervene in inheritance.For example,guide_legend() has special handling of text margins andguide_axis() suffixes⁠{aes}.{position}⁠ to get the theme elements forthe correct position.

For other purposes, you can override theoverride_elements() method.

Usage

Guide$setup_elements(params, elements, theme)Guide$override_elements(params, elements, theme)

Arguments

params

A list of parameters initiated by theparams field.

elements

A named list of strings initiated by theelements field.

theme

Acomplete theme

Value

A list of elements or resolved theme settings.

build_title

Description

A function method for rendering the title. Note that titles for positionguides are rendered by the Facet class and not this method.

You can override this method if you need to render more than one title(or none) or adjust margin settings.

Usage

Guide$build_title(label, elements, params)

Arguments

label

A single string or expression with the title text.

elements

A list of elements or resolved theme settings fromtheoverride_elements() method. The default method expectselements$title to inherit from the⁠<element_text>⁠ class.

params

A list of parameters initiated by theparams field.

Value

A grob representing the title.

build_ticks

Description

A function method for rendering tick marks.

You can override this function if you don't need ticks or have completelydifferent logic on how these should be drawn.

Usage

Guide$build_ticks(key, elements, params, position, length)

Arguments

key

A data frame with the key information derived from theextract_key() method.

elements

A list of elements or resolved theme settings fromtheoverride_elements() method. The default method expectselements$ticks to inherit from the⁠<element_line>⁠ class andelements$ticks_length to be a scalar⁠<unit>⁠ object.

params

A list of parameters initiated by theparams field.

position

A scalar string indicating the position. Due tohistoric error this works in the opposite way to intuition: if you wantticks for an axis at the bottom of a plot, you should use"top" here.

length

A scalar⁠<unit>⁠ object giving the tick length.

Value

A grob representing tick marks.

build_labels

Description

A function method for rendering labels. The default method returns anempty grob. It is recommended to override this method when your extensiondirectly descends from Guide.

Usage

Guide$build_labels(key, elements, params)

Arguments

key

A data frame with the key information derived from theextract_key() method.

elements

A list of elements or resolved theme settings fromtheoverride_elements() method. Most non-default methods expectselements$text to inherit from the⁠<element_text>⁠.

params

A list of parameters initiated by theparams field.

Value

A grob representing labels.

build_decor

Description

A function method for rendering decor. As the 'wildcard' component, thiscan draw whatever component the guide needs that isn't already captured bythe key. The default method returns an empty grob. It is recommended tooverride this method.

For some examples:guide_legend() renders the keys with the glyphs,guide_colourbar() renders the colour gradient rectangle andguide_axis() renders the axis line.

Usage

Guide$build_decor(decor, grobs, elements, params)

Arguments

decor

A data frame (or other structure) with information derivedfrom theextract_decor() method.

grobs

A list with grobs generated by the other⁠build_*⁠methods.

elements

A list of elements or resolved theme settings fromtheoverride_elements() method. Most non-default methods expectselements$text to inherit from the⁠<element_text>⁠.

params

A list of parameters initiated by theparams field.

Value

A grob.

measure_grobs

Description

A function method for measuring grobs. In preparation for arranging grobs,they often need to be measured to determine their widths and heights.It is convention that every measurement is converted to centimetres.You can override this method if your extension directly descends fromGuide, or the parent class measurement is defective.

Usage

Guide$measure_grobs(grobs, params, elements)

Arguments

grobs

A list with grobs generated by the⁠build_*⁠ methods.

params

A list of parameters initiated by theparams field.

elements

A list of elements or resolved theme settings fromtheoverride_elements() method.

Value

A named list or⁠<unit>⁠ vector giving sizes of components, coordinatedwitharrange_layout() andassemble_drawing() methods. The defaultmethod returnsNULL.

arrange_layout

Description

A function method for determining the location or order of grobs in agtable. Typically determines rows and columns where decor and labels areplaced. Titles are added seperately.You can override this method if yourextension directly descends from Guide.

Usage

Guide$arrange_layout(key, sizes, params, elements)

Arguments

key

A data frame with the key information derived from theextract_key() method.

sizes

A list of⁠<unit>⁠ vector from themeasure_grobs() method.

params

A list of parameters initiated by theparams field.

elements

A list of elements or resolved theme settings fromtheoverride_elements() method.

Value

Any structure holding placement information coordinated with theassemble_drawing() method.

assemble_drawing

Description

A function method that takes measurements, placement information and grobsand assembles these together in a gtable structure. You can override thismethod if your extension directly descends from Guide, or the parent classassembly does not work for your guide.

Usage

Guide$assemble_drawing(grobs, layout, sizes, params, elements)

Arguments

grobs

A list with grobs generated by the⁠build_*⁠ methods.

layout

A data structure from thearrange_layout() method.

sizes

A list of⁠<unit>⁠ vector from themeasure_grobs() method.

params

A list of parameters initiated by theparams field.

elements

A list of elements or resolved theme settings fromtheoverride_elements() method.

Value

A finished gtable containing the guide.

arrange_layout

Description

A function method for placing the title. It is a subsidiary method usedin theassemble_drawing() method for non-position guides. Titles aretypically added beforelegend.margin is applied. It is notrecommended to override this method.

Usage

Guide$add_title(gtable, title, position, just)

Arguments

gtable

An unfinished gtable under construction in theassemble_drawing() method.

title

The grob resulting from thebuild_title() method.

position

A scaler string, either"top","right","bottom"or"left" corresponding to thelegend.title.position.

just

A named list havinghjust andvjust components withscalar numeric values between 0 and 1.

Value

Thegtable argument with added title.

Conventions

The object name that a new class is assigned to is typically the same as theclass name. Guide class names are in UpperCamelCase and start with the⁠Guide*⁠ prefix, likeGuideNew.

A constructor function is usually paired with a Guide class. The constructorwraps a call tonew_guide(), where e.g.new_guide(super = GuideNew). Theconstructor name is formatted by taking the Guide class name and formattingit with snake_case, so thatGuideNew becomesguide_new().

See Also

Runvignette("extending-ggplot2"), in particular the "Creatingnew guides" section.

Examples

# Extending the classGuideDescribe <- ggproto(  "GuideDescribe", Guide,  # Fields  elements  = list(text = "legend.text", margin = "legend.margin"),  hashables = rlang::exprs(key$.label),  # Methods  build_title = function(...) zeroGrob(), # Turn off title  build_labels = function(key, elements, params) {    labels <- key$.label    n <- length(labels)    labels <- paste0(paste0(labels[-n], collapse = ", "), ", and ", labels[n])    labels <- paste0("A guide showing ", labels, " categories")    element_grob(elements$text, label = labels, margin_x = TRUE, margin_y = TRUE)  },  measure_grobs = function(grobs, params, elements) {    # Measuring in centimetres is the convention    width  <- grid::convertWidth(grid::grobWidth(grobs$labels), "cm", valueOnly = TRUE)    height <- grid::convertHeight(grid::grobHeight(grobs$labels), "cm", valueOnly = TRUE)    list(width = unit(width, "cm"), height = unit(height, "cm"))  },  assemble_drawing = function(self, grobs, layout, sizes, params, elements) {    gt <- gtable::as.gtable(grobs$labels, width = sizes$width, height = sizes$height)    gt <- gtable::gtable_add_padding(gt, elements$margin)    gt  })# Building a constructorguide_describe <- function(position = NULL) {  new_guide(position = position, super = GuideDescribe)}# Use new guide plotggplot(mpg, aes(displ, hwy, colour = class)) +  geom_point() +  guides(colour = guide_describe("bottom"))

Layers

Description

The Layer class is a chaperone class not available for extension. The classfulfils the following tasks. The class houses the Geom, Stat and Positiontrinity and tracks their stateful parameters. Furthermore, its methods areresponsible for managing the layer data and exposing it to other componentsof the plot at the right time.

Details

The Layer class is an internal class that is not exported because the classis not intended for extension. Thelayer() function instantiates theLayerInstance class, which inherits from Layer, but has relevant fieldspopulated.

The class is mostly used inggplot_build(), with the notable exceptionof thedraw_geom() method, which is used inggplot_gtable() instead.

Fields

constructor

Acall object with the user-facingconstructor function, for use in error messaging. This field is populatedbylayer().

geom,stat,position

These fields house the Geom, Stat and Positiontrifecta in ggproto form and is populated bylayer().

stat_params,computed_stat_params

These fields hold parametersassigned to the Stat. Thestat_params field is directly derived fromuser input and is populated bylayer(). Thecomputed_stat_paramscarries state and is constructed by theStat$setup_params() method.

geom_params,computed_geom_params

These fields hold parametersassigned to the Geom. Thegeom_params field is directly derived fromuser input and is populated bylayer(). Thecomputed_geom_paramscarries state and is constructed by theGeom$setup_params() method.

mapping,computed_mapping

These fields holdmappings.Themapping field holds thelayer(mapping) argument. Thecomputed_mapping field carries state and is constructed in thesetup_layer() method.

data

The fortifiedlayer(data) argument.

aes_params

Holds the fixed, unmapped aesthetics passed tolayer(params) as determined byGeom$aesthetics().

inherit.aes

A scalar boolean used in thesetup_layer() method toindicate whether thecomputed_mapping should include the global mapping(TRUE) or only the layer mapping (FALSE). This is populated by thelayer(inherit.aes) parameter.

layer_data

Description

A function method for initially resolving layer data. If layer data ismissing or is a function, it will derive layer data from the global plotdata.

Usage

Layer$layer_data(plot_data)

Arguments

plot_data

Thedata field of the ggplot object.

Value

A data frame with layer data orNULL

setup_layer

Description

A function method is a hook to allow a final access to layer data ininput form. In addition, it allows a layer access to global plotinformation. The latter is used to enforce theinherit.aes parameter bysupplementing the layer mapping with the global mapping when requested.

Usage

Layer$setup_data(data, plot)

Arguments

data

A data frame with the layer's data.

plot

A ggplot object

Value

A data frame with layer data. As a side effect, thecomputed_mappingfield is populated.

compute_aesthetics

Description

A function method that evaluates aesthetics and warns about any problems.It also infers agroup aesthetic if not provided. This method is alsothe step where layer data becomes standardised to base data frames withoutrow names or additional attributes.

Usage

Layer$compute_aesthetics(data, plot)

Arguments

data

A data frame with the layer's data.

plot

A ggplot object

Value

A data frame with layer data

compute_aesthetics

Description

A function method that orchestrates computing statistics. It executesmethods from the Stat class to form new computed variables.

Usage

Layer$compute_statistic(data, layout)

Arguments

data

A data frame with the layer's data.

layout

A⁠<Layout>⁠ ggproto object.

Value

A data frame with layer data. As a side effect thecomputed_stat_paramsfield is populated.

map_statistic

Description

A function method that finishes the result of computed statistics. It hasseveral tasks:

• It evaluates theafter_stat() stage of the mapping from both thecomputed_mapping but also theStat$default_aes fields.

• It ensures relevant scales are instantiated for computed aesthetics.

• It takes care that scale transformation is applied to computed aesthetics.

Usage

Layer$map_statistic(data, plot)

Arguments

data

A data frame with the layer's data.

plot

A ggplot object.

Value

A data frame with layer data

compute_geom_1

Description

A function method that prepares data for drawing. It checks that allrequired aesthetics are present and sets up parameters and data using theGeom class.

Usage

Layer$compute_geom_1(data)

Arguments

data

A data frame with the layer's data.

Value

A data frame with layer data. As a side effect thecomputed_geom_paramsfield is populated.

compute_position

Description

A function method that orchestrates the position adjustment. It executesmethods from the Position class.

Usage

Layer$compute_position(data, layout)

Arguments

data

A data frame with the layer's data.

layout

A⁠<Layout>⁠ ggproto object.

Value

A data frame with layer data.

compute_geom_2

Description

A function method that add defaults and fixed parameters. It wraps theGeom$use_defaults() method.

Usage

Layer$compute_geom_2(data, params, theme, ...)

Arguments

data

A data frame with the layer's data.

params

A list with fixed aesthetic parameters, typically theaes_params field.

theme

Atheme object

...

Passed on toGeom$use_defaults(), not in use.

Value

A data frame with layer data.

finish_statistics

Description

A function method that wrapsStat$finish_layer().

Usage

Layer$finish_statistics(data)

Arguments

data

A data frame with the layer's data.

Value

A data frame with layer data.

draw_geom

Description

A function method that produces graphics for every panel. It uses Geomclass methods to handle missing data and produce grobs. In contrast toother methods, this is called during theggplot_gtable() stage, not theggplot_build() stage.

Usage

Layer$draw_geom(data, layout)

Arguments

data

A data frame with the layer's data.

layout

A⁠<Layout>⁠ ggproto object.

Value

A list of grobs, one per panel.

print

Description

A function method that prints information about the layer.

Usage

Layer$print()

Value

Nothing (NULL), invisibly

Layer data diagram

As the Layer class is a chaparone for the data, it makes sense to give asmall overview of how layer data flows through a plot. In the diagram belowwe following thelayer(data) argument over the course of plot buildingthrough Layer class methods. When an outside class acts on the data withoutthe Layer class, this is indicated with the left arrow⁠<-⁠. Subcomponentsof a method that touch data are indicated with the right arrow⁠->⁠.

# Inside `ggplot_build()` |layer(data) | | | # Inherit plot data |Layer$layer_data() | | | # Finalise mapping |Layer$setup_layer() | | | # Append PANEL variable for facets | |<- Layout$setup() |    | |    +-> Facet$setup_data() |    | |    +-> Coord$setup_data() | | | # Evaluate mappings to new data and infer group |Layer$compute_aesthetics() | | | # Scale-transform all aesthetics | |<- ScalesList$transform_df() |    | |    +-> Scale$transform_df() | | | # Map x/y aesthetics with initial scale | |<- Layout$map_position() |    | |    +-> Scale$map() | | | # Compute stat part of layer |Layer$compute_statistic() | | | +-> Stat$setup_data() | | | +-> Stat$compute_layer() | | | # Add `after_stat()` stage | # Scale transform computed variables |Layer$map_statistic() | | | # Setup geom part of layer |Layer$compute_geom_1() | | | +-> Geom$setup_data() | | | # Apply position adjustments |Layer$compute_position() | | | +-> Position$use_defaults() | | | +-> Position$setup_data() | | | +-> Position$compute_layer() | | | # Map x/y aesthetics with final scales | |<- Layout$map_position() |    | |    +-> Scale$map() | | # Map non-position aesthetics | |<- ScalesList$map_df() |    | |    +-> Scale$map() | | | # Fill in defaults and fixed aesthetics |Layer$compute_geom_2() | | | +-> Geom$use_defaults() | | | # Apply final Stat hook |Layer$finish_statistics() | | | +-> Stat$finish_layer() | | | # Apply final Facet hook | |<- Layout$finish_data() |    | |    +-> Facet$finish_data() | V# `ggplot_build()` is finished# Hand off to `ggplot_gtable()` | | | # Draw the geom part |Layer$draw_geom() | +-> Geom$handle_na() | +-> Geom$draw_layer()

See Also

Other Layer components:Geom,Position,Stat

Other chaperone classes:Layout

Examples

# None: Layer is not intended to be extended

Layout

Description

The Layout class is a chaperone class discouraged for extension. The classfulfils the following tasks. The class houses the Coord and Facet classesand tracks their stateful parameters. In addition, it manages the positionscales for each panel. It is responsible for keeping track of panelspecifications and matching pieces of the data to scales and parameters inpanel-wise manners.

Details

The Layout class is only exported for extensions that re-implement aggplot_build() method for their specific class of plots. It is discouragedto subclass the Layout class and for all purposes be considered an internalstructure. It has no user-facing constructor to put an small barrier in theway.

The class is used throughoutggplot_build(), with the notable exception oftherender() method, which is used inggplot_gtable() instead.

Fields

coord,coord_params

A<Coord> ggproto object and a listof the coordinate system's parameters. Parameters get populated by theCoord$setup_params() method.

facet,facet_params

A<Facet> ggproto object and a listof the faceting specification's parameters. Parameters get populated bytheFacet$setup_params() method.

layout

A data frame with a row for each panel. The data framecontains integer columnsPANEL,SCALE_X,SCALE_Y,ROW andCOLrepresenting a panel ID, scale indices and placement locations. In addition,the layout may contain faceting variables or other additional information.This field gets populated by theFacet$compute_layout() method.

panel_scales_x,panel_scales_y

A list ofx andy position scalesparallel to the layout field'sSCALE_X andSCALE_Y levels respectively.This fields gets populated by theFacet$init_scales() method.

panel_params

A named list of parameters per panel populated by theCoord$setup_panel_params() method. Contains⁠<ViewScale>⁠ entries forthex andy variables in addition to ranges and other information thecoordinate system might need to transform or render guides and grids.

setup

Description

A function method for setting up the relevant information for the layoutof the plot. It populates thefacet_params,coord_params andlayoutfields and appends aPANEL variable to the layer data.

Usage

Layout$setup(data, plot_data, plot_env)

Arguments

data

A list of data frames with layer data.

plot_data

The data frame in thedata field of the ggplotobject.

plot_env

The environment in theplot_env field of theggplot object.

Value

A list of data frames from thedata argument with aPANEL variablecorresponding to rows in thelayout field.Also called for the side effects of populating fields.

train_position

Description

A function method for training position scales and optionally initiatingthem. Implementation is via theFacet$train_scales() andFacet$init_scales() methods.

Usage

Layout$train_position(data, x_scale, y_scale)

Arguments

data

A list of data frames with layer data.

x_scale,y_scale

A single prototype position scale for thexandy aesthetics respectively.

Value

Nothing, this method is called for the side effect of training scales andoptionally populating thepanel_scales_x andpanel_scales_y fields.

map_position

Description

A function method for mapping position aesthetics. For discrete scales thisconverts discrete levels to a numeric representation, usually integers. Forcontinuous scales, this applies out-of-bounds handling.

Usage

Layout$map_position(data)

Arguments

data

A list of data frames with layer data.

Value

A list of data frames per thedata argument with mapped positionaesthetics.

reset_scales

Description

A function method for resetting scale ranges. After computing stats andposition adjustments, scales need to be reset and re-trained to have anaccurate measure of the data limits. This goes through thepanel_scales_x andpanel_scales_y fields and invokes theScale$reset() method.

Usage

Layout$reset_scales()

Value

Nothing, it is called for the side-effect of resetting scale ranges.

setup_panel_params

Description

A function method for executingCoord$setup_panel_params() once per panelwith the appropriate scales. For efficiency reasons, the setup is invokedonce per unique combination ofx andy scale.

Usage

Layout$setup_panel_params()

Value

Nothing, it is called for the side effect of populating thepanel_paramsfield.

setup_panel_guides

Description

A function method for setting up and training the position guides (axes)once per panel with the appropriate scales. For efficiency reasons,the guides are setup once per unique combination ofx andy scale.It calls theCoord$setup_panel_guides() andCoord$train_panel_guides()methods.

Usage

Layout$setup_panel_guides(guides, layers)

Arguments

guides

A⁠<Guides>⁠ ggproto object from theguides field ofthe ggplot object.

layers

A list of layers from thelayers field of the ggplotobject.

Value

Nothing, it is called for the side effect of augmenting each entry of thepanel_params field with position guides.

setup_panel_guides

Description

A function method for setting up theFacet$finish_data() hook.

Usage

Layout$finish_data(data)

Arguments

data

A list of data frames with layer data.

Value

A list of data frames with layer data.

render

Description

A function method for drawing and assembling the core plot. Mostly itdelegates tasks to the specific Facet methods for drawing components.

Usage

Layout$render(panels, data, theme, labels)

Arguments

panels

A list parallel to layers. Each element is another listwith grobs for each panel, generated byLayer$draw_geom().

data

A list of data frames with layer data.

theme

Acomplete theme.

labels

A list of labels from thelabels field of the ggplotobject.

Value

A gtable containing a plot with panels, axes, axis titles and strips.

resolve_label

Description

A function method for prying the axis titles from guides, scales or plotlabels.

Usage

Layout$resolve_label(scale, labels)

Arguments

scale

A single scale from thepanel_scales_x orpanel_scales_y fields.

labels

A list of labels from thelabels field of the ggplotobject.

Value

A named list containing a two titles named"primary" and"secondary".

render_labels

Description

A function method for drawing axis title grobs. The position guidesthemselves do not typically render the axis title grobs as they areorchestrated by the layout to draw one title even for multiple axes.

Usage

Layout$render_labels(labels, theme)

Arguments

labels

A named list containing anx list and ay list. Thex andy lists haveprimary andsecondary labels. It originatesfrom theCoord$labels() method.

theme

Acomplete theme.

Value

A list with the same structure and names as thelabels argument, but withgrobs instead of text.

get_scales

Description

A function method for retrieving panel specific scales. It is called intheStat$compute_layer() andPosition$compute_layer() methods. TheGeom uses thepanel_params field instead of the raw scales.

Usage

Layout$get_scales(i)

Arguments

i

A scalar integer panel index giving the panel for which toretrieve scales

Value

A named list of scales giving thex andy scale for the panel.

See Also

Other Layout components:Coord,Facet

Other chaperone classes:Layer-class

Examples

# Some dummy layout componentsfacet <- facet_null()coord <- coord_cartesian()# Use in custom `ggplot_build()` methodslayout <- ggproto(NULL, Layout, facet = facet, coord = coord)

Positions

Description

All⁠position_*()⁠ functions (likeposition_dodge()) return a⁠Position*⁠ object (likePositionDodge). The⁠Position*⁠object is responsible for adjusting the position of overlapping geoms.

Details

The way that the⁠position_*⁠ functions work is slightly different fromthe⁠geom_*⁠ and⁠stat_*⁠ functions, because a⁠position_*⁠function actually "instantiates" the⁠Position*⁠ object by creating adescendant, and returns that. The object is chaperoned by theLayer class.

To create a new type of Position object, you typically will want to overrideone or more of the following:

• Therequired_aes anddefault_aes fields.

• Thesetup_params() andsetup_data() methods.

• One of thecompute_layer() orcompute_panel() methods.

Fields

required_aes

A character vector naming aesthetics that are necessaryto compute the position adjustment.

default_aes

Amapping of default values for aesthetics.

use_defaults

Description

A function method for completing the layer data by filling in defaultposition aesthetics that are not present. These can come from two sources:either from the layer parameters as static, unmapped aesthetics or fromthedefault_aes field.

Usage

Position$use_defaults(data, params)

Arguments

data

A data frame of the layer's data

params

A list of fixed aesthetic parameters

Value

A data frame with completed layer data

setup_params

Description

A function method for modifying or checking the parameters based on thedata. The default method returns an empty list.

Usage

Position$setup_params(data)

Arguments

data

A data frame with the layer's data.

Value

A list of parameters

setup_data

Description

A function method for modifying or checking the data. The default methodchecks for the presence of required aesthetics.

Usage

Position$setup_data(data, params)

Arguments

data

A data frame with the layer's data.

params

A list of parameters coming from thesetup_params()method

Value

A data frame with layer data

compute_layer

Description

A function method orchestrating the position adjust of the entire layer.The default method splits the data and passes on adjustment tasks to thepanel-levelcompute_panel(). In addition, it finds the correct scalesin the layout object to pass to the panel computation.

Usage

Position$compute_layer(data, params, layout)

Arguments

data

A data frame with the layer's data.

params

A list of parameters coming from thesetup_params()method

layout

A⁠<Layout>⁠ ggproto object.

Value

A data frame with layer data

compute_panel

Description

A function method executing the position adjustment at the panel level.The default method is not implemented.

Usage

Position$compute_panel(data, params, scales)

Arguments

data

A data frame with the layer's data.

params

A list of parameters coming from thesetup_params()method

scales

A list of pre-trainedx andy scales. Note that theposition scales are not finalised at this point and reflect the initialdata range before computing stats.

Value

A data frame with layer data

aesthetics

Description

A function method for listing out custom position aesthetics for thisposition adjustment.

Usage

Position$aesthetics()

Value

A character vector of aesthetic names.

Convention

The object name that a new class is assigned to is typically the same as theclass name. Position class name are in UpperCamelCase and start with the⁠Position*⁠ prefix, likePositionNew.

A constructor functions is usually paired with a Position class. Theconstructor copies the position class and populates parameters. Theconstructor function name is formatted by taking the Position class name andformatting it with snake_case, so thatPositionNew becomesposition_new().

See Also

Thenew positions section of the online ggplot2 book.

Other Layer components:Geom,Layer-class,Stat

Examples

# Extending the classPositionRank <- ggproto(  "PositionRank", Position,  # Fields  required_aes = c("x", "y"),  # Methods  setup_params = function(self, data) list(width = self$width),  compute_panel = function(data, params, scales) {    width <- params$width    if (is.null(width)) {      width <- resolution(data$x, zero = FALSE, TRUE) * 0.4    }    rank   <- stats::ave(data$y, data$group, FUN = rank)    rank   <- scales::rescale(rank, to = c(-width, width) / 2)    data$x <- data$x + rank    data  })# Building a constructorposition_rank <- function(width = NULL) {  ggproto(NULL, PositionRank, width = width)}# Use new position in plotggplot(mpg, aes(drv, displ)) +  geom_point(position = position_rank(width = 0.5))

Scales

Description

All⁠scale_*()⁠ functions (likescale_fill_continuous()) return a⁠Scale*⁠object. The main purpose of these objects is to translate data values toaesthetic values and populating breaks and labels.

Details

All⁠scale_*⁠ functions likescale_x_continuous() return a⁠Scale*⁠ objectlikeScaleContinuous. Each of the⁠Scale*⁠ objects is aggproto() objectdescended from the top-levelScale.

Scales generally need to track three types of spaces:

1. Data space. These are values as they are evaluated from the plotor layer mapping, prior to any transformation.

2. Transformed space. This is the space after original data has beentransformed. Effectively, scales internally operate in transformed spacein that ranges and breaks get passed around in this space. Discrete scalesdon't do transformations, so for these scales, transformed space is thesame as untransformed space.

3. Aesthetic space. Graphic values that are mapped from the transformedspace. This is dependent on thepalette field for most scales and on therescaler field for continuous position scales.

The user is expected to give any vector-basedminor_breaks,breaks orlimits in data space. Whenbreaks,limits orlabels is a function,its input is expected to be in data space.

Before you attempt to create a new⁠Scale*⁠ class of your own, it isrecommended to think through whether your aims cannot be implemented withone of the existing classes. Making a wrapper for thecontinuous_scale(),discrete_scale() andbinned_scale() should cover many cases, and shouldbe considered prior to commiting to build a⁠Scale*⁠ extension.

For example, if you aim to develop a scale for a new data type, it shouldgenerally be possible to create a newtransformationinstead. One reason to implement your own⁠Scale*⁠ class is to accommodatea data type does not lend itself for continuous or discrete range training.

In such case, you can override the following:

• Therange field.

• Thetransform,train andmap methods.

• Theget_limits(),get_breaks() andget_labels() methods.

Fields

call

Acall object with the user-facing constructorfunction, for use in error messaging. This field is populated by scaleconstructors.

range

ARange class object, likescales::ContinuousRange orscales::DiscreteRange. These are 'trained'to keep track of the data range (continuous) or data levels (discrete).Continuous ranges are tracked in transformed space.

aesthetics,palette,name,breaks,labels,limits,name,guide,position,na.value,expand

Fields populated by the scale constructor that can take on the same valuesas described in e.g.?continuous_scale.Note thatlimits is expected in transformed space.

transform_df,transform

Description

A function method for orchestrating the transformation of aesthetics in adata frame. Data transformation occurs before stats are computed.Thetransform_df() method ensures thetransform() method is appliedto the correct columns.

Usage

Scale$transform_df(df)Scale$transform(x)

Arguments

df

A data frame with the layer's data.

x

A vector of the relevant aesthetic.

Value

Fortransform() a vector of transformed values.Fortransform_df(), a named list with transformed values for eachtransformed aesthetic.

train_df,train

Description

A function method for orchestrating scale training for keeping track ofthe data range or levels. Thetrain_df() method ensures thetrain()method is applied to the correct columns.

Usage

Scale$train_df(df)Scale$train(x)

Arguments

df

A data frame with the layer's data.

x

A vector of the relevant aesthetic.

Value

Nothing, these are called for their side effect of updating therangefield.

map_df,map

Description

A function method for orchestrating the mapping of data values toaesthetics. Themap_df() method ensures themap() method is appliedto the correct columns. When the scale uses apalette() function, it isapplied in themap() method.

Usage

Scale$map_df(df, i)Scale$map(x, limits)

Arguments

df

A data frame with the layer's data.

i

An integer vector giving an index to map a subset of data.The default,NULL, will map all rows.

x

A vector of the relevant aesthetic.

limits

A vector of the relevant aesthetic, usually viatheget_limits() method.

Value

Formap() a vector of mapped values in aesthetics space.Formap_df(), a named list with mapped values for eachaesthetic.

recale

Description

A function method for applying the recale function in therescaler field.It is used during the continuousmap() andCoord$transform() methodsto ensure values are in the 0-1 range.

Usage

Scale$rescale(x, limits, range)

Arguments

x

A vector of values to rescale. Can contain out-of-boundsor missing values depending on themap() method.

limits

A length two vector giving the limits of the relevantaesthetic, usually via theget_limits() method.

range

A length two vector giving the range that should coincidewith the 0-1 points. For most purpuses, this should be the same as thelimits argument.

Value

A vector of values between 0 and 1 for in-bounds values ofx.

get_limits

Description

A function method for resolving user input and getting the scale limits.

Usage

Scale$get_limits()

Value

The scale limits, without any expansion applied, in transformed space.

dimension

Description

A function method for getting a continuous representation of the limits ofposition scales. For continuous scales, the dimension is the same conceptas the limits. For discrete scales the dimension is the continuous rangeoccupied by the mapped breaks, which by default take integer positions.

Usage

Scale$dimension(expand, limits)

Arguments

expand

A length 4 vector giving scaleexpansion.This is optional and defaults to no expansion.

limits

A vector of the relevant aesthetic, usually viatheget_limits() method.

Value

A numeric vector of length 2

get_breaks,get_breaks_minor

Description

A function method for resolving user input and getting the scale breaksor minor breaks. Note that these may return out-of-bounds values for thepurpose of coordinating with theget_labels() method.

Usage

Scale$get_breaks(limits)Scale$get_breaks_minor(n, b, limits)

Arguments

limits

A vector of the relevant aesthetic, usually viatheget_limits() method.

n

An integer setting the desired number of minor breaks permajor break. Note that the resulting minor breaks may coincide withmajor breaks.

b

A vector of mapped major breaks from theget_breaks()method.

Value

A vector of breaks in transformed space.

get_labels

Description

A function method for resolving user input and getting the scale labels fora set of breaks.

Usage

Scale$get_labels(breaks)

Arguments

breaks

A vector of unmapped major breaks from theget_breaks()method, in transformed space.

Value

A vector of labels of the same length asbreaks.

get_transformation

Description

A helper method to access the scale's transformation object.

Usage

Scale$get_transformation()

Value

Atransform object.

break_info

Description

A function method for getting all break related information for positionscales. It is in use by coords that do not use the modern Guide systemand secondary axes.

Usage

Scale$break_info(range)

Arguments

range

A vector of the relevant aesthetic.

Value

A named list with the following structure:

• range a length 2 vector giving continuous range

• labels a character or expression vector of the same length as major breaks.

• major a numeric vector with mapped numeric values for major breaks.

• major_source a numeric vector with (transformed) data values for major breaks.

• minor a numeric vector with mapped numeric values for minor breaks.

• minor_source a numeric vector with (transformed) data values for minor breaks.

break_position

Description

A function method for getting mapped break positions. It is in use as adefault value inget_breaks_minor(), but is otherwise vestigial.

Usage

Scale$break_info(range)

Arguments

range

A vector of the relevant aesthetic.

Value

A vector with mapped break positions

make_title,make_sec_title

Description

A function method for picking the title to use. This is usually called intheGuide$extract_params() orLayout$resolve_label() methods.The hierarchy of titles goes from guide (highest priority), to scale, tolabs (lowest priority).When the guide or scale title are functions, they're applied to the nextin line. Themake_sec_title() method by default re-uses the primarymake_title() method and only applies to position aesthetics.

Usage

Scale$make_title(guide_title, scale_title, label_title)Scale$make_sec_title(...)

Arguments

guide_title

Thetitle parameter coming from a guide.

scale_title

Thename field of the Scale.

label_title

The relevant entry in theplot$labels field.

...

By default, arguments forwarded to themake_title()method

Value

A scalar character or expression title

axis_order

Description

A function method for setting the order of axes titles used to coordinatewithFacet$draw_labels().

Usage

Scale$axis_order()

Value

Eitherc("primary", "secondary") orc("secondary", "primary").

clone

Description

A function method for making an untrained copy of the scale. Due toreference semantics of ggproto objects, in contrast to copy-on-modifysemantics, scales need to be cloned at the start of plot building.The cloned scale can be trained independently of the original.

Usage

Scale$clone()

Value

A Scale object.

reset

Description

A function method for to reset therange field, effectively 'untraining'the scale. This is used in theLayout$reset_scales() method, so thatscales can be re-trained on data with final position aesthetics.For discrete scales, only the continuous range (range_c) is reset.

Usage

Scale$clone()

Value

None, called for the side-effect of resetting the range.

is_empty

Description

A function method for determining whether a scale is empty, i.e. when noinformation with which to calculate limits.

Usage

Scale$is_empty()

Value

A scalar boolean value.

is_empty

Description

A function method for determining whether a scale is discrete.

Usage

Scale$is_discrete()

Value

A scalar boolean value.

Conventions

The object name that a new class is assigned to is typically the same as theclass name. Scale class names are in UpperCamelCase and start with the⁠Scale*⁠ prefix, likeScaleNew.

In scales, there is a difference between user-facing and developer-facingconstructors. Developer facing constructors have the shape⁠{foundation}_scale()⁠, likediscrete_scale() corresponding toScaleDiscrete. User-facing constructors have the⁠scale_{aesthetic}_{type}⁠as name. If you implement a new⁠Scale*⁠ class, you like want both thesetypes of constructor.

Examples

# TODO: find easy to digest exampleNULL

Stats

Description

All⁠stat_*()⁠ functions (likestat_bin()) return a layer thatcontains a⁠Stat*⁠ object (likeStatBin). The⁠Stat*⁠object is responsible for rendering the data in the plot.

Details

Each of the⁠Stat*⁠ objects is aggproto() object, descendedfrom the top-levelStat, and each implements various methods andfields. The object and its parameters are chaperoned by theLayer class.

To create a new type of Stat object, you typically will want tooverride one or more of the following:

• Therequired_aes anddefault_aes fields.

• One of thecompute_layer(),compute_panel() orcompute_group()functions. Typically it best to implementcompute_group() and use thehigher-up methods when there are substantial performance improvements tobe gained.

• Thefinish_layer() method

Fields

required_aes

A character vector naming aesthetics that are necessaryto compute the stat.

non_missing_aes

A character vector naming aesthetics that will causeremoval if they have missing values.

optional_aes

A character vector naming aesthetics that will beaccepted bylayer(), but are not required or dscribed in thedefault_aesfield.

default_aes

Amapping of default values for aesthetics.Aesthetics can be set toNULL to be included as optional aesthetic.

dropped_aes

A character vector naming aesthetics that can be droppedfrom the data without warning. Typically used for aesthetics that are'consumed' during computation like"weight".

extra_params

A character vector of parameter names in addition tothose imputed from thecompute_panel() orcompute_groups() methods.This field can be set to include parameters forsetup_data() methods.By default, this only contains"na.rm".

retransform

A scalar boolean: should the values produced by thestatistic also be transformed in the second pass when recently addedstatistics are trained to the scales

setup_params

Description

A function method for modifying or checking the parameters based on thedata. The default method returns the parameters unaltered.

Usage

Stat$setup_params(data, params)

Arguments

data

A data frame with the layer's data.

params

A list of current parameters

Value

A list of parameters

setup_data

Description

A function method for modifying or checking the data. The default methodreturns data unaltered.

Usage

Stat$setup_data(data, params)

Arguments

data

A data frame with the layer's data.

params

A list of parameters coming from thesetup_params()method

Value

A data frame with layer data

compute_layer

Description

A function method for orchestrating the computation of the statistic. Thedefault method splits the data and passes on computation tasks to thepanel-levelcompute_panel() method. In addition, the default methodhandles missing values by removing rows that have missing values for theaesthetics listed in therequired_aes andnon_missing_aes fields. It isnot recommended to use this method as an extension point.

Usage

Stat$compute_layer(data, params, layout)

Arguments

data

A data frame with the layer's data.

params

A list of parameters

layout

A pre-trained⁠<Layout>⁠ ggproto object.

Value

A data frame with computed data

compute_panel,compute_group

Description

A function method orchestrating the computation of statistics for a singlepanel or group. The defaultcompute_panel() method splits the data intogroups, and passes on computation tasks to thecompute_group() method.In addition,compute_panel() is tasked with preserving aesthetics thatare constant within a group and preserving these if the computation losesthem. The defaultcompute_group() is not implemented.

Usage

Stat$compute_panel(data, scales, ...)Stat$compute_group(data, scales, ...)

Arguments

data

A data frame with the layer's data.

scales

A list of pre-trainedx andy scales. Note that theposition scales are not finalised at this point and reflect the initialdata range before computing stats.

...

Reserved for extensions. By default, this passes parametersto thecompute_group() method.

Value

A data frame with layer data

finish_layer

Description

A function method acting as a hook to modify data after scales have beenapplied, but before geoms have to render. The default is to pass the dataunaltered. This can be used as an extension point when actual aestheticvalues rather than values mapped to the aesthetic are needed.

Usage

Stat$finish_layer(data, params)

Arguments

data

A data frame with layer data

params

A list of parameters

Value

A data frame with layer data

parameters

Description

A function method for listing out all acceptable parameters for this stat.

Usage

Stat$parameters(extra)

Arguments

extra

A boolean: whether to include theextra_params field.

Value

A character vector of parameter names.

aesthetics

Description

A function method for listing out all acceptable aesthetics for this stat.

Usage

Stat$aesthetics()

Value

A character vector of aesthetic names.

Conventions

The object name that a new class is assigned to is typically the same as theclass name. Stat class names are in UpperCamelCase and start with the⁠Stat*⁠prefix, likeStatNew.

A constructor function is usually paired wih a Stat class. The constructorwraps a call tolayer(), where e.g.layer(stat = StatNew). Theconstructor function name is formatted by taking the Stat class name andformatting it with snake_case, so thatStatNew becomesstat_new().

See Also

Thenew stats section of the online ggplot2 book..

Runvignette("extending-ggplot2"), in particular the "Creating anew stat" section.

Other Layer components:Geom,Layer-class,Position

Examples

# Extending the classStatKmeans <- ggproto(  "StatKmeans", Stat,  # Fields  required_aes = c("x", "y"),  # You can relate computed variables to aesthetics using `after_stat()`  # in defaults  default_aes = aes(colour = after_stat(cluster)),  # Methods  compute_panel = function(data, scales, k = 2L) {    km <- kmeans(cbind(scale(data$x), scale(data$y)), centers = k)    data$cluster <- factor(km$cluster)    data  })# Building a constructorstat_kmeans <- function(mapping = NULL, data = NULL, geom = "point",                        position = "identity", ..., k = 2L, na.rm = FALSE,                        show.legend = NA, inherit.aes = TRUE) {  layer(    mapping = mapping, data = data,    geom = geom, stat = StatKmeans, position = position,    show.legend = show.legend, inherit.aes = inherit.aes,    params = list(na.rm = na.rm, k = k, ...)  )}# Use new stat in plotggplot(mpg, aes(displ, hwy)) +  stat_kmeans(k = 3)

Absolute grob

Description

This grob has fixed dimensions and position.

Usage

absoluteGrob(  grob,  width = NULL,  height = NULL,  xmin = NULL,  ymin = NULL,  vp = NULL)

Details

It's still experimental

Add components to a plot

Description

+ is the key to constructing sophisticated ggplot2 graphics. Itallows you to start simple, then get more and more complex, checking yourwork at each step.

Usage

add_gg(e1, e2)e1 %+% e2

Arguments

What can you add?

You can add any of the following types of objects:

• Anaes() object replaces the default aesthetics.

• A layer created by ageom_ orstat_ function adds anew layer.

• Ascale overrides the existing scale.

• Atheme() modifies the current theme.

• Acoord overrides the current coordinate system.

• Afacet specification overrides the current faceting.

To replace the current default data frame, you must use⁠%+%⁠,due to S3 method precedence issues.

You can also supply a list, in which case each element of the list willbe added in turn.

See Also

theme()

Examples

base <- ggplot(mpg, aes(displ, hwy)) + geom_point()base + geom_smooth()# To override the data, you must use %+%base %+% subset(mpg, fl == "p")# Alternatively, you can add multiple components with a list.# This can be useful to return from a function.base + list(subset(mpg, fl == "p"), geom_smooth())

Modify properties of an element in a theme object

Description

Modify properties of an element in a theme object

Usage

add_theme(t1, t2, t2name, call = caller_env())

Arguments

Construct aesthetic mappings

Description

Aesthetic mappings describe how variables in the data are mapped to visualproperties (aesthetics) of geoms. Aesthetic mappings can be set inggplot() and in individual layers.

Usage

aes(x, y, ...)

Arguments

Details

This function also standardises aesthetic names by convertingcolor tocolour(also in substrings, e.g.,point_color topoint_colour) and translating old styleR names to ggplot names (e.g.,pch toshape andcex tosize).

Value

An S7 object representing a list with classmapping. Components ofthe list are either quosures or constants.

Quasiquotation

aes() is aquoting function. This means thatits inputs are quoted to be evaluated in the context of thedata. This makes it easy to work with variables from the data framebecause you can name those directly. The flip side is that you haveto usequasiquotation to program withaes(). See a tidy evaluation tutorial such as thedplyr programming vignetteto learn more about these techniques.

Note

UsingI() to create objects of class 'AsIs' causes scales to ignore thevariable and assumes the wrapped variable is direct input for the gridpackage. Please be aware that variables are sometimes combined, like insome stats or position adjustments, that may yield unexpected results with'AsIs' variables.

See Also

vars() for another quoting function designed forfaceting specifications.

Runvignette("ggplot2-specs") to see an overview of other aestheticsthat can be modified.

Delayed evaluation for working with computed variables.

Other aesthetics documentation:aes_colour_fill_alpha,aes_group_order,aes_linetype_size_shape,aes_position

Examples

aes(x = mpg, y = wt)aes(mpg, wt)# You can also map aesthetics to functions of variablesaes(x = mpg ^ 2, y = wt / cyl)# Or to constantsaes(x = 1, colour = "smooth")# Aesthetic names are automatically standardisedaes(col = x)aes(fg = x)aes(color = x)aes(colour = x)# aes() is passed to either ggplot() or specific layer. Aesthetics supplied# to ggplot() are used as defaults for every layer.ggplot(mpg, aes(displ, hwy)) + geom_point()ggplot(mpg) + geom_point(aes(displ, hwy))# Tidy evaluation ----------------------------------------------------# aes() automatically quotes all its arguments, so you need to use tidy# evaluation to create wrappers around ggplot2 pipelines. The# simplest case occurs when your wrapper takes dots:scatter_by <- function(data, ...) {  ggplot(data) + geom_point(aes(...))}scatter_by(mtcars, disp, drat)# If your wrapper has a more specific interface with named arguments,# you need the "embrace operator":scatter_by <- function(data, x, y) {  ggplot(data) + geom_point(aes({{ x }}, {{ y }}))}scatter_by(mtcars, disp, drat)# Note that users of your wrapper can use their own functions in the# quoted expressions and all will resolve as it should!cut3 <- function(x) cut_number(x, 3)scatter_by(mtcars, cut3(disp), drat)

Define aesthetic mappings programmatically

Description

Aesthetic mappings describe how variables in the data are mapped to visualproperties (aesthetics) of geoms.aes() uses non-standardevaluation to capture the variable names.aes_() andaes_string()require you to explicitly quote the inputs either with"" foraes_string(), or withquote or~ foraes_().(aes_q() is an alias toaes_()). This makesaes_() andaes_string() easy to program with.

aes_string() andaes_() are particularly useful when writingfunctions that create plots because you can use strings or quotednames/calls to define the aesthetic mappings, rather than having to usesubstitute() to generate a call toaes().

I recommend usingaes_(), because creating the equivalents ofaes(colour = "my colour") oraes(x = `X$1`)withaes_string() is quite clunky.

Usage

aes_(x, y, ...)aes_string(x, y, ...)aes_q(x, y, ...)

Arguments

Life cycle

All these functions are deprecated. Please use tidy evaluation idiomsinstead. Regardingaes_string(), you can replace it with.data pronoun.For example, the following code can achieve the same mapping asaes_string(x_var, y_var).

x_var <- "foo"y_var <- "bar"aes(.data[[x_var]], .data[[y_var]])

For more details, please seevignette("ggplot2-in-packages").

See Also

aes()

Given a character vector, create a set of identity mappings

Description

Given a character vector, create a set of identity mappings

Usage

aes_all(vars)

Arguments

Examples

aes_all(names(mtcars))aes_all(c("x", "y", "col", "pch"))

Automatic aesthetic mapping

Description

Usage

aes_auto(data = NULL, ...)

Arguments

Colour related aesthetics: colour, fill, and alpha

Description

These aesthetics parameters change the colour (colour andfill) and theopacity (alpha) of geom elements on a plot. Almost every geom has eithercolour or fill (or both), as well as can have their alpha modified.Modifying colour on a plot is a useful way to enhance the presentation of data,often especially when a plot graphs more than two variables.

Colour and fill

Thecolour aesthetic is used to draw lines and strokes, such as ingeom_point() andgeom_line(), but also the line contours ofgeom_rect() andgeom_polygon(). Thefill aesthetic is used tocolour the inside areas of geoms, such asgeom_rect() andgeom_polygon(), but also the insides of shapes 21-25 ofgeom_point().

Colours and fills can be specified in the following ways:

• A name, e.g.,"red". R has 657 built-in named colours, which can belisted withgrDevices::colors().

• An rgb specification, with a string of the form"#RRGGBB" where each of thepairsRR,GG,BB consists of two hexadecimal digits giving a value in therange00 toFF. You can optionally make the colour transparent by using theform"#RRGGBBAA".

• AnNA, for a completely transparent colour.

Alpha

Alpha refers to the opacity of a geom. Values ofalpha range from 0 to 1,with lower values corresponding to more transparent colors.

Alpha can additionally be modified through thecolour orfill aestheticif either aesthetic provides color values using an rgb specification("#RRGGBBAA"), whereAA refers to transparency values.

See Also

• Other options for modifying colour:scale_colour_brewer(),scale_colour_gradient(),scale_colour_grey(),scale_colour_hue(),scale_colour_identity(),scale_colour_manual(),scale_colour_viridis_d()

• Other options for modifying fill:scale_fill_brewer(),scale_fill_gradient(),scale_fill_grey(),scale_fill_hue(),scale_fill_identity(),scale_fill_manual(),scale_fill_viridis_d()

• Other options for modifying alpha:scale_alpha(),scale_alpha_manual(),scale_alpha_identity()

• Runvignette("ggplot2-specs") to see an overview of other aesthetics thatcan be modified.

Other aesthetics documentation:aes(),aes_group_order,aes_linetype_size_shape,aes_position

Examples

# Bar chart examplep <- ggplot(mtcars, aes(factor(cyl)))# Default plottingp + geom_bar()# To change the interior colouring use fill aestheticp + geom_bar(fill = "red")# Compare with the colour aesthetic which changes just the bar outlinep + geom_bar(colour = "red")# Combining both, you can see the changes more clearlyp + geom_bar(fill = "white", colour = "red")# Both colour and fill can take an rgb specification.p + geom_bar(fill = "#00abff")# Use NA for a completely transparent colour.p + geom_bar(fill = NA, colour = "#00abff")# Colouring scales differ depending on whether a discrete or# continuous variable is being mapped. For example, when mapping# fill to a factor variable, a discrete colour scale is used.ggplot(mtcars, aes(factor(cyl), fill = factor(vs))) + geom_bar()# When mapping fill to continuous variable a continuous colour# scale is used.ggplot(faithfuld, aes(waiting, eruptions)) +  geom_raster(aes(fill = density))# Some geoms only use the colour aesthetic but not the fill# aesthetic (e.g. geom_point() or geom_line()).p <- ggplot(economics, aes(x = date, y = unemploy))p + geom_line()p + geom_line(colour = "green")p + geom_point()p + geom_point(colour = "red")# For large datasets with overplotting the alpha# aesthetic will make the points more transparent.set.seed(1)df <- data.frame(x = rnorm(5000), y = rnorm(5000))p  <- ggplot(df, aes(x,y))p + geom_point()p + geom_point(alpha = 0.5)p + geom_point(alpha = 1/10)# Alpha can also be used to add shading.p <- ggplot(economics, aes(x = date, y = unemploy)) + geom_line()pyrng <- range(economics$unemploy)p <- p +  geom_rect(    aes(NULL, NULL, xmin = start, xmax = end, fill = party),    ymin = yrng[1], ymax = yrng[2], data = presidential  )pp + scale_fill_manual(values = alpha(c("blue", "red"), .3))

Control aesthetic evaluation

Description

Mostaesthetics are mapped from variables found in the data.Sometimes, however, you want to delay the mapping until later in therendering process. ggplot2 has three stages of the data that you can mapaesthetics from, and three functions to control at which stage aestheticsshould be evaluated.

after_stat() replaces the old approaches of using eitherstat(), e.g.stat(density), or surrounding the variable names with.., e.g...density...

Usage

# These functions can be used inside the `aes()` function# used as the `mapping` argument in layers, for example:# geom_density(mapping = aes(y = after_stat(scaled)))after_stat(x)after_scale(x)from_theme(x)stage(start = NULL, after_stat = NULL, after_scale = NULL)

Arguments

Staging

Below follows an overview of the three stages of evaluation and how aestheticevaluation can be controlled.

Stage 1: direct input at the start

The default is to map at the beginning, using the layer data provided bythe user. If you want to map directly from the layer data you should not doanything special. This is the only stage where the original layer data canbe accessed.

# 'x' and 'y' are mapped directlyggplot(mtcars) + geom_point(aes(x = mpg, y = disp))

Stage 2: after stat transformation

The second stage is after the data has been transformed by the layerstat. The most common example of mapping from stat transformed data is theheight of bars ingeom_histogram(): the height does not come from avariable in the underlying data, but is instead mapped to thecountcomputed bystat_bin(). In order to map from stat transformed data youshould use theafter_stat() function to flag that evaluation of theaesthetic mapping should be postponed until after stat transformation.Evaluation after stat transformation will have access to the variablescalculated by the stat, not the original mapped values. The 'computedvariables' section in each stat lists which variables are available toaccess.

# The 'y' values for the histogram are computed by the statggplot(faithful, aes(x = waiting)) +  geom_histogram()# Choosing a different computed variable to display, matching up the# histogram with the density plotggplot(faithful, aes(x = waiting)) +  geom_histogram(aes(y = after_stat(density))) +  geom_density()

Stage 3: after scale transformation

The third and last stage is after the data has been transformed andmapped by the plot scales. An example of mapping from scaled data couldbe to use a desaturated version of the stroke colour for fill. You shoulduseafter_scale() to flag evaluation of mapping for after data has beenscaled. Evaluation after scaling will only have access to the finalaesthetics of the layer (including non-mapped, default aesthetics).

# The exact colour is known after scale transformationggplot(mpg, aes(cty, colour = factor(cyl))) +  geom_density()# We re-use colour properties for the fill without a separate fill scaleggplot(mpg, aes(cty, colour = factor(cyl))) +  geom_density(aes(fill = after_scale(alpha(colour, 0.3))))

Complex staging

Sometimes, you may want to map the same aesthetic multiple times, e.g. mapx to a data column at the start for the layer stat, but remap it later toa variable from the stat transformation for the layer geom. Thestage()function allows you to control multiple mappings for the same aestheticacross all three stages of evaluation.

# Use stage to modify the scaled fillggplot(mpg, aes(class, hwy)) +  geom_boxplot(aes(fill = stage(class, after_scale = alpha(fill, 0.4))))# Using data for computing summary, but placing label elsewhere.# Also, we're making our own computed variables to use for the label.ggplot(mpg, aes(class, displ)) +  geom_violin() +  stat_summary(    aes(      y = stage(displ, after_stat = 8),      label = after_stat(paste(mean, "±", sd))    ),    geom = "text",    fun.data = ~ round(data.frame(mean = mean(.x), sd = sd(.x)), 2)  )

Conceptually,aes(x) is equivalent toaes(stage(start = x)), andaes(after_stat(count)) is equivalent toaes(stage(after_stat = count)),and so on.stage() is most useful when at least two of its arguments arespecified.

Theme access

Thefrom_theme() function can be used to acces theelement_geom()fields of thetheme(geom) argument. Usingaes(colour = from_theme(ink))andaes(colour = from_theme(accent)) allows swapping between foreground andaccent colours.

Examples

# Default histogram displayggplot(mpg, aes(displ)) +  geom_histogram(aes(y = after_stat(count)))# Scale tallest bin to 1ggplot(mpg, aes(displ)) +  geom_histogram(aes(y = after_stat(count / max(count))))# Use a transparent version of colour for fillggplot(mpg, aes(class, hwy)) +  geom_boxplot(aes(colour = class, fill = after_scale(alpha(colour, 0.4))))# Use stage to modify the scaled fillggplot(mpg, aes(class, hwy)) +  geom_boxplot(aes(fill = stage(class, after_scale = alpha(fill, 0.4))))# Making a proportional stacked density plotggplot(mpg, aes(cty)) +  geom_density(    aes(      colour = factor(cyl),      fill = after_scale(alpha(colour, 0.3)),      y = after_stat(count / sum(n[!duplicated(group)]))    ),    position = "stack", bw = 1  ) +  geom_density(bw = 1)# Imitating a ridgeline plotggplot(mpg, aes(cty, colour = factor(cyl))) +  geom_ribbon(    stat = "density", outline.type = "upper",    aes(      fill = after_scale(alpha(colour, 0.3)),      ymin = after_stat(group),      ymax = after_stat(group + ndensity)    )  )# Labelling a bar plotggplot(mpg, aes(class)) +  geom_bar() +  geom_text(    aes(      y = after_stat(count + 2),      label = after_stat(count)    ),    stat = "count"  )# Labelling the upper hinge of a boxplot,# inspired by June Choeggplot(mpg, aes(displ, class)) +  geom_boxplot(outlier.shape = NA) +  geom_text(    aes(      label = after_stat(xmax),      x = stage(displ, after_stat = xmax)    ),    stat = "boxplot", hjust = -0.5  )

Aesthetics: grouping

Description

Thegroup aesthetic is by default set to the interaction of all discrete variablesin the plot. This choice often partitions the data correctly, but when it does not,or when no discrete variable is used in the plot, you will need to explicitly define thegrouping structure by mappinggroup to a variable that has a different valuefor each group.

Details

For most applications the grouping is set implicitly by mapping one or morediscrete variables tox,y,colour,fill,alpha,shape,size,and/orlinetype. This is demonstrated in the examples below.

There are three common cases where the default does not display the data correctly.

1. geom_line() where there are multiple individuals and the plot tries toconnect every observation, even across individuals, with a line.

2. geom_line() where a discrete x-position implies groups, whereas observationsspan the discrete x-positions.

3. When the grouping needs to be different over different layers, for examplewhen computing a statistic on all observations when another layer showsindividuals.

The examples below use a longitudinal dataset,Oxboys, from the nlme package to demonstratethese cases.Oxboys records the heights (height) and centered ages (age) of 26 boys (Subject),measured on nine occasions (Occasion).

See Also

• Geoms commonly used with groups:geom_bar(),geom_histogram(),geom_line()

• Runvignette("ggplot2-specs") to see an overview of other aesthetics thatcan be modified.

Other aesthetics documentation:aes(),aes_colour_fill_alpha,aes_linetype_size_shape,aes_position

Examples

p <- ggplot(mtcars, aes(wt, mpg))# A basic scatter plotp + geom_point(size = 4)# Using the colour aestheticp + geom_point(aes(colour = factor(cyl)), size = 4)# Using the shape aestheticp + geom_point(aes(shape = factor(cyl)), size = 4)# Using fillp <- ggplot(mtcars, aes(factor(cyl)))p + geom_bar()p + geom_bar(aes(fill = factor(cyl)))p + geom_bar(aes(fill = factor(vs)))# Using linetypesggplot(economics_long, aes(date, value01)) +  geom_line(aes(linetype = variable))# Multiple groups with one aestheticp <- ggplot(nlme::Oxboys, aes(age, height))# The default is not sufficient here. A single line tries to connect all# the observations.p + geom_line()# To fix this, use the group aesthetic to map a different line for each# subject.p + geom_line(aes(group = Subject))# Different groups on different layersp <- p + geom_line(aes(group = Subject))# Using the group aesthetic with both geom_line() and geom_smooth()# groups the data the same way for both layersp + geom_smooth(aes(group = Subject), method = "lm", se = FALSE)# Changing the group aesthetic for the smoother layer# fits a single line of best fit across all boysp + geom_smooth(aes(group = 1), size = 2, method = "lm", se = FALSE)# Overriding the default grouping# Sometimes the plot has a discrete scale but you want to draw lines# that connect across groups. This is the strategy used in interaction# plots, profile plots, and parallel coordinate plots, among others.# For example, we draw boxplots of height at each measurement occasion.p <- ggplot(nlme::Oxboys, aes(Occasion, height)) + geom_boxplot()p# There is no need to specify the group aesthetic here; the default grouping# works because occasion is a discrete variable. To overlay individual# trajectories, we again need to override the default grouping for that layer# with aes(group = Subject)p + geom_line(aes(group = Subject), colour = "blue")

Differentiation related aesthetics: linetype, size, shape

Description

Thelinetype,linewidth,size, andshape aesthetics modify theappearance of lines and/or points. They also apply to the outlines ofpolygons (linetype andlinewidth) or to text (size).

Linetype

Thelinetype aesthetic can be specified with either an integer (0-6), aname (0 = blank, 1 = solid, 2 = dashed, 3 = dotted, 4 = dotdash, 5 = longdash,6 = twodash), a mapping to a discrete variable, or a string of an even number(up to eight) of hexadecimal digits which give the lengths in consecutivepositions in the string. See examples for a hex string demonstration.

Linewidth and stroke

Thelinewidth aesthetic sets the widths of lines, and can be specifiedwith a numeric value (for historical reasons, these units are about 0.75millimetres). Alternatively, they can also be set via mapping to a continuousvariable. Thestroke aesthetic serves the same role for points, but isdistinct for discriminating points from lines in geoms such asgeom_pointrange().

Size

Thesize aesthetic control the size of points and text, and can bespecified with a numerical value (in millimetres) or via a mapping to acontinuous variable.

Shape

Theshape aesthetic controls the symbols of points, and can be specifiedwith an integer (between 0 and 25), a single character (which uses thatcharacter as the plotting symbol), a. to draw the smallest rectangle thatis visible (i.e., about one pixel), anNA to draw nothing, or a mapping toa discrete variable. Symbols and filled shapes are described in the examplesbelow.

See Also

• geom_line() andgeom_point() for geoms commonly usedwith these aesthetics.

• aes_group_order() for usinglinetype,size, orshape for grouping.

• Scales that can be used to modify these aesthetics:scale_linetype(),scale_linewidth(),scale_size(), andscale_shape().

• Runvignette("ggplot2-specs") to see an overview of other aesthetics thatcan be modified.

Other aesthetics documentation:aes(),aes_colour_fill_alpha,aes_group_order,aes_position

Examples

df <- data.frame(x = 1:10 , y = 1:10)p <- ggplot(df, aes(x, y))p + geom_line(linetype = 2)p + geom_line(linetype = "dotdash")# An example with hex strings; the string "33" specifies three units on followed# by three off and "3313" specifies three units on followed by three off followed# by one on and finally three off.p + geom_line(linetype = "3313")# Mapping line type from a grouping variableggplot(economics_long, aes(date, value01)) +  geom_line(aes(linetype = variable))# Linewidth examplesggplot(economics, aes(date, unemploy)) +  geom_line(linewidth = 2, lineend = "round")ggplot(economics, aes(date, unemploy)) +  geom_line(aes(linewidth = uempmed), lineend = "round")# Size examplesp <- ggplot(mtcars, aes(wt, mpg))p + geom_point(size = 4)p + geom_point(aes(size = qsec))p + geom_point(size = 2.5) +  geom_hline(yintercept = 25, size = 3.5)# Shape examplesp + geom_point()p + geom_point(shape = 5)p + geom_point(shape = "k", size = 3)p + geom_point(shape = ".")p + geom_point(shape = NA)p + geom_point(aes(shape = factor(cyl)))# A look at all 25 symbolsdf2 <- data.frame(x = 1:5 , y = 1:25, z = 1:25)p <- ggplot(df2, aes(x, y))p + geom_point(aes(shape = z), size = 4) +  scale_shape_identity()# While all symbols have a foreground colour, symbols 19-25 also take a# background colour (fill)p + geom_point(aes(shape = z), size = 4, colour = "Red") +  scale_shape_identity()p + geom_point(aes(shape = z), size = 4, colour = "Red", fill = "Black") +  scale_shape_identity()

Position related aesthetics: x, y, xmin, xmax, ymin, ymax, xend, yend

Description

The following aesthetics can be used to specify the position of elements:x,y,xmin,xmax,ymin,ymax,xend,yend.

Details

x andy define the locations of points or of positions along a lineor path.

x,y andxend,yend define the starting and ending points ofsegment and curve geometries.

xmin,xmax,ymin andymax can be used to specify the position ofannotations and to represent rectangular areas.

In addition, there are position aesthetics that are contextual to thegeometry that they're used in. These arexintercept,yintercept,xmin_final,ymin_final,xmax_final,ymax_final,xlower,lower,xmiddle,middle,xupper,upper,x0 andy0. Many of these are usedand automatically computed ingeom_boxplot().

Relation towidth andheight

The position aesthetics mentioned above likex andy are all locationbased. Thewidth andheight aesthetics are closely related lengthbased aesthetics, but are not position aesthetics. Consequently,x andyaesthetics respond to scale transformations, whereas the length basedwidth andheight aesthetics are not transformed by scales. For example,if we have the pair⁠x = 10, width = 2⁠, that gets translated to thelocations⁠xmin = 9, xmax = 11⁠ when using the default identity scales.However, the same pair becomes⁠xmin = 1, xmax = 100⁠ when using log10 scales,aswidth = 2 in log10-space spans a 100-fold change.

See Also

• Geoms that commonly use these aesthetics:geom_crossbar(),geom_curve(),geom_errorbar(),geom_line(),geom_linerange(),geom_path(),geom_point(),geom_pointrange(),geom_rect(),geom_segment()

• Scales that can be used to modify positions:scale_continuous(),scale_discrete(),scale_binned(),scale_date().

• See alsoannotate() for placing annotations.

Other aesthetics documentation:aes(),aes_colour_fill_alpha,aes_group_order,aes_linetype_size_shape

Examples

# Generate data: means and standard errors of means for prices# for each type of cutdmod <- lm(price ~ cut, data = diamonds)cut <- unique(diamonds$cut)cuts_df <- data.frame(  cut,  predict(dmod, data.frame(cut), se = TRUE)[c("fit", "se.fit")])ggplot(cuts_df) +  aes(   x = cut,   y = fit,   ymin = fit - se.fit,   ymax = fit + se.fit,   colour = cut  ) +  geom_pointrange()# Using annotatep <- ggplot(mtcars, aes(x = wt, y = mpg)) + geom_point()pp + annotate(  "rect", xmin = 2, xmax = 3.5, ymin = 2, ymax = 25,  fill = "dark grey", alpha = .5)# Geom_segment examplesp + geom_segment(  aes(x = 2, y = 15, xend = 2, yend = 25),  arrow = arrow(length = unit(0.5, "cm")))p + geom_segment(  aes(x = 2, y = 15, xend = 3, yend = 15),  arrow = arrow(length = unit(0.5, "cm")))p + geom_segment(  aes(x = 5, y = 30, xend = 3.5, yend = 25),  arrow = arrow(length = unit(0.5, "cm")))# You can also use geom_segment() to recreate plot(type = "h")# from base R:set.seed(1)counts <- as.data.frame(table(x = rpois(100, 5)))counts$x <- as.numeric(as.character(counts$x))with(counts, plot(x, Freq, type = "h", lwd = 10))ggplot(counts, aes(x = x, y = Freq)) +  geom_segment(aes(yend = 0, xend = x), size = 10)

Create an annotation layer

Description

This function adds geoms to a plot, but unlike a typical geom function,the properties of the geoms are not mapped from variables of a data frame,but are instead passed in as vectors. This is useful for adding small annotations(such as text labels) or if you have your data in vectors, and for somereason don't want to put them in a data frame.

Usage

annotate(  geom,  x = NULL,  y = NULL,  xmin = NULL,  xmax = NULL,  ymin = NULL,  ymax = NULL,  xend = NULL,  yend = NULL,  ...,  na.rm = FALSE)

Arguments

Details

Note that all position aesthetics are scaled (i.e. they will expand thelimits of the plot so they are visible), but all other aesthetics areset. This means that layers created with this function will neveraffect the legend.

Unsupported geoms

Due to their special nature, reference line geomsgeom_abline(),geom_hline(), andgeom_vline() can't be used withannotate().You can use these geoms directly for annotations.

See Also

Thecustom annotations section of the online ggplot2 book.

Examples

p <- ggplot(mtcars, aes(x = wt, y = mpg)) + geom_point()p + annotate("text", x = 4, y = 25, label = "Some text")p + annotate("text", x = 2:5, y = 25, label = "Some text")p + annotate("rect", xmin = 3, xmax = 4.2, ymin = 12, ymax = 21,  alpha = .2)p + annotate("segment", x = 2.5, xend = 4, y = 15, yend = 25,  colour = "blue")p + annotate("pointrange", x = 3.5, y = 20, ymin = 12, ymax = 28,  colour = "red", size = 2.5, linewidth = 1.5)p + annotate("text", x = 2:3, y = 20:21, label = c("my label", "label 2"))p + annotate("text", x = 4, y = 25, label = "italic(R) ^ 2 == 0.75",  parse = TRUE)p + annotate("text", x = 4, y = 25,  label = "paste(italic(R) ^ 2, \" = .75\")", parse = TRUE)

Create a layer of map borders

Description

This is a quick and dirty way to get map data (from themaps package)onto your plot. This is a good place to start if you need some crudereference lines, but you'll typically want something more sophisticatedfor communication graphics.

Usage

annotation_borders(  database = "world",  regions = ".",  fill = NA,  colour = "grey50",  xlim = NULL,  ylim = NULL,  ...)borders(...) # Deprecated

Arguments

Examples

if (require("maps")) {data(us.cities)capitals <- subset(us.cities, capital == 2)ggplot(capitals, aes(long, lat)) +  annotation_borders("state") +  geom_point(aes(size = pop)) +  scale_size_area() +  coord_quickmap()}if (require("maps")) {# Same map, with some world contextggplot(capitals, aes(long, lat)) +  annotation_borders("world", xlim = c(-130, -60), ylim = c(20, 50)) +  geom_point(aes(size = pop)) +  scale_size_area() +  coord_quickmap()}

Annotation: Custom grob

Description

This is a special geom intended for use as static annotationsthat are the same in every panel. These annotations will notaffect scales (i.e. the x and y axes will not grow to cover the rangeof the grob, and the grob will not be modified by any ggplot settingsor mappings).

Usage

annotation_custom(grob, xmin = -Inf, xmax = Inf, ymin = -Inf, ymax = Inf)

Arguments

Details

Most useful for adding tables, inset plots, and other grid-based decorations.

Note

annotation_custom() expects the grob to fill the entire viewportdefined by xmin, xmax, ymin, ymax. Grobs with a different (absolute) sizewill be center-justified in that region.Inf values can be used to fill the full plot panel (see examples).

Examples

# Dummy plotdf <- data.frame(x = 1:10, y = 1:10)base <- ggplot(df, aes(x, y)) +  geom_blank() +  theme_bw()# Full panel annotationbase + annotation_custom(  grob = grid::roundrectGrob(),  xmin = -Inf, xmax = Inf, ymin = -Inf, ymax = Inf)# Inset plotdf2 <- data.frame(x = 1 , y = 1)g <- ggplotGrob(ggplot(df2, aes(x, y)) +  geom_point() +  theme(plot.background = element_rect(colour = "black")))base +  annotation_custom(grob = g, xmin = 1, xmax = 10, ymin = 8, ymax = 10)

Annotation: log tick marks

Description

This function is superseded by usingguide_axis_logticks().

This annotation adds log tick marks with diminishing spacing.These tick marks probably make sense only for base 10.

Usage

annotation_logticks(  base = 10,  sides = "bl",  outside = FALSE,  scaled = TRUE,  short = unit(0.1, "cm"),  mid = unit(0.2, "cm"),  long = unit(0.3, "cm"),  colour = "black",  linewidth = 0.5,  linetype = 1,  alpha = 1,  color = NULL,  ...,  size = deprecated())

Arguments

See Also

scale_y_continuous(),scale_y_log10() for log scaletransformations.

coord_transform() for log coordinate transformations.

Examples

# Make a log-log plot (without log ticks)a <- ggplot(msleep, aes(bodywt, brainwt)) + geom_point(na.rm = TRUE) + scale_x_log10(   breaks = scales::trans_breaks("log10", \(x) 10^x),   labels = scales::trans_format("log10", scales::math_format(10^.x)) ) + scale_y_log10(   breaks = scales::trans_breaks("log10", \(x) 10^x),   labels = scales::trans_format("log10", scales::math_format(10^.x)) ) + theme_bw()a + annotation_logticks()                # Default: log ticks on bottom and lefta + annotation_logticks(sides = "lr")    # Log ticks for y, on left and righta + annotation_logticks(sides = "trbl")  # All four sidesa + annotation_logticks(sides = "lr", outside = TRUE) + coord_cartesian(clip = "off")  # Ticks outside plot# Hide the minor grid lines because they don't align with the ticksa + annotation_logticks(sides = "trbl") + theme(panel.grid.minor = element_blank())# Another way to get the same results as 'a' above: log-transform the data before# plotting it. Also hide the minor grid lines.b <- ggplot(msleep, aes(log10(bodywt), log10(brainwt))) + geom_point(na.rm = TRUE) + scale_x_continuous(name = "body", labels = scales::label_math(10^.x)) + scale_y_continuous(name = "brain", labels = scales::label_math(10^.x)) + theme_bw() + theme(panel.grid.minor = element_blank())b + annotation_logticks()# Using a coordinate transform requires scaled = FALSEt <- ggplot(msleep, aes(bodywt, brainwt)) +  geom_point() +  coord_transform(x = "log10", y = "log10") +  theme_bw()t + annotation_logticks(scaled = FALSE)# Change the length of the ticksa + annotation_logticks(  short = unit(.5,"mm"),  mid = unit(3,"mm"),  long = unit(4,"mm"))

Annotation: a map

Description

Display a fixed map on a plot. This function predates thegeom_sf()framework and does not work with sf geometry columns as input. However,it can be used in conjunction withgeom_sf() layers and/orcoord_sf() (see examples).

Usage

annotation_map(map, ...)

Arguments

Examples

## Not run: if (requireNamespace("maps", quietly = TRUE)) {# location of cities in North Carolinadf <- data.frame(  name = c("Charlotte", "Raleigh", "Greensboro"),  lat = c(35.227, 35.772, 36.073),  long = c(-80.843, -78.639, -79.792))p <- ggplot(df, aes(x = long, y = lat)) +  annotation_map(    map_data("state"),    fill = "antiquewhite", colour = "darkgrey"  ) +  geom_point(color = "blue") +  geom_text(    aes(label = name),    hjust = 1.105, vjust = 1.05, color = "blue"  )# use without coord_sf() is possible but not recommendedp + xlim(-84, -76) + ylim(34, 37.2)if (requireNamespace("sf", quietly = TRUE)) {# use with coord_sf() for appropriate projectionp +  coord_sf(    crs = sf::st_crs(3347),    default_crs = sf::st_crs(4326),  # data is provided as long-lat    xlim = c(-84, -76),    ylim = c(34, 37.2)  )# you can mix annotation_map() and geom_sf()nc <- sf::st_read(system.file("shape/nc.shp", package = "sf"), quiet = TRUE)p +  geom_sf(    data = nc, inherit.aes = FALSE,    fill = NA, color = "black", linewidth = 0.1  ) +  coord_sf(crs = sf::st_crs(3347), default_crs = sf::st_crs(4326))}}## End(Not run)

Annotation: high-performance rectangular tiling

Description

This is a special version ofgeom_raster() optimised for staticannotations that are the same in every panel. These annotations will notaffect scales (i.e. the x and y axes will not grow to cover the rangeof the raster, and the raster must already have its own colours). Thisis useful for adding bitmap images.

Usage

annotation_raster(raster, xmin, xmax, ymin, ymax, interpolate = FALSE)

Arguments

Examples

# Generate datarainbow <- matrix(hcl(seq(0, 360, length.out = 50 * 50), 80, 70), nrow = 50)ggplot(mtcars, aes(mpg, wt)) +  geom_point() +  annotation_raster(rainbow, 15, 20, 3, 4)# To fill up whole plotggplot(mtcars, aes(mpg, wt)) +  annotation_raster(rainbow, -Inf, Inf, -Inf, Inf) +  geom_point()rainbow2 <- matrix(hcl(seq(0, 360, length.out = 10), 80, 70), nrow = 1)ggplot(mtcars, aes(mpg, wt)) +  annotation_raster(rainbow2, -Inf, Inf, -Inf, Inf) +  geom_point()rainbow2 <- matrix(hcl(seq(0, 360, length.out = 10), 80, 70), nrow = 1)ggplot(mtcars, aes(mpg, wt)) +  annotation_raster(rainbow2, -Inf, Inf, -Inf, Inf, interpolate = TRUE) +  geom_point()

Convert a ggproto object to a list

Description

This will not include the object'ssuper member.

Usage

## S3 method for class 'ggproto'as.list(x, inherit = TRUE, ...)

Arguments

Coerce to labeller function

Description

This transforms objects to labeller functions. Used internally bylabeller().

Usage

as_labeller(x, default = label_value, multi_line = TRUE)

Arguments

See Also

labeller(),labellers

Examples

p <- ggplot(mtcars, aes(disp, drat)) + geom_point()p + facet_wrap(~am)# Rename labels on the fly with a lookup character vectorto_string <- as_labeller(c(`0` = "Zero", `1` = "One"))p + facet_wrap(~am, labeller = to_string)# Quickly transform a function operating on character vectors to a# labeller function:appender <- function(string, suffix = "-foo") paste0(string, suffix)p + facet_wrap(~am, labeller = as_labeller(appender))# If you have more than one faceting variable, be sure to dispatch# your labeller to the right variable with labeller()p + facet_grid(cyl ~ am, labeller = labeller(am = to_string))

Create a ggplot layer appropriate to a particular data type

Description

autolayer() uses ggplot2 to draw a particular layer for an object of aparticular class in a single command. This defines the S3 generic thatother classes and packages can extend.

Usage

autolayer(object, ...)

Arguments

Value

a ggplot layer

See Also

Other plotting automation topics:automatic_plotting,autoplot(),fortify()

Tailoring plots to particular data types

Description

There are three functions to make plotting particular data types easier:autoplot(),autolayer() andfortify(). These are S3 generics for whichother packages can write methods to display classes of data. The threefunctions are complementary and allow different levels of customisation.Below we'll explore implementing this series of methods to automate plottingof some class.

Let's suppose we are writing a packages that has a class called 'my_heatmap',that wraps a matrix and we'd like users to easily plot this heatmap.

my_heatmap <- function(...) {  m <- matrix(...)  class(m) <- c("my_heatmap", class(m))  m}my_data <- my_heatmap(volcano)

Automatic data shaping

One of the things we have to do is ensure that the data is shaped in the longformat so that it is compatible with ggplot2. This is the job of thefortify() function. Because 'my_heatmap' wraps a matrix, we can let thefortify method 'melt' the matrix to a long format. If your data is alreadybased on a long-format⁠<data.frame>⁠, you can skip implementing afortify() method.

fortify.my_heatmap <- function(model, ...) {  data.frame(    row = as.vector(row(model)),    col = as.vector(col(model)),    value = as.vector(model)  )}fortify(my_data)

When you have implemented thefortify() method, it should be easier toconstruct a plot with the data than with the matrix.

ggplot(my_data, aes(x = col, y = row, fill = value)) +  geom_raster()

Automatic layers

A next step in automating plotting of your data type is to write anautolayer() method. These are typically wrappers around geoms or statsthat automatically set aesthetics or other parameters. If you haven'timplemented afortify() method for your data type, you might have toreshape the data inautolayer().

If you require multiple layers to display your data type, you can use anautolayer() method that constructs a list of layers, which can be addedto a plot.

autolayer.my_heatmap <- function(object, ...) {  geom_raster(    mapping = aes(x = col, y = row, fill = value),    data = object,    ...,    inherit.aes = FALSE  )}ggplot() + autolayer(my_data)

As a quick tip: if you define a mapping inautolayer(), you might wantto setinherit.aes = FALSE to not have aesthetics set in other layersinterfere with your layer.

Automatic plots

The last step in automating plotting is to write anautoplot() methodfor your data type. The expectation is that these return a complete plot.In the example below, we're exploiting theautolayer() method that wehave already written to make a complete plot.

autoplot.my_heatmap <- function(object, ..., option = "magma") {  ggplot() +    autolayer(my_data) +    scale_fill_viridis_c(option = option) +    theme_void()}autoplot(my_data)

If you don't have a wish to implement a base R plotting method, youcan set the plot method for your class to the autoplot method.

plot.my_heatmap <- autoplot.my_heatmapplot(my_data)

See Also

Other plotting automation topics:autolayer(),autoplot(),fortify()

Create a complete ggplot appropriate to a particular data type

Description

autoplot() uses ggplot2 to draw a particular plot for an object of aparticular class in a single command. This defines the S3 generic thatother classes and packages can extend.

Usage

autoplot(object, ...)

Arguments

Value

a ggplot object

See Also

Other plotting automation topics:autolayer(),automatic_plotting,fortify()

Benchmark plot creation time.Broken down into construct, build, render and draw times.

Description

Benchmark plot creation time.Broken down into construct, build, render and draw times.

Usage

benchplot(x)

Arguments

Examples

benchplot(ggplot(mtcars, aes(mpg, wt)) + geom_point())benchplot(ggplot(mtcars, aes(mpg, wt)) + geom_point() + facet_grid(. ~ cyl))# With tidy eval:p <- expr(ggplot(mtcars, aes(mpg, wt)) + geom_point())benchplot(!!p)

Utilities for working with bidirectional layers

Description

These functions are what underpins the ability of certain geoms to workautomatically in both directions. See theExtending ggplot2 vignette forhow they are used when implementingGeom,Stat, andPosition classes.

Usage

has_flipped_aes(  data,  params = list(),  main_is_orthogonal = NA,  range_is_orthogonal = NA,  group_has_equal = FALSE,  ambiguous = FALSE,  main_is_continuous = FALSE,  main_is_optional = FALSE,  default = FALSE)flip_data(data, flip = NULL)flipped_names(flip = FALSE)

Arguments

Details

has_flipped_aes() is used to sniff out the orientation of the layer fromthe data. It has a range of arguments that can be used to finetune thesniffing based on what the data should look like.flip_data() will switchthe column names of the data so that it looks like x-oriented data.flipped_names() provides a named list of aesthetic names that correspondsto the orientation of the layer.

Value

has_flipped_aes() returnsTRUE if it detects a layer in the otherorientation andFALSE otherwise.flip_data() will return the inputunchanged ifflip = FALSE and the data with flipped aesthetic names ifflip = TRUE.flipped_names() returns a named list of strings. Ifflip = FALSE the name of the element will correspond to the element, e.g.flipped_names(FALSE)$x == "x" and ifflip = TRUE it will correspond tothe flipped name, e.g.flipped_names(FALSE)$x == "y"

Controlling the sniffing

How the layer data should be interpreted depends on its specific features.has_flipped_aes() contains a range of flags for defining what certainfeatures in the data correspond to:

• main_is_orthogonal: This argument controls how the existence of only axory aesthetic is understood. IfTRUE then the existing aestheticwould be then secondary axis. This behaviour is present instat_ydensity()andstat_boxplot(). IfFALSE then the existing aesthetic is the mainaxis as seen in e.g.stat_bin(),geom_count(), andstat_density().

• range_is_orthogonal: This argument controls whether the existence ofrange-like aesthetics (e.g.xmin andxmax) represents the main orsecondary axis. IfTRUE then the range is given for the secondary axis asseen in e.g.geom_ribbon() andgeom_linerange().

• group_has_equal: This argument controls whether to test for equality ofallx andy values inside each group and set the main axis to the onewhere all is equal. This test is only performed ifTRUE, and only afterless computationally heavy tests has come up empty handed. Examples arestat_boxplot() andstat_ydensity

• ambiguous: This argument tells the function that the layer, whilebidirectional, doesn't treat each axis differently. It will circumvent anydata based guessing and only take hint from theorientation element inparams. If this is not present it will fall back toFALSE. Examples aregeom_line() andgeom_area()

• main_is_continuous: This argument controls how the test for discretenessin the scales should be interpreted. IfTRUE then the main axis will bethe one which is not discrete-like. Conversely, ifFALSE the main axiswill be the discrete-like one. Examples ofTRUE isstat_density() andstat_bin(), while examples ofFALSE isstat_ydensity() andstat_boxplot()

• main_is_optional: This argument controls the rare case of layers were themain direction is an optional aesthetic. This is only seen instat_boxplot() wherex is set to0 if not given. IfTRUE there willbe a check for whether allx or ally are equal to0

Binning scale constructor

Description

Binning scale constructor

Usage

binned_scale(  aesthetics,  scale_name = deprecated(),  palette,  name = waiver(),  breaks = waiver(),  labels = waiver(),  limits = NULL,  rescaler = rescale,  oob = squish,  expand = waiver(),  na.value = NA_real_,  n.breaks = NULL,  nice.breaks = TRUE,  right = TRUE,  transform = "identity",  trans = deprecated(),  show.limits = FALSE,  guide = "bins",  position = "left",  fallback.palette = NULL,  call = caller_call(),  super = ScaleBinned)

Arguments

See Also

Thenew scales section of the online ggplot2 book.

Calculate the element properties, by inheriting properties from its parents

Description

Calculate the element properties, by inheriting properties from its parents

Usage

calc_element(  element,  theme,  verbose = FALSE,  skip_blank = FALSE,  call = caller_env())

Arguments

Examples

t <- theme_grey()calc_element('text', t)# Compare the "raw" element definition to the element with calculated inheritancet$axis.text.xcalc_element('axis.text.x', t, verbose = TRUE)# This reports that axis.text.x inherits from axis.text,# which inherits from text. You can view each of them with:t$axis.text.xt$axis.textt$text

Check graphics device capabilities

Description

This function makes an attempt to estimate whether the graphics device isable to render newer graphics features.

Usage

check_device(  feature,  action = "warn",  op = NULL,  maybe = FALSE,  call = caller_env())

Arguments

Details

The procedure for testing is as follows:

• First, theR version is checked against the version wherein a feature wasintroduced.

• Next, thedev.capabilities() function isqueried for support of the feature.

• If that check is ambiguous, thesvglite andragg devices arechecked for known support.

• Lastly, if there is no answer yet, it is checked whether the device is oneof the 'known' devices that supports a feature.

Value

TRUE when the feature is thought to be supported andFALSEotherwise.

Features

"clippingPaths"

While most devices support rectangular clippingregions, this feature is about the support for clipping to arbitrary paths.It can be used to only display a part of a drawing.

"alpha_masks"

Like clipping regions and paths, alpha masks can alsobe used to only display a part of a drawing. In particular asemi-transparent mask can be used to display a drawing in the opaque partsof the mask and hide a drawing in transparent part of a mask.

⁠"lumi_masks⁠

Similar to alpha masks, but using the mask's luminance(greyscale value) to determine what is drawn. Light values are opaque anddark values are transparent.

"compositing"

Compositing allows one to control how to drawingsare drawn in relation to one another. By default, one drawing is drawn'over' the previous one, but other operators are possible, like 'clear','in' and 'out'.

"blending"

When placing one drawing atop of another, the blendmode determines how the colours of the drawings relate to one another.

"transformations"

Performing an affine transformation on a groupcan be used to translate, rotate, scale, shear and flip the drawing.

"gradients"

Gradients can be used to show a transition betweentwo or more colours as a fill in a drawing. The checks expects both linearand radial gradients to be supported.

"patterns"

Patterns can be used to display a repeated, tileddrawing as a fill in another drawing.

"paths"

Contrary to 'paths' as polyline or polygon drawings,"paths" refers to the ability to fill and stroke collections ofdrawings.

"glyphs"

Refers to the advanced typesetting feature forcontrolling the appearance of individual glyphs.

Limitations

• On Windows machines, bitmap devices such aspng() orjpeg() defaulttotype = "windows". At the time of writing, these don't support anynew features, in contrast totype = "cairo", which does. Prior toRversion 4.2.0, the capabilities cannot be resolved and the value of themaybe argument is returned.

• With the exception of theragg andsvglite devices, if thedevice doesn't report their capabilities viadev.capabilities(), or theR version isbelow 4.2.0, themaybe value is returned.

• Even though patterns and gradients where introduced inR 4.1.0, theyare considered unsupported because providing vectorised patterns andgradients was only introduced later inR 4.2.0.

• When using the RStudio graphics device, the back end is assumed to be thenext device on the list. This assumption is typically met by default,unless the device list is purposefully rearranged.

Examples

# Typically you'd run `check_device()` inside a function that might produce# advanced graphics.# The check is designed for use in control flow statements in the test modeif (check_device("patterns", action = "test")) {  print("Yay")} else {  print("Nay")}# Automatically throw a warning when unavailableif (check_device("compositing", action = "warn")) {  print("Yay")} else {  print("Nay")}# Possibly throw an errortry(check_device("glyphs", action = "abort"))

Class definitions

Description

The S7 object oriented programming system requires class definitions.Here, we provide definitions of classes that are home to ggplot2.

S7 classes

A general advice the S7 package gives is to name class definition objectsthe same as the class name, which then becomes the constructor for the class.The classes listed below deviate from that advice for historical reasons,because some constructors likeggplot() are also S3 generics with methods.The have theclass_-prefix to indicate their role.

• class_ggplot is an S7 class used for objects generated byggplot().

• class_ggplot_built is an S7 class used for objects generated byggplot_build().

• class_mapping is an S7 class used for objects generated byaes().

• class_theme is an S7 class used for objects generated bytheme().

• class_labels is an S7 class used for objects generated bylabs().

• class_gg is an abstract S7 class to used invoke similar behaviour amongggplot objects.

Theme elements

The theme elements follow the advice of the S7 package that the class namesare also the class definitions and constructors.

• element is an abstract S7 class used to invoke similar behaviour amongtheme element objects.

• element_blank is an S7 class for not drawing theme elements.

• element_rect is an S7 class for drawing rectangles.

• element_line is an S7 class for drawing lines.

• element_text is an S7 class for rendering text.

• element_polygon is an S7 class for drawing polygons.

• element_point is an S7 class for drawing points.

• element_geom is an S7 class holding geom defaults.

• margin is an S7 class for declaring margins.

ggproto classes

The ggproto classes are S3 classes of the type environment that form thebackbone of most systems in ggplot2 and are in particular crucial to theextension system.

• class_ggproto is an S3 class used for the objects generated byggproto() which are of the type environment.

• class_scale is a subclass ofclass_ggproto and is more described intheScale documentation.

• class_guides is a subclass ofclass_ggproto and is considered aninternal class.

• class_guide is a subclass ofclass_ggproto and is more described in theGuide documentation.

• class_coord is a subclass ofclass_ggproto and is more described in theCoord documentation.

• class_facet is a subclass ofclass_ggproto and is more described in theFacet documentation.

• class_layer is a subclass ofclass_ggproto and is used for the objectsgenerated bylayer(). The class itself is considered internal and isdescribed in more detail in theLayer documentation.

• class_layout is a subclass ofclass_ggproto and is considered aninternal class. It is described in more detail in theLayoutdocumentation.

• class_scales_list is a subclass ofclass_ggproto and is considered aninternal class.

S3 classes

Some simple classes remain S3, primarily because they aren't meant to berecycled into new classes.

• class_S3_gg is a temporary S3 classuntil R 4.3.0 is the minimum supported version. It is exported andlisted here for completeness, but its use is heavily discouraged. Itis superseded byclass_gg.

• class_rel is an S3 class used inelement properties.

• class_zero_grob is an S3 class used to indicate empty drawings.

• class_waiver is an S3 sentinel value class used in various places.

• class_derive is an S3 sentinel value class used primarily insec_axis().

The ggplot class

Description

The ggplot class collects the needed information to render a plot.This class can be constructed using theggplot() function.

Usage

class_ggplot(  data = waiver(),  ...,  layers = list(),  scales = NULL,  guides = NULL,  mapping = aes(),  theme = NULL,  coordinates = coord_cartesian(default = TRUE),  facet = facet_null(),  layout = NULL,  labels = labs(),  meta = list(),  plot_env = parent.frame())

Arguments

The ggplot built class

Description

The ggplot built class is an intermediate class and represents a processedggplot object ready for rendering. It is constructed by callingggplot_build() on aggplot object and is not meant to beinstantiated directly. The class can be rendered to a gtable object bycalling theggplot_gtable() function on a ggplot built class object.

Usage

class_ggplot_built(..., data = NULL, layout = NULL, plot = NULL)

Arguments

The labels class

Description

The labels class holds a list with label information to display as titlesof plot components. The preferred way to construct an object of the labelsclass is to use thelabs() function.

Usage

class_labels(labels = list(), ...)

Arguments

Details

All members oflabels are expected to be named and names should be unique.

The mapping class

Description

The mapping class holds a list of quoted expressions(quosures) or constants. An object is typicallyconstructed using theaes() function.

Usage

class_mapping(x = list(), ..., env = globalenv())

Arguments

The theme class

Description

The theme class holds information on how non-data elements of the plotshould be rendered. The preferred way to construct an object of this classis through thetheme() function.

Usage

class_theme(elements = list(), ..., complete = FALSE, validate = TRUE)

Arguments

Take input data and define a mapping between faceting variables and ROW,COL and PANEL keys

Description

Take input data and define a mapping between faceting variables and ROW,COL and PANEL keys

Usage

combine_vars(data, env = emptyenv(), vars = NULL, drop = TRUE)

Arguments

Value

A data.frame with columns for PANEL, ROW, COL, and faceting vars

Complete a theme

Description

This function takes a theme and completes it so that it can be useddownstream to render theme elements. Missing elements are filled in andevery item is validated to the specifications of the element tree.

Usage

complete_theme(theme = NULL, default = theme_get())

Arguments

Value

Atheme object.

Examples

my_theme <- theme(line = element_line(colour = "red"))complete_theme(my_theme)

Continuous scale constructor

Description

Continuous scale constructor

Usage

continuous_scale(  aesthetics,  scale_name = deprecated(),  palette,  name = waiver(),  breaks = waiver(),  minor_breaks = waiver(),  n.breaks = NULL,  labels = waiver(),  limits = NULL,  rescaler = rescale,  oob = censor,  expand = waiver(),  na.value = NA,  transform = "identity",  trans = deprecated(),  guide = "legend",  position = "left",  fallback.palette = NULL,  call = caller_call(),  super = ScaleContinuous)

Arguments

See Also

Thenew scales section of the online ggplot2 book.

Cartesian coordinates

Description

The Cartesian coordinate system is the most familiar, and common, type ofcoordinate system. Setting limits on the coordinate system will zoom theplot (like you're looking at it with a magnifying glass), and will notchange the underlying data like setting limits on a scale will.

Usage

coord_cartesian(  xlim = NULL,  ylim = NULL,  expand = TRUE,  default = FALSE,  clip = "on",  reverse = "none",  ratio = NULL)

Arguments

Examples

# There are two ways of zooming the plot display: with scales or# with coordinate systems.  They work in two rather different ways.p <- ggplot(mtcars, aes(disp, wt)) +  geom_point() +  geom_smooth()p# Setting the limits on a scale converts all values outside the range to NA.p + scale_x_continuous(limits = c(325, 500))# Setting the limits on the coordinate system performs a visual zoom.# The data is unchanged, and we just view a small portion of the original# plot. Note how smooth continues past the points visible on this plot.p + coord_cartesian(xlim = c(325, 500))# By default, the same expansion factor is applied as when setting scale# limits. You can set the limits precisely by setting expand = FALSEp + coord_cartesian(xlim = c(325, 500), expand = FALSE)# Similarly, we can use expand = FALSE to turn off expansion with the# default limitsp + coord_cartesian(expand = FALSE)# Using a fixed ratio: 1 y-axis unit is 100 x-axis units# Plot window can be resized and aspect ratio will be maintainedp + coord_cartesian(ratio = 100)# You can see the same thing with this 2d histogramd <- ggplot(diamonds, aes(carat, price)) +  stat_bin_2d(bins = 25, colour = "white")d# When zooming the scale, the we get 25 new bins that are the same# size on the plot, but represent smaller regions of the data spaced + scale_x_continuous(limits = c(0, 1))# When zooming the coordinate system, we see a subset of original 50 bins,# displayed biggerd + coord_cartesian(xlim = c(0, 1))

Cartesian coordinates with fixed "aspect ratio"

Description

A fixed scale coordinate system forces a specified ratio between thephysical representation of data units on the axes. The ratio represents thenumber of units on the y-axis equivalent to one unit on the x-axis. Thedefault,ratio = 1, ensures that one unit on the x-axis is the samelength as one unit on the y-axis. Ratios higher than one make units on they axis longer than units on the x-axis, and vice versa. This is similar toMASS::eqscplot(), but it works for all types of graphics.

Usage

coord_fixed(ratio = 1, ...)

Arguments

Examples

# ensures that the ranges of axes are equal to the specified ratio by# adjusting the plot aspect ratiop <- ggplot(mtcars, aes(mpg, wt)) + geom_point()p + coord_fixed(ratio = 1)p + coord_fixed(ratio = 5)p + coord_fixed(ratio = 1/5)p + coord_fixed(xlim = c(15, 30))# Resize the plot to see that the specified aspect ratio is maintained

Cartesian coordinates with x and y flipped

Description

This function is superseded because in many cases,coord_flip() can easilybe replaced by swapping the x and y aesthetics, or optionally setting theorientation argument in geom and stat layers.

coord_flip() is useful for geoms and statistics that do not supporttheorientation setting, and converting the display of y conditional on x,to x conditional on y.

Usage

coord_flip(xlim = NULL, ylim = NULL, expand = TRUE, clip = "on")

Arguments

Details

Coordinate systems interact with many parts of the plotting system. You canexpect the following forcoord_flip():

• It doesnot change the facet order infacet_grid() orfacet_wrap().

• The⁠scale_x_*()⁠ functions apply to the vertical direction,whereas⁠scale_y_*()⁠ functions apply to the horizontal direction. Thesame holds for thexlim andylim arguments ofcoord_flip() and thexlim() andylim() functions.

• The x-axis theme settings, such asaxis.line.x apply to the horizontaldirection. The y-axis theme settings, such asaxis.text.y apply to thevertical direction.

Examples

# The preferred method of creating horizontal instead of vertical boxplotsggplot(diamonds, aes(price, cut)) +  geom_boxplot()# Using `coord_flip()` to make the same plotggplot(diamonds, aes(cut, price)) +  geom_boxplot() +  coord_flip()# With swapped aesthetics, the y-scale controls the left axisggplot(diamonds, aes(y = carat)) +  geom_histogram() +  scale_y_reverse()# In `coord_flip()`, the x-scale controls the left axisggplot(diamonds, aes(carat)) +  geom_histogram() +  coord_flip() +  scale_x_reverse()# In line and area plots, swapped aesthetics require an explicit orientationdf <- data.frame(a = 1:5, b = (1:5) ^ 2)ggplot(df, aes(b, a)) +  geom_area(orientation = "y")# The same plot with `coord_flip()`ggplot(df, aes(a, b)) +  geom_area() +  coord_flip()

Map projections

Description

coord_map() projects a portion of the earth, which is approximatelyspherical, onto a flat 2D plane using any projection defined by themapproj package. Map projections do not, in general, preserve straightlines, so this requires considerable computation.coord_quickmap() is aquick approximation that does preserve straight lines. It works best forsmaller areas closer to the equator.

Bothcoord_map() andcoord_quickmap()are superseded bycoord_sf(), and should no longer be used in newcode. All regular (non-sf) geoms can be used withcoord_sf() bysetting the default coordinate system via thedefault_crs argument.See also the examples forannotation_map() andgeom_map().

Usage

coord_map(  projection = "mercator",  ...,  parameters = NULL,  orientation = NULL,  xlim = NULL,  ylim = NULL,  clip = "on")coord_quickmap(xlim = NULL, ylim = NULL, expand = TRUE, clip = "on")

Arguments