Introduction to ‘ggtibble’

library(ggtibble)

Motivation for ggtibble

From time to time, having a list of ggplots and being able to work on them like a regular ggplot can be very helpful. For example, when writing a report, you may want to make a set of figures to separate out various levels of a group, then make separate figures for each group.

Introduction

The ggtibble package has two main functions to create sets of figures, ggtibble() and gglist(). These create a tibble with optional labels per figure and captions (for ggtibble()) or a simpler list of figures (for gglist()).

Both ggtibble and gglist objects can have ggplot geoms, facets, labels, and lists of those added to them as though they were normal ggplot objects. And, you can add a gglist to either a ggtibble or a gglist.

Typical use

Typical use will load required libraries, setup your plot data, generate the plot, and then knit_print() it.

When generating the plot:

  1. Give your dataset,
  2. Indicate your columns for plotting using the aes() mapping as for any ggplot2 object,
  3. Provide the outercols which are columns outside your dataset; one plot will be generated for each unique level of your data with the outercols. Note that you cannot use outercols columns within the plot, but you will use them for captions and labels.
  4. You can give a caption with a glue::glue_data() specification where valid columns are any column names that are in your outercols specification. (If you don’t give a caption, then it will be an empty string, "".)
  5. You can give a list of labels which are each processed the same as the caption via glue::glue_data() and then passed to labs().
  6. After the plot is setup in ways that are specific to ggtibble, use it like a normal ggplot object adding geoms, etc.
# Note, add `fig.cap=all_plots$caption` to show the generated caption for the
# figures

library(ggtibble)
library(dplyr)
#> 
#> Attaching package: 'dplyr'
#> The following objects are masked from 'package:stats':
#> 
#>     filter, lag
#> The following objects are masked from 'package:base':
#> 
#>     intersect, setdiff, setequal, union
library(ggplot2)
#> Warning: package 'ggplot2' was built under R version 4.5.3
#> 
#> Attaching package: 'ggplot2'
#> The following objects are masked from 'package:ggtibble':
#> 
#>     %+%, ggsave

d_plot <-
  mtcars |>
  mutate(
    dispu = "cu. in."
  )
all_plots <-
  ggtibble(
    d_plot,
    aes(x = disp, y = hp),
    outercols = c("cyl", "dispu"),
    caption = "Horsepower by displacement for {cyl} cars",
    labs = list(x = "Displacement ({dispu})", y = "Gross horsepower")
  ) +
  geom_point() +
  geom_line()

# The result is a tibble with columns for the `data_plot`, `figure`, and
# `caption`
as_tibble(all_plots)
#> # A tibble: 3 × 5
#>     cyl dispu   data_plot                   figure caption                      
#>   <dbl> <chr>   <list>                    <gglist> <glue>                       
#> 1     6 cu. in. <tibble [7 × 10]>  A ggplot object Horsepower by displacement f…
#> 2     4 cu. in. <tibble [11 × 10]> A ggplot object Horsepower by displacement f…
#> 3     8 cu. in. <tibble [14 × 10]> A ggplot object Horsepower by displacement f…

# You can then show all the figures with the `knit_print()` method.
knit_print(all_plots)
Horsepower by displacement for 6 cars
Horsepower by displacement for 6 cars
Horsepower by displacement for 4 cars
Horsepower by displacement for 4 cars
Horsepower by displacement for 8 cars
Horsepower by displacement for 8 cars

Shorter syntax via the ggtibble chunk option

The ggtibble package registers a knitr opts_hooks callback that lets you render a ggtibble with a single chunk option. The chunk below is equivalent to the one above: the chunk label, fig.cap, and knit_print() call are all derived from the ggtibble option value.


``` r
knitr::knit_print(getFromNamespace(".ggtibble_chunk_cache", "ggtibble")[["all_plots"]])
```



![Horsepower by displacement for 6 cars](C:/Users/bill/AppData/Local/Temp/Rtmp8cQwid/Rbuild4dd045927d6/ggtibble/vignettes/v01-introduction_files/figure-html/all_plots-1.png)





![Horsepower by displacement for 4 cars](C:/Users/bill/AppData/Local/Temp/Rtmp8cQwid/Rbuild4dd045927d6/ggtibble/vignettes/v01-introduction_files/figure-html/all_plots-2.png)





![Horsepower by displacement for 8 cars](C:/Users/bill/AppData/Local/Temp/Rtmp8cQwid/Rbuild4dd045927d6/ggtibble/vignettes/v01-introduction_files/figure-html/all_plots-3.png)

The option value is R code given as a character string and is evaluated in the knit environment, so ggtibble = "targets::tar_read(all_plots)" also works. This same syntax works in Quarto, where the auto-generated chunk label is prefixed with fig- so that @fig-all_plots cross-references resolve.