ggplot2::aes()
   get_help() docs


Description

The aes() function is part of the {ggplot2} package, which is part of the {tidyverse}.

We use the aes() function within {ggplot2} plots to establish aesthetic mappings between visual features in the plot and columns in the tibble (data frame) being plotted. The aes() function should be used only to map columns to aesthetics. Other stylings can be directly provided to geoms, without enclosing them in aes().

To use this function, you need to either first load the {ggplot2} library, or always use the function with ggplot2::aes() notation.

# Load the library
library(ggplot2)
# Or, load the full tidyverse:
library(tidyverse)

# Or, use :: notation
ggplot2::aes()

Conceptual Usage

# Provide aes() to initial ggplot call so that all geoms inherit
ggplot(tibble to plot, 
       mapping = aes(aspect of plot = column name in tibble, etc.))

# It is optional whether you use the 'mapping' argument keyword with `ggplot()`
# This is equivalent to above:
ggplot(tibble to plot, 
       aes(aspect of plot = column name in tibble, etc.))

# Provide aes on its own so that all geoms inherit
ggplot(tibble to plot) +
  aes(aspect of plot = column name in tibble, etc.)

# Provide aes to a geom directly
ggplot(tibble to plot) +
  geom_whatever(aes(aspect of plot = column name in tibble, etc.))

Examples

The examples below use the msleep dataset. Learn more about this dataset with get_help("msleep").

# Show the msleep dataset with head()
head(msleep)
## # A tibble: 6 × 11
##   name  genus vore  order conservation sleep_total sleep_rem sleep_cycle awake  brainwt  bodywt
##   <chr> <chr> <chr> <chr> <chr>              <dbl>     <dbl>       <dbl> <dbl>    <dbl>   <dbl>
## 1 Owl … Aotus omni  Prim… <NA>                17         1.8      NA       7    0.0155    0.48 
## 2 Moun… Aplo… herbi Rode… nt                  14.4       2.4      NA       9.6 NA         1.35 
## 3 Grea… Blar… omni  Sori… lc                  14.9       2.3       0.133   9.1  0.00029   0.019
## 4 Cow   Bos   herbi Arti… domesticated         4         0.7       0.667  20    0.423   600    
## 5 Thre… Brad… herbi Pilo… <NA>                14.4       2.2       0.767   9.6 NA         3.85 
## 6 Nort… Call… carni Carn… vu                   8.7       1.4       0.383  15.3 NA        20.5


# Make a boxplot with `vore` on the x-axis and `awake` on the y-axis
# This example provides aes() inside ggplot()
# Note, to remove NAs, you must manipulate the data first
ggplot(msleep, 
       aes(x = vore, y = awake)) + 
  geom_boxplot()


# Make a boxplot with `vore` on the x-axis and `awake` on the y-axis, with aes() on its own
# This examples provides aes() separately, outside of ggplot()
# Note, to remove NAs, you must manipulate the data first
ggplot(msleep) + 
  aes(x = vore, y = awake) + 
  geom_boxplot()


# Make a boxplot with `vore` on the x-axis and `awake` on the y-axis, with aes() on its own
# Also _fill_ the boxplots based on the values in the `vore` column
# Note, to remove NAs, you must manipulate the data first
ggplot(msleep) + 
  aes(x = vore, y = awake, fill = vore) + 
  geom_boxplot()


## CAUTION! This example code results in an error because `vore` is a column but it was not placed into `aes()`
# Note, to remove NAs, you must manipulate the data first
ggplot(msleep) + 
  aes(x = vore, y = awake) + 
  geom_boxplot(fill = vore)
## Error in layer(data = data, mapping = mapping, stat = stat, geom = GeomBoxplot, : object 'vore' not found


## CAUTION! This example code results in _an inappropriate legend_ and _wrong colors_ because a non-column is provided to `aes()`
# Note, to remove NAs, you must manipulate the data first
ggplot(msleep) + 
  aes(x = vore, y = awake) + 
  geom_boxplot(aes(fill = "blue")) # "blue" is not a column. It's just a fill specification without mapping, and the fill isn't even blue!


# When using multiple geoms, all will inherit mappings from an initial aes() call
# Note, to remove NAs, you must manipulate the data first
ggplot(msleep) + 
  aes(x = vore, 
      y = awake, 
      fill = vore,
      color = vore) +
  geom_jitter()  +  # also inherits x, y, color, and fill mappings
  geom_boxplot()    # inherits x, y, color, and fill mappings


# When using multiple geoms, you can decide which geoms get which aesthetic:
# Note, to remove NAs, you must manipulate the data first
ggplot(msleep) + 
  aes(x = vore, y = awake) +       # All geoms inherit the x/y mapping
  geom_jitter(aes(color = vore), pch = 21) + # ONLY the jitter geom gets the color mapping. Using pch=21, we see points are NOT filled, only colored
  geom_boxplot(aes(fill = vore), alpha = 0.5)   # ONLY the boxplot gets the fill mapping. Its color remains default black. Add alpha for transparency

# Another example with multiple geoms: All geoms inherit the aes() mappings. 
# Each vore has its own `geom_smooth()` trendline _because of the color mapping_
# Note, to remove NAs, you must manipulate the data first
ggplot(msleep) + 
  aes(x = sleep_rem, y = awake, color = vore) +       
  geom_point() +  
  geom_smooth(method = "lm", se=FALSE) # Linear trendline without confidence interval, for clarity
## `geom_smooth()` using formula 'y ~ x'


# Another example with multiple geoms: Choose which geoms use which aesthetic
# Note, to remove NAs, you must manipulate the data first
ggplot(msleep) + 
  aes(x = sleep_rem, y = awake) +       
  geom_point(aes(color = vore)) +  
  geom_smooth(method = "lm", se=FALSE) # Does NOT separate trendlines by color: Single trendline for all vores
## `geom_smooth()` using formula 'y ~ x'


# Another example with multiple geoms: Choose which geoms use which aesthetic
# Note, to remove NAs, you must manipulate the data first
ggplot(msleep) + 
  aes(x = sleep_rem, y = awake) +       
  geom_point() +   # Does NOT show points by color
  geom_smooth(aes(color = vore), # Separate trendline for all vores
              method = "lm", 
              se = FALSE) 
## `geom_smooth()` using formula 'y ~ x'