Add Plot Element — add

Quickly and conveniently add a new 'geom' to an existing plot2/ggplot model. Like plot2(), these functions support tidy evaluation, meaning that variables can be unquoted. Better yet, they can contain any function with any output length, or any vector. They can be added using the pipe (new base R's |> or tidyverse's %>%).

Usage

add_type(plot, type = NULL, mapping = aes(), ..., data = NULL, move = 0)

add_line(
  plot,
  y = NULL,
  x = NULL,
  colour = getOption("plot2.colour", "ggplot2"),
  linetype,
  linewidth,
  ...,
  inherit.aes = NULL,
  move = 0,
  legend.value = NULL
)

add_point(
  plot,
  y = NULL,
  x = NULL,
  colour = getOption("plot2.colour", "ggplot2"),
  size,
  shape,
  ...,
  inherit.aes = NULL,
  move = 0,
  legend.value = NULL
)

add_col(
  plot,
  y = NULL,
  x = NULL,
  colour = getOption("plot2.colour", "ggplot2"),
  colour_fill,
  width,
  ...,
  inherit.aes = NULL,
  move = 0,
  legend.value = NULL
)

add_errorbar(
  plot,
  min,
  max,
  colour = getOption("plot2.colour", "ggplot2"),
  width = 0.5,
  ...,
  inherit.aes = NULL,
  move = 0
)

add_sf(
  plot,
  sf_data,
  colour = getOption("plot2.colour_sf", "grey50"),
  colour_fill = getOption("plot2.colour_sf_fill", getOption("plot2.colour", "ggplot2")),
  size = 2,
  linewidth = 0.1,
  datalabels = NULL,
  datalabels.colour = "black",
  datalabels.size = 3,
  datalabels.angle = 0,
  datalabels.font = getOption("plot2.font"),
  datalabels.nudge_y = 2500,
  ...,
  inherit.aes = FALSE
)

Arguments

plot: a ggplot2 plot
type: a ggplot2 geom name, all geoms are supported. Full function names can be used (e.g., "geom_line"), but they can also be abbreviated (e.g., "l", "line"). These geoms can be abbreviated by their first character: area ("a"), boxplot ("b"), column ("c"), histogram ("h"), jitter ("j"), line ("l"), point ("p"), ribbon ("r"), violin ("v").
mapping: a mapping created with aes() to pass on to the geom
data: data to use in mapping
move: number of layers to move the newly added geom down, e.g., move = 1 will place the newly added geom down 1 layer, thus directly under the highest layer
x, y: aesthetic arguments
colour, colour_fill: colour of the line or column, will be evaluated with get_colour(). If colour_fill is missing but colour is given, colour_fill will inherit the colour set with colour.
linetype, linewidth, shape, size, width, ...: arguments passed on to the geom
inherit.aes: a logical to indicate whether the default aesthetics should be inherited, rather than combining with them
legend.value: text to show in an additional legend that will be created. Since ggplot2 does not actually support this, it may give some false-positive warnings or messages, such as "Removed 1 row containing missing values or values outside the scale range".
min, max: minimum (lower) and maximum (upper) values of the error bars
sf_data: an 'sf' data.frame
datalabels: a column of sf_data to add as label below the points
datalabels.colour, datalabels.size, datalabels.angle, datalabels.font: properties of datalabels
datalabels.nudge_y: is datalabels is not NULL, the amount of vertical adjustment of the datalabels (positive value: more to the North, negative value: more to the South)

Value

a ggplot object

Details

The function add_line() will add:

geom_hline() if only y is provided;
geom_vline() if only x is provided;
geom_line() in all other cases.

The function add_errorbar() only adds error bars to the y values, see Examples.

Examples

head(iris)
#>   Sepal.Length Sepal.Width Petal.Length Petal.Width Species
#> 1          5.1         3.5          1.4         0.2  setosa
#> 2          4.9         3.0          1.4         0.2  setosa
#> 3          4.7         3.2          1.3         0.2  setosa
#> 4          4.6         3.1          1.5         0.2  setosa
#> 5          5.0         3.6          1.4         0.2  setosa
#> 6          5.4         3.9          1.7         0.4  setosa
                 
p <- iris |>
  plot2(x = Sepal.Length,
        y = Sepal.Width,
        category = Species,
        zoom = TRUE)
#> ℹ Using type = "point" since both axes are numeric
p

  
# if not specifying x or y, current plot data are taken
p |> add_line()

  
# single values for add_line() will plot 'hline' or 'vline'
# even considering the `category` if set
p |> 
  add_line(y = mean(Sepal.Width))


# set `colour` to ignore existing colours
# and use `legend.value` to add a legend
p |> 
  add_line(y = mean(Sepal.Width),
           colour = "red",
           legend.value = "Average")

  
p |> 
  add_line(x = mean(Sepal.Length)) |> 
  add_line(y = mean(Sepal.Width))

  
p |>
  add_point(x = median(Sepal.Length),
            y = median(Sepal.Width),
            shape = 13,
            size = 25,
            show.legend = FALSE)

  
# multiple values will just plot multiple lines
p |> 
  add_line(y = fivenum(Sepal.Width),
           colour = "blue",
           legend.value = "Tukey's Numbers")

  
p |> 
  add_line(y = quantile(Sepal.Width, c(0.25, 0.5, 0.75)),
           colour = c("red", "black", "red"),
           linewidth = 1)

  
# use move to move the new layer down
p |> 
  add_point(size = 5,
            colour = "lightpink",
            move = -1)


# providing x and y will just plot the points as new data,
p |> 
  add_point(y = 2:4,
            x = 5:7,
            colour = "red",
            size = 5)

# even with expanded grid if x and y are not of the same length
p |> 
  add_point(y = 2:4,
            x = 5:8,
            colour = "red",
            size = 5)


# any mathematical transformation of current values is supported
df <- data.frame(var_1 = c(1:100),
                 var_2 = rnorm(100, 100, 25),
                 var_3 = rep(LETTERS[1:5], 5))
df |>
  plot2(var_1, var_2) |> 
  add_line(y = mean(var_2), 
           linetype = 3,
           legend.value = "Average") |>
  add_col(y = var_2 / 5,
          width = 0.25,
          colour = "blue",
          legend.value = "This *is* **some** symbol: $beta$")
#> ℹ Using type = "point" since both axes are numeric
#> Warning: Removed 1 row containing missing values or values outside the scale range
#> (`geom_col()`).


# plotting error bars was never easier
library("dplyr", warn.conflicts = FALSE)
df2 <- df |> 
  as_tibble() |> 
  slice(1:25) |>
  filter(var_1 <= 50) |> 
  mutate(error1 = var_2 * 0.9,
         error2 = var_2 * 1.1)

df2
#> # A tibble: 25 × 5
#>    var_1 var_2 var_3 error1 error2
#>    <int> <dbl> <chr>  <dbl>  <dbl>
#>  1     1 106.  A       95.7  117. 
#>  2     2  39.1 B       35.2   43.0
#>  3     3  99.9 C       89.9  110. 
#>  4     4 116.  D      104.   127. 
#>  5     5 129.  E      116.   142. 
#>  6     6  54.5 A       49.0   59.9
#>  7     7  93.8 B       84.4  103. 
#>  8     8  93.9 C       84.5  103. 
#>  9     9  92.9 D       83.6  102. 
#> 10    10  86.2 E       77.5   94.8
#> # ℹ 15 more rows

df2 |> 
  plot2(var_1, var_2, var_3, type = "col", datalabels = FALSE, alpha = 0.25, width = 0.75) |> 
  # adding error bars was never easier - just reference the lower and upper values
  add_errorbar(error1, error2)
#> ℹ This additional argument was given to the geom: alpha
#> ℹ Using x.character = TRUE for discrete plot type (geom_col) since var_1 is
#> numeric


# adding sf objects is just as convenient as all else
plot2(netherlands)
#> ℹ Assuming datalabels.centroid = TRUE. Set to FALSE for a point-on-surface
#> placing of datalabels.
#> ℹ Using category = area_km2
#> ℹ Using datalabels = province

plot2(netherlands) |>
  add_sf(netherlands, colour_fill = NA, colour = "red", linewidth = 1)
#> ℹ Assuming datalabels.centroid = TRUE. Set to FALSE for a point-on-surface
#> placing of datalabels.
#> ℹ Using category = area_km2
#> ℹ Using datalabels = province