ggplot2::geom_text() and ggplot2::geom_label()
   get_help() docs


Description

The geom_text() and geom_label() functions are part of the {ggplot2} package, which is part of the {tidyverse}.

These functions are used within {ggplot2} plots to create text in plots. The geom_text() function simply writes text, but the geom_label() function includes a rectangle behind the text.

Required aesthetics:

  • x: The x-axis coordinate(s) for the text(s)
  • y: The y-axis coordinate(s) for the text(s)

Commonly used optional aesthetics:

  • color (colour): The text color
  • size: The text size
  • fill: A rectangle fill when using geom_label() (not geom_text())

To use these functions, you need to either first load the {ggplot2} library, or always use the function with ggplot2::geom_text() (or ggplot2::geom_label()) notation.

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

# Or, use :: notation for example with geom_text()
ggplot2::geom_text()

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


# Plot of awake against sleep_rem ("y against x"), but using `geom_text()` instead of `geom_point()`.
# Using the label argument, all "text points" are the letter "w". This is "just a label"
ggplot(msleep) + 
  aes(x = sleep_rem, y = awake) + 
  geom_text(label = "w")


# Plot of awake against sleep_rem ("y against x"), but using `geom_label()` instead of `geom_point()`.
# Using the label argument, all "text points" are the letter "w". This is "just a label"
ggplot(msleep) + 
  aes(x = sleep_rem, y = awake) + 
  geom_label(label = "w")


# Plot of awake against sleep_rem ("y against x"), but using `geom_label()` instead of `geom_point()`.
# Include "just a fill" for the geom_label rectangles:
ggplot(msleep) + 
  aes(x = sleep_rem, y = awake) + 
  geom_label(label = "w", fill = "yellow")


# Plot of awake against sleep_rem ("y against x"), but using `geom_text()` instead of `geom_point()`.
# Now we also make all labels blue, and all labels now read 'hello'
ggplot(msleep) + 
  aes(x = sleep_rem, y = awake) + 
  geom_text(label = "hello", color = "blue")


# Plot of awake against sleep_rem ("y against x"), but using `geom_text()` instead of `geom_point()`.
# Now we map the vore column to label
ggplot(msleep) + 
  aes(x = sleep_rem, y = awake, label = vore) + 
  geom_text(color = "blue")


# Plot of awake against sleep_rem ("y against x"), but using `geom_text()` instead of `geom_point()`.
# Now we map the vore column to label AND to color
ggplot(msleep) + 
  aes(x = sleep_rem, 
      y = awake, 
      label = vore, 
      color = vore) + 
  geom_text()


# Plot of awake against sleep_rem ("y against x"), but using `geom_label()` instead of `geom_point()`.
# Now we map FILL and label to vore as an example of using this function (not a good plot though since excessive overlap!)
ggplot(msleep) + 
  aes(x = sleep_rem, 
      y = awake, 
      label = vore, 
      fill = vore) + 
  geom_label()


# A wrangled-using-dplyr barplot showing the mean awake value for each vore, where bars are labeled with mean awake values.
# Subsequent examples all modify this plot.
# To explore this example, see it in action one line at a time!
# The next example presents a "cleaned" version of this plot
msleep %>%
  # Calculate mean hours awake for each vore
  group_by(vore) %>%
  summarize(mean_hours_awake = mean(awake)) %>%
  ggplot() + 
  aes(x = vore, 
      y = mean_hours_awake,
      # Set the label aesthetic for geom_text
      label = mean_hours_awake) + 
  geom_col() + 
  geom_text()


# The previous examples labels were at the exact bar height - it would look nicer if they were a little bit higher up on the Y-axis higher
# We can achieve this by specifying aesthetics separately for each geom: 
msleep %>%
  # Calculate mean hours awake for each vore
  group_by(vore) %>%
  summarize(mean_hours_awake = mean(awake)) %>%
  ggplot() + 
  geom_col(aes(x = vore, 
               # column height shoud be the mean hours spent awake
               y = mean_hours_awake)) + 
  geom_text(aes(x = vore, 
                # label height should be 0.5 units or so higher than the bar! You can add any value you want here, in units of the Y-axis
                # trial and error to find how much higher!
                y = mean_hours_awake + 0.5,
                label = mean_hours_awake))


# This example further modifies the plot by rounding mean values in the label so they are more legible
msleep %>%
  # Calculate mean hours awake for each vore
  group_by(vore) %>%
  summarize(mean_hours_awake = mean(awake)) %>%
  ggplot() + 
  geom_col(aes(x = vore, 
               y = mean_hours_awake)) + 
  geom_text(aes(x = vore, 
                y = mean_hours_awake + 0.5,
                # Round the LABEL (not the bar height!) to two decimal places. See get_help("round")
                label = round(mean_hours_awake, 2)))

# This example even further modifies the bar plot by arranging bars in order of mean hours spent awake with fct_reorder
msleep %>%
  # Calculate mean hours awake for each vore
  group_by(vore) %>%
  summarize(mean_hours_awake = mean(awake)) %>%
  ggplot() + 
  geom_col(aes(x = fct_reorder(vore, mean_hours_awake), # reorder vore
               y = mean_hours_awake)) + 
  geom_text(aes(x = fct_reorder(vore, mean_hours_awake), # reorder vore
                y = mean_hours_awake + 0.5,
                label = round(mean_hours_awake, 2)))

# This final example even further modifies the bar plot by arranging bars in order of mean hours spent awake with fct_reorder
# But this time, the vore variable is reordered before plotting and NAs are removed:
msleep %>%
  # Calculate mean hours awake for each vore
  group_by(vore) %>%
  summarize(mean_hours_awake = mean(awake)) %>%
  # reorder the vore factor here
  mutate(vore = fct_reorder(vore, mean_hours_awake)) %>%
  # drop any NAs with tidyr::drop_na()
  tidyr::drop_na() %>%
  ggplot() + 
  geom_col(aes(x = vore, #
               y = mean_hours_awake)) + 
  geom_text(aes(x = vore,
                y = mean_hours_awake + 0.5,
                label = round(mean_hours_awake, 2)))