CINXE.COM

<!DOCTYPE html> <html lang="en"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><meta charset="utf-8"><meta http-equiv="X-UA-Compatible" content="IE=edge"><meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no"><meta name="description" content="Aesthetic mappings describe how variables in the data are mapped to visual properties (aesthetics) of geoms. Aesthetic mappings can be set in ggplot() and in individual layers."><title>Construct aesthetic mappings — aes • ggplot2</title><link rel="icon" type="image/png" sizes="16x16" href="../favicon-16x16.png"><link rel="icon" type="image/png" sizes="32x32" href="../favicon-32x32.png"><link rel="apple-touch-icon" type="image/png" sizes="180x180" href="../apple-touch-icon.png"><link rel="apple-touch-icon" type="image/png" sizes="120x120" href="../apple-touch-icon-120x120.png"><link rel="apple-touch-icon" type="image/png" sizes="76x76" href="../apple-touch-icon-76x76.png"><link rel="apple-touch-icon" type="image/png" sizes="60x60" href="../apple-touch-icon-60x60.png"><script src="../deps/jquery-3.6.0/jquery-3.6.0.min.js"></script><meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no"><link href="../deps/bootstrap-5.3.1/bootstrap.min.css" rel="stylesheet"><script src="../deps/bootstrap-5.3.1/bootstrap.bundle.min.js"></script><link href="../deps/Source_Sans_Pro-0.4.9/font.css" rel="stylesheet"><link href="../deps/Source_Code_Pro-0.4.9/font.css" rel="stylesheet"><link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.12.1/css/all.min.css" integrity="sha256-mmgLkCYLUQbXn0B1SRqzHar6dCnv9oZFPEC1g1cwlkk=" crossorigin="anonymous"><link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/5.12.1/css/v4-shims.min.css" integrity="sha256-wZjR52fzng1pJHwx4aV2AO3yyTOXrcDW7jBpJtTwVxw=" crossorigin="anonymous"><script src="https://cdn.jsdelivr.net/gh/afeld/bootstrap-toc@v1.0.1/dist/bootstrap-toc.min.js" integrity="sha256-4veVQbu7//Lk5TSmc7YV48MxtMy98e26cf5MrgZYnwo=" crossorigin="anonymous"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/headroom/0.11.0/headroom.min.js" integrity="sha256-AsUX4SJE1+yuDu5+mAVzJbuYNPHj/WroHuZ8Ir/CkE0=" crossorigin="anonymous"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/headroom/0.11.0/jQuery.headroom.min.js" integrity="sha256-ZX/yNShbjqsohH1k95liqY9Gd8uOiE1S4vZc+9KQ1K4=" crossorigin="anonymous"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/2.0.11/clipboard.min.js" integrity="sha512-7O5pXpc0oCRrxk8RUfDYFgn0nO1t+jLuIOQdOMRp4APB7uZ4vSjspzp5y6YDtDs4VzUSTbWzBFZ/LKJhnyFOKw==" crossorigin="anonymous" referrerpolicy="no-referrer"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/fuse.js/6.4.6/fuse.js" integrity="sha512-zv6Ywkjyktsohkbp9bb45V6tEMoWhzFzXis+LrMehmJZZSys19Yxf1dopHx7WzIKxr5tK2dVcYmaCk2uqdjF4A==" crossorigin="anonymous"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/autocomplete.js/0.38.0/autocomplete.jquery.min.js" integrity="sha512-GU9ayf+66Xx2TmpxqJpliWbT5PiGYxpaG8rfnBEk1LL8l1KGkRShhngwdXK1UgqhAzWpZHSiYPc09/NwDQIGyg==" crossorigin="anonymous"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/mark.js/8.11.1/mark.min.js" integrity="sha512-5CYOlHXGh6QpOFA/TeTylKLWfB3ftPsde7AnmhuitiTX4K5SqCLBeKro6sPS8ilsz1Q4NRx3v8Ko2IBiszzdww==" crossorigin="anonymous"></script><script src="../pkgdown.js"></script><meta property="og:title" content="Construct aesthetic mappings — aes"><meta property="og:description" content="Aesthetic mappings describe how variables in the data are mapped to visual properties (aesthetics) of geoms. Aesthetic mappings can be set in ggplot() and in individual layers."><meta property="og:image" content="https://ggplot2.tidyverse.org/logo.png"><script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js" integrity="sha256-nvJJv9wWKEm88qvoQl9ekL2J+k/RWIsaSScxxlsrv8k=" crossorigin="anonymous"></script><script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/config/TeX-AMS-MML_HTMLorMML.js" integrity="sha256-84DKXVJXs0/F8OTMzX4UR909+jtl4G7SPypPavF+GfA=" crossorigin="anonymous"></script><script defer data-domain="ggplot2.tidyverse.org,all.tidyverse.org" src="https://plausible.io/js/plausible.js"></script></head><body> <a href="#container" class="visually-hidden-focusable">Skip to content</a> <nav class="navbar fixed-top navbar-light navbar-expand-lg bg-none" data-bs-theme="light"><div class="container"> <a class="navbar-brand me-2" href="../index.html">ggplot2</a> 3.5.1 <button class="navbar-toggler" type="button" data-bs-toggle="collapse" data-bs-target="#navbar" aria-controls="navbar" aria-expanded="false" aria-label="Toggle navigation"> </button> <div id="navbar" class="collapse navbar-collapse ms-3"> <ul class="navbar-nav me-auto"><li class="nav-item"> <a class="nav-link" href="../articles/ggplot2.html">Get started</a> </li> <li class="active nav-item"> <a class="nav-link" href="../reference/index.html">Reference</a> </li> <li class="nav-item dropdown"> <a href="#" class="nav-link dropdown-toggle" data-bs-toggle="dropdown" role="button" aria-expanded="false" aria-haspopup="true" id="dropdown-news">News</a> <div class="dropdown-menu" aria-labelledby="dropdown-news"> <h6 class="dropdown-header" data-toc-skip>Releases</h6> <a class="external-link dropdown-item" href="https://www.tidyverse.org/blog/2024/02/ggplot2-3-5-0/">Version 3.5.0</a> <a class="external-link dropdown-item" href="https://www.tidyverse.org/blog/2022/11/ggplot2-3-4-0/">Version 3.4.0</a> <a class="external-link dropdown-item" href="https://www.tidyverse.org/blog/2020/03/ggplot2-3-3-0/">Version 3.3.0</a> <a class="external-link dropdown-item" href="https://www.tidyverse.org/articles/2019/06/ggplot2-3-2-0/">Version 3.2.0</a> <a class="external-link dropdown-item" href="https://www.tidyverse.org/articles/2018/10/ggplot2-3-1-0/">Version 3.1.0</a> <a class="external-link dropdown-item" href="https://www.tidyverse.org/articles/2018/07/ggplot2-3-0-0/">Version 3.0.0</a> <a class="external-link dropdown-item" href="https://posit.co/blog/ggplot2-2-2-0/">Version 2.2.0</a> <a class="external-link dropdown-item" href="https://posit.co/blog/ggplot2-2-1-0/">Version 2.1.0</a> <a class="external-link dropdown-item" href="https://posit.co/blog/ggplot2-2-0-0/">Version 2.0.0</a> <a class="external-link dropdown-item" href="https://posit.co/blog/ggplot2-updates/">Version 1.0.0</a> <div class="dropdown-divider"></div> <a class="dropdown-item" href="../news/index.html">Changelog</a> </div> </li> <li class="nav-item dropdown"> <a href="#" class="nav-link dropdown-toggle" data-bs-toggle="dropdown" role="button" aria-expanded="false" aria-haspopup="true" id="dropdown-articles">Articles</a> <div class="dropdown-menu" aria-labelledby="dropdown-articles"> <a class="dropdown-item" href="../articles/ggplot2-specs.html">Aesthetic specifications</a> <div class="dropdown-divider"></div> <h6 class="dropdown-header" data-toc-skip>Developer</h6> <a class="dropdown-item" href="../articles/extending-ggplot2.html">Extending ggplot2</a> <a class="dropdown-item" href="../articles/ggplot2-in-packages.html">Using ggplot2 in packages</a> <a class="dropdown-item" href="../articles/profiling.html">Profiling Performance</a> <div class="dropdown-divider"></div> <h6 class="dropdown-header" data-toc-skip>FAQ</h6> <a class="dropdown-item" href="../articles/faq-axes.html">FAQ: Axes</a> <a class="dropdown-item" href="../articles/faq-faceting.html">FAQ: Faceting</a> <a class="dropdown-item" href="../articles/faq-customising.html">FAQ: Customising</a> <a class="dropdown-item" href="../articles/faq-annotation.html">FAQ: Annotation</a> <a class="dropdown-item" href="../articles/faq-reordering.html">FAQ: Reordering</a> <a class="dropdown-item" href="../articles/faq-bars.html">FAQ: Barplots</a> </div> </li> <li class="nav-item"> <a class="external-link nav-link" href="https://exts.ggplot2.tidyverse.org/gallery/">Extensions</a> </li> </ul><form class="form-inline my-2 my-lg-0" role="search"> <input type="search" class="form-control me-sm-2" aria-label="Toggle navigation" name="search-input" data-search-index="../search.json" id="search-input" placeholder="Search for" autocomplete="off"></form> <ul class="navbar-nav"><li class="nav-item"> <a class="external-link nav-link" href="https://github.com/tidyverse/ggplot2/" aria-label="github"> </a> </li> </ul></div> </div> </nav><div class="container template-reference-topic" id="container"> <div class="row"> <main id="main" class="col-md-9"><div class="page-header"> <img src="../logo.png" class="logo" alt=""><h1>Construct aesthetic mappings</h1> Source: <a href="https://github.com/tidyverse/ggplot2/blob/HEAD/R/aes.R" class="external-link"><code>R/aes.R</code></a> <div class="d-none name"><code>aes.Rd</code></div> </div> <div class="ref-description section level2"> Aesthetic mappings describe how variables in the data are mapped to visual properties (aesthetics) of geoms. Aesthetic mappings can be set in <code><a href="ggplot.html">ggplot()</a></code> and in individual layers. </div> <div class="section level2"> <h2 id="ref-usage">Usage<a class="anchor" aria-label="anchor" href="#ref-usage"></a></h2> <div class="sourceCode"><pre class="sourceCode r"><code>aes(x, y, ...)</code></pre></div> </div> <div class="section level2"> <h2 id="arguments">Arguments<a class="anchor" aria-label="anchor" href="#arguments"></a></h2> <dl><dt>x, y, ...</dt> <dd><<code><a href="https://rlang.r-lib.org/reference/topic-data-mask.html" class="external-link">data-masking</a></code>> List of name-value pairs in the form <code>aesthetic = variable</code> describing which variables in the layer data should be mapped to which aesthetics used by the paired geom/stat. The expression <code>variable</code> is evaluated within the layer data, so there is no need to refer to the original dataset (i.e., use <code>ggplot(df, aes(variable))</code> instead of <code>ggplot(df, aes(df$variable))</code>). The names for x and y aesthetics are typically omitted because they are so common; all other aesthetics must be named.</dd> </dl></div> <div class="section level2"> <h2 id="value">Value<a class="anchor" aria-label="anchor" href="#value"></a></h2> A list with class <code>uneval</code>. Components of the list are either quosures or constants. </div> <div class="section level2"> <h2 id="details">Details<a class="anchor" aria-label="anchor" href="#details"></a></h2> This function also standardises aesthetic names by converting <code>color</code> to <code>colour</code> (also in substrings, e.g., <code>point_color</code> to <code>point_colour</code>) and translating old style R names to ggplot names (e.g., <code>pch</code> to <code>shape</code> and <code>cex</code> to <code>size</code>). </div> <div class="section level2"> <h2 id="quasiquotation">Quasiquotation<a class="anchor" aria-label="anchor" href="#quasiquotation"></a></h2> <code>aes()</code> is a <a href="https://rlang.r-lib.org/reference/topic-defuse.html" class="external-link">quoting function</a>. This means that its inputs are quoted to be evaluated in the context of the data. This makes it easy to work with variables from the data frame because you can name those directly. The flip side is that you have to use <a href="https://rlang.r-lib.org/reference/topic-inject.html" class="external-link">quasiquotation</a> to program with <code>aes()</code>. See a tidy evaluation tutorial such as the <a href="https://dplyr.tidyverse.org/articles/programming.html" class="external-link">dplyr programming vignette</a> to learn more about these techniques. </div> <div class="section level2"> <h2 id="see-also">See also<a class="anchor" aria-label="anchor" href="#see-also"></a></h2> <div class="dont-index"><code><a href="vars.html">vars()</a></code> for another quoting function designed for faceting specifications. Run <code><a href="../articles/ggplot2-specs.html">vignette("ggplot2-specs")</a></code> to see an overview of other aesthetics that can be modified. <a href="aes_eval.html">Delayed evaluation</a> for working with computed variables. Other aesthetics documentation: <code><a href="aes_colour_fill_alpha.html">aes_colour_fill_alpha</a></code>, <code><a href="aes_group_order.html">aes_group_order</a></code>, <code><a href="aes_linetype_size_shape.html">aes_linetype_size_shape</a></code>, <code><a href="aes_position.html">aes_position</a></code></div> </div> <div class="section level2"> <h2 id="ref-examples">Examples<a class="anchor" aria-label="anchor" href="#ref-examples"></a></h2> <div class="sourceCode"><pre class="sourceCode r"><code>aes(x = mpg, y = wt) #> Aesthetic mapping: #> * `x` -> `mpg` #> * `y` -> `wt` aes(mpg, wt) #> Aesthetic mapping: #> * `x` -> `mpg` #> * `y` -> `wt` # You can also map aesthetics to functions of variables aes(x = mpg ^ 2, y = wt / cyl) #> Aesthetic mapping: #> * `x` -> `mpg^2` #> * `y` -> `wt/cyl` # Or to constants aes(x = 1, colour = "smooth") #> Aesthetic mapping: #> * `x` -> 1 #> * `colour` -> "smooth" # Aesthetic names are automatically standardised aes(col = x) #> Aesthetic mapping: #> * `colour` -> `x` aes(fg = x) #> Aesthetic mapping: #> * `colour` -> `x` aes(color = x) #> Aesthetic mapping: #> * `colour` -> `x` aes(colour = x) #> Aesthetic mapping: #> * `colour` -> `x` # aes() is passed to either ggplot() or specific layer. Aesthetics supplied # to ggplot() are used as defaults for every layer. <a href="ggplot.html">ggplot</a>(mpg, aes(displ, hwy)) + <a href="geom_point.html">geom_point</a>() <img src="aes-1.png" alt="" width="700" height="433"> <a href="ggplot.html">ggplot</a>(mpg) + <a href="geom_point.html">geom_point</a>(aes(displ, hwy)) <img src="aes-2.png" alt="" width="700" height="433"> # 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, ...) { <a href="ggplot.html">ggplot</a>(data) + <a href="geom_point.html">geom_point</a>(aes(...)) } scatter_by(mtcars, disp, drat) <img src="aes-3.png" alt="" width="700" height="433"> # If your wrapper has a more specific interface with named arguments, # you need the "embrace operator": scatter_by <- function(data, x, y) { <a href="ggplot.html">ggplot</a>(data) + <a href="geom_point.html">geom_point</a>(aes({{ x }}, {{ y }})) } scatter_by(mtcars, disp, drat) <img src="aes-4.png" alt="" width="700" height="433"> # 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) <a href="cut_interval.html">cut_number</a>(x, 3) scatter_by(mtcars, cut3(disp), drat) <img src="aes-5.png" alt="" width="700" height="433"> </code></pre></div> </div> </main><aside class="col-md-3"><nav id="toc"><h2>On this page</h2> </nav></aside></div> </div> <footer><div class="container"> <div class="pkgdown-footer-left"> Developed by <a href="https://hadley.nz" class="external-link">Hadley Wickham</a>, <a href="https://github.com/wch" class="external-link">Winston Chang</a>, <a href="https://github.com/lionel-" class="external-link">Lionel Henry</a>, <a href="https://data-imaginist.com" class="external-link">Thomas Lin Pedersen</a>, Kohske Takahashi, <a href="https://clauswilke.com" class="external-link">Claus Wilke</a>, <a href="https://karawoo.com" class="external-link">Kara Woo</a>, <a href="https://yutani.rbind.io" class="external-link">Hiroaki Yutani</a>, <a href="https://fishandwhistle.net" class="external-link">Dewey Dunnington</a>, Teun van den Brand, <a href="https://www.posit.co" class="external-link"><img src="https://www.tidyverse.org/posit-logo.svg" alt="Posit" height="16" width="62" style="margin-bottom: 3px;"></a>. </div> <div class="pkgdown-footer-right"> Site built with <a href="https://pkgdown.r-lib.org/" class="external-link">pkgdown</a> 2.0.9. </div> </div></footer></body></html>