Aim and structure of the tutorial

The aim of this tutorial is not to reiterate the contents of the package’s documentation from the web in its entirety or introduce ggplot2 (Hehman & Xie, 2021; Wickham, 2016; Wickham, Çetinkaya-Rundel, & Grolemund, 2023). Instead, it aims to present a new workflow for the visualization of a composite plot in ggplot2 with a programmatic approach and the smplot2 package. In the first section, I will briefly introduce some of the visualization functions of smplot2, such as its background themes, which improve aesthetics for subplotting. Then, in the next three sections, I will demonstrate how we can produce subplots in ggplot2 iteratively, and then combine them into a composite plot using a linear process (similar as shown in Figure 2 for Python’s matplotlib) with three examples. The examples will become increasingly more sophisticated to demonstrate there is no limit to how users can create and customize composite figures. The tutorial is summarized in Table 1 in the end.

Target audience

The tutorial assumes that readers have some basic knowledge of R and ggplot2, and some experience with working with data frames using functions such as filter(), group_by(), %>% and summarise(). They do not need to be familiar with concepts of programming or be fluent in any other programming languages, such as Python. Although, the examples in this tutorial use randomly generated data based on human vision studies, readers across disciplines will be able to adapt the codes/examples in this tutorial easily for their own purpose.

Readers who have not used ggplot2 and R should read Chapters 2-3 of the package’s documentation webpage (https://smin95.github.io/dataviz) before starting this tutorial. The chapters provide a step-by-step guide on how to install RStudio and use ggplot2. Those who have not worked with data frames in R are recommended to read the tutorial by Nordmann et al. (Nordmann et al., 2022) or the early sections of Chapter 7 of the documentation webpage (sections 7.1 & 7.2). Completing these two prerequisites for the tutorial would take about 2-3 hours.

Installation requirements for this tutorial

These two packages - tidyverse (Wickham et al., 2019) and smplot2 - should be downloaded for the completion of the tutorial from the Comprehensive R Archive Network (CRAN). The tidyverse package is a suite of multiple packages, such as ggplot2 (for plotting and saving visualizations), dplyr (for working with data frames), and readr (for reading external data files).

install.packages(c('tidyverse','smplot2')) # smplot2 version: 0.2.4

Open science practices

With more than 300 examples, smplot2 has been documented online in detail (https://smin95.github.io/dataviz) with 12 chapters devoted to the package at the time of writing. The documentation webpage was created using the bookdown package for reproducibility (source codes in https://www.github.com/smin95/dataviz). The codes in the tutorial are posted online (https://www.smin95.com/smplot2doc).

Simulated dataset

Amblyopia is a visual deficit with origins in the primary visual cortex (Min et al., 2022). The simulated data here represent visual health in individuals with amblyopia and normal vision at various experimental conditions and types of visual stimuli. They will be used throughout the rest of the tutorial.

df2 <- read_csv('https://www.smin95.com/amblyopia_random2.csv')

df2_amb <- df2 %>% filter(Group == 'Amblyopia') %>%
  mutate(logSF = log2(SF)) %>%
  mutate(Condition = factor(Condition, levels = c('One','Two','Three')))

head(df2_amb)

## # A tibble: 6 × 6
##   Subject  absBP    SF Group     Condition logSF
##   <chr>    <dbl> <dbl> <chr>     <fct>     <dbl>
## 1 A1      0.168    0.5 Amblyopia Three        -1
## 2 A1      1.37     1   Amblyopia Three         0
## 3 A1      1.29     2   Amblyopia Three         1
## 4 A1      2.67     4   Amblyopia Three         2
## 5 A1      0.0111   8   Amblyopia Three         3
## 6 A2      0.0136   0.5 Amblyopia Three        -1

This dataset should be loaded to memory using the code above. Throughout the tutorial, we will use %>% operator, which is known as the pipe. It allows the data frame from the previous operation of data transformation to be carried over or piped to the next operation. This reduces the burden of users from supplying the input data frame for each operation. To begin with, we extract the data from the df2 object only for individuals in the Group == 'Amblyopia' by using filter(). Next, the continuous variable SF, which is an acronym for spatial frequency, is converted into log2 scale using mutate(), which creates another column (logSF) based on the existing column (SF) in the data frame df2. Through this logarithmic operation in mutate(), a new column logSF is created, with equal spacing along its scale. Then, the data type of the Condition column is changed using mutate(); it is initially a string but mutate() converts it into a factor and then re-orders the level of the variable to its numerical order ('One'-'Two'-'Three'). After the data transformations, a newly formed data frame is stored in the object df2_amb, whose first six rows are displayed in the tutorial. Readers can double-check by comparing their own printed values of the df2_amb object to those in the tutorial.

The column absBP, which is short for absolute balance point, contains data of the dependent variable (y-axis). It is a measure of visual health. The higher the value, the worse the vision.

In this example, we will allocate data to each panel by using the variable Subject (i.e., subplotting with one variable). In other words, each panel will display the data of each subject (absBP as a function of logSF).

lapply()

lapply() is one of the apply functions from base R. It applies a function to a list or a vector, and returns a list with the same length as the input. A list is a data structure of an object that can contain different types of elements, such as strings, numbers and lists. Essentially, lapply() is similar to how a for loop works but it returns a list as output. Since ggplot2 objects can be stored in a list but not in other types of vectors, we will use lapply() to perform iterations. Pseudocode 3 shows the basic syntax of lapply().

# Pseudocode 3 
<OUTPUT> <- lapply(<INPUT>, <FUNCTION>, <ADDITIONAL ARGUMENTS>)

The input can be either a list or a vector. If the input has a length of five (i.e., five elements), then the function will be run five times, and an output list that has a length of five will be returned. In our case, the function will be plotting the data, with specific mapping and aesthetics, and generate ggplot2 objects. We will plot each of the nine individuals’ data, so we will run the function nine times (i.e., nine iterations). The returning output should therefore have a length of nine, each of which is a plot. Additional arguments can be passed to the function but in our tutorial there will not be any additional arguments, so these can be ignored.

First, we create an input object that specifies the nine subjects in the Amblyopia Group. The data frame df2 contains a column of identifiers for subjects. We see that these subjects have identifiers A1 to A9. These can be recreated as vector subj_list by concatenating the string 'A' with a sequence numbers 1:9 (1 to 9 in integers) using the function paste0(). So, the elements within the vector subj_list will contain subject identifiers that are also found in the Subject column of the data frame df2.

In the lapply() structure, through which we will plot the data of each subject on a separate panel, there should be two parts. The approach will be used throughout the rest of the tutorial, and it can be widely applicable across designs and disciplines:

1. The first part filters data using the index of the iteration. Here, iSubj is the index of the iteration, and it starts from 1 and ends at 9 as specified by 1:length(subj_list). During each iteration, the index is used to retrieve the element of the object subj_list, ex. A9 from subj_list[iSubj] when iSubj = 9. The extracted subject identifier is then used to filter for each subject’s data before plotting begins (ex. filter(Subject == subj_list[iSubj])). The filtered data is stored in the object subj_data, which will be used by the subsequent plotting functions; so, plotting will only use the filtered data from each subject.

2. The second part of the lapply() function plots the filtered data. The variables are mapped to aesthetics, and the appearance of the plot is customized using functions from ggplot2. Here, the specifications are set so that the data frame to be used is subj_data, that x is logSF, and that y is absBP, which is the outcome of interest in this simulated dataset. Moreover, the aesthetic group is mapped to the variable Condition of the data frame subj_data, so that the points are connected with lines for each condition. Also, within the ggplot() function, the shape, the filling color of the points (fill), as well as color of the lines are all set to be unique for each condition. In other words, all three conditions will be plotted in one panel of each subject at once.

In this example, each condition is coded to a unique shape with the function scale_shape_manual(). The first condition is coded to the shape value of 21 (circle with borders), the second to the value of 22 (square with borders), and the third to the value of 23 (triangle with borders). Since these shapes have borders, the argument fill determines their filling color, and color determines their border color, which is set to transparent. Similarly, with scale_fill_manual(), each condition is color coded to a specific filling color. The colors are specified in the object cList, which is defined outside the lapply() function using the sm_palette() function that returns three colors here. This function returns default colors of the package and is equivalent to sm_color(), except that it takes the number of colors as input instead of character strings specifying the colors. Users are encouraged to find their own color schemes from other packages, such as RColorBrewer and viridis, available in the R ecosystem.

subj_list <- paste0("A", 1:9) # 9 subjects
cList <- sm_palette(3) # Three colors from smplot2 (defaults)

indv_plots <- lapply(1:length(subj_list), function(iSubj) {
  # First part: Filter for each subject's data during each iteration
  subj_data <- df2_amb %>%
    filter(Subject == subj_list[iSubj])

  # Second part: Plot each subject's data
  ggplot(data = subj_data, aes(
    x = logSF, y = absBP, group = Condition,
    shape = Condition, fill = Condition, color = Condition
  )) +
    geom_line(linewidth = 1) +
    geom_point(size = 5, color = "transparent") +
    scale_color_manual(values = cList) +
    scale_fill_manual(values = cList) +
    scale_shape_manual(values = c(21, 22, 23)) +
    sm_hgrid() +
    scale_y_continuous(limits = c(0, 3)) +
    scale_x_continuous(
      limits = c(-1.3, 3.3),
      labels = c(0.5, 1, 2, 4, 8)
    )
})

As lapply() performs function each time, a plot will be generated. Each plot will get stored in the object indv_plots, which is a list. Since length(subj_list) is 9 and the input for the lapply() function is a digit from from 1 to 9 (1:length(subj_list)), there will be nine iterations, and hence, nine plots that will be generated.

When one codes for multiple subplots in a lapply() function (second part of the structure), it is important to make the limits of x- and y-axes identical. In the lapply() function, both have been specified using scale_y_continuous() (y-axis: 0 to 3) and scale_x_continuous() (x-axis: -1.3 to 1.3). If there is no specification of the limits, each plot will have its own limit based on each subject’s data. Also, notice that although we plot data as a function of the variable logSF, which has values of -1, 0, 1, 2 and 3, the tick labels of the x-axis are displayed as 0.5, 1, 2, 4 and 8. This is because the labels argument has been supplied with these specifications in the function scale_x_continuous(). Essentially, these inputs mask over the true values of the x ticks on the plot. This is a common method of plotting data in human vision studies because the visual system has been known to process information non-linearly (Baker, Wallis, Georgeson, & Meese, 2012), and it is specific to the examples in the tutorial.

To display a plot from the object indv_plots, users can type the name of the list indv_plots in the console, or subset for one specific subject’s plot using double brackets (ex. indv_plots[[3]]). This individual plot still has ticks for x- and y-axes as well as their labels. However, these will be removed automatically later or resized during the generation of a composite plot.

# Figure not shown
indv_plots[[3]] # Print the third plot from the list

Next, we define the title, as well as common x- and y-axes labels of the composite figure that we will create. As their names suggest, sm_common_title() sets the title of the combined figure, sm_common_xlabel() sets the common x-axis label of the combined plot, and sm_common_ylabel() sets the common y-axis label of the combined figure. In these three functions, x and y control the location of the texts. Their defaults are set to x = 0.5, y = 0.5 which refers to the center origin of their respective areas (x and y do not refer to the coordinate relative to the combined figure).

# Figure 4 - Set the title and axis labels of the composite figure
title <- sm_common_title("Individual data (subplotting with one variable)", x = 0.53, y = 0.52)
xlabel <- sm_common_xlabel("Spatial frequency (c/deg)", x = 0.52)
ylabel <- sm_common_ylabel("Visual deficit")

Notice that this process is highly similar to what is often used in Python’s matplotlib, where fig refers to the object that stores the combined figure (see Pseudocode 4).

# Pseudocode 4: Titles and axis labels in Python's matplotlib (Figure 4)
fig.suptitle('Individual data', x, y)
fig.text(x, y, 'Spatial frequency (c/deg)') # x-axis label
fig.text(x, y, 'Visual deficit', rotation = 90) # y-axis label

Figure 4. A composite plot with three columns and three rows. Each panel plots each subject’s data across all three conditions. A legend is absent in this figure.

In Python’s matplotlib, the text labels and the title get added to fig (the composite plot) using the object-oriented approach. Here, we will use sm_put_together(), which is essentially a layout function that creates a composite figure from individual plots. The output from sm_put_together() must be stored in an output object (ex. plots_tgd). Three inputs must be provided to run sm_put_together(): 1) the list object, which stores all plots (ex. all_plots argument = indv_plots), 2) the number of columns (ex. ncol argument = 3), and 3) the number of rows (ex. nrow argument = 3). There are optional arguments as well, such as title, xlabel and ylabel. For instance, if title is not supplied as input, then no space will be allocated for a common title in the composite figure. Here, we will supply title in sm_put_together(). In addition, the extent of blank spacing (i.e., margin) in both width (wmargin) and height (hmargin) can be adjusted (see Figure 2). In this example, they are set as negative values to minimize the spacing between subpanels.

# Figure 4 - Combine subplots into a specified layout
plots_tgd <- sm_put_together(
  all_plots = indv_plots, title = title, xlabel = xlabel,
  ylabel = ylabel, ncol = 3, nrow = 3,
  wmargin = -4.5, hmargin = -4.5
)

We can save the figure using ggsave() (see Figure 4). We supply the name of the image file in strings ('together1.pdf') as the function’s first input, and the object of the composite figure (plots_tgd) as its second input. This forces the function save the object plots_tgd as together1.pdf in your directory. Also, we set the dimension of the image so that it has a height and a width of 9 inches.

# Figure 4 - Save the composite output as a vector file
ggsave("together1.pdf", plots_tgd,
  width = 9, # inches
  height = 9
)

Immediately in Figure 4, we can notice that the function sm_put_together() has removed extraneous tick labels and titles from both axes in the inner panels. This was possible because we had provided the layout of the composite figure that was to be constructed in sm_put_together(), which is similar to how matplotlib controls the layout of the figure (see Pseudocode 2). Although the default of the function removes the extraneous ticks in inner panels (remove_ticks = 'some' in sm_put_together()), this option can be overwritten so that all ticks are kept (remove_ticks = 'none') or removed (remove_ticks = 'all'). The order of the subpanels follows that of plots that are generated by the lapply() code chunk. In this case, we set the layout to be (ncol = 3, nrow = 3), so axis ticks in the 2nd, 3rd, 5th and 6th panels in the composite figure are removed.

We can also label each panel by annotating each subject’s identifier (ex. A1 for Subject 1 in Amblyopia; see Figure 5). There are two ways of achieving this. The first way is revisit and modify the code chunk that generates the nine points iteratively using lapply(), but this goes against our aim of linearizing the process of subplotting. Therefore, we will use the function sm_panel_label() to label each panel.

# Figure 5 - Add subject identification label (ex. A1) in each panel
indv_plots_label1 <- sm_panel_label(
  all_plots = indv_plots, x = 0.15, y = 0.85,
  panel_pretag = "A", panel_tag = "1",
  text_color = "black"
)

The function sm_panel_label() has a few arguments, some of which are similar to those of the former function. For the first argument all_plots, users must provide the list vector (indv_plots) that stores all plots. Next, x and y determine the location of the panel label; 0.5 is the origin of the panel (i.e., the center of each subplot). panel_tag sets the string for enumeration. In this example, we set panel_tag = "1" so that the first panel will have “1” labelled but the next one will have “2”. There are other options to enumerate each panel, such as: 1) panel_tag = "A" for uppercase letters, 2) panel_tag = "a" for small case letters, 3) panel_tag = "I" for upper roman numerals, and 4) panel_tag = "i" for lower roman numerals. These options of the panel_tag argument were included as inspired by the plot_annotation() function of the patchwork package (Pedersen, 2019). Also, there are tag labels that can be set to be consistent across panels: panel_pretag and panel_posttag. As their names imply, panel_pretag comes before panel_tag, and panel_posttag comes after panel_tag. These two arguments can be any string at any lengths. To label each panel using the subject’s identifier that is consistent with those in the data frame df2 (ex. A1 and A3), panel_pretag should be “A”. Then, we store the output from sm_panel_label() in the object indv_plots_label1. The differences between plot_annotation() and sm_panel_label() are that in sm_panel_label() 1) the locations can be specified in x and y coordinates within but not outside each panel, 2) annotations can be added multiple times (as demonstrated in this example) in sequence, 3) the plot input must be a single list object rather than separate ggplot2 objects.

We will also label each panel so that the first panel has “a)” and the second panel has “b)”. To do so, we use the function sm_panel_label() again, where we provide the indv_plots_label1 object as input and set panel_tag = 'a' and panel_posttag = ')'. This creates labels with a small alphabet that is followed by a bracket in each panel. The final output is then saved in the indv_plots_label2 object, which is the end-result of running sm_panel_label() twice.

A composite plot with two rows and five columns. Nine panels display each subject’s data in the Amblyopia group, while the last panel shows the legend, representing each condition with a unique color.

# Figure 5 - Add panel label in small alphabets followed by a bracket
indv_plots_label2 <- sm_panel_label(
  all_plots = indv_plots_label1, x = 0.15, y = 0.7,
  panel_tag = "a", panel_posttag = ")",
  text_color = "black", fontface = "bold"
)

Next, we sort the nine panels into a layout with five columns and two rows (ncol = 5, nrow = 2) using the function sm_put_together(). We also add the common title, common x-axis label and common y-axis label by directly supplying character strings rather than using sm_common_*() functions. This option is less flexible but it is more convenient; the text size can still be adjusted using the labelRatio argument, where 1 refers to the default size, but not its location. The labelRatio argument does not affect the size of text labels created from sm_common_*() functions. sm_put_together() also supports combining subplots with secondary x- and y-axes (not shown in the tutorial); xlabel2 and ylabel2 should be provided to set the titles for these axes.

# Figure 5 - Combine the subplots into one figure
plots_tgd2 <- sm_put_together(
  all_plots = indv_plots_label2,
  title = "Individual data (subplotting with one variable)",
  xlabel = "Spatial frequency (c/deg)",
  ylabel = "Visual deficit", ncol = 5, nrow = 2,
  wmargin = -2, hmargin = -2, labelRatio = 0.9
)

Now that a composite figure has been created with individual subplots and labels, we will add a common legend in the combined figure plots_tgd2. There are two ways to do so using smplot2. There is a quick way and a slow but highly customizable way. They both involve the function sm_add_legend(). To preview, readers can compare the legend in Figure 5 from the quick method with the legend in Figure 6 from the slow method.

The first method of adding legend basically forces sm_add_legend() to derive a legend from a reference plot so that users do not have to manually make it. To make the legend using the quick method, users should provide some inputs for some arguments. The output from sm_put_together() (plots_tgd2) must be supplied as input for the argument combined_plot. The coordinate of the legend can be specified using x (horizontal coordinate of the legend) and y (vertical coordinate of the legend) arguments. Also, a reference plot from which the legend can be derived must be supplied for the argument sampleplot (i.e., one plot from indv_plots). In this example, the coordinate is set to be within the area of the empty 10th panel (x=0.92, y=0.35); the sample plot is derived from the first subject’s plot (indv_plots[[1]]). The direction argument (i.e., orientation) of the legend is specified to be vertical, not horizontal. legend_spacing is an argument that can set the extent of blank space within the legend to prevent overcrowding. If border = FALSE, then the border of the legend will be removed. The font size of the legend can be adjusted using the argument font_size. The code below stores the output from sm_add_legend() in the object plots_tgd2_legend, and then saves the figure as a vector file using the ggsave() function with specified width and height.

# Figure 5 - Legend in the area of the 10th panel 
plots_tgd2_legend <- sm_add_legend(
  combined_plot = plots_tgd2, x = 0.92, y = 0.35,
  sampleplot = indv_plots[[1]], direction = "vertical",
  legend_spacing = 1, border = TRUE, font_size = 13
)
# Figure 5 - Save the composite figure as a vector file
ggsave("together2.pdf", plots_tgd2_legend,
  width = 15, # inches
  height = 6.6
) 

We can make two observations from this legend in Figure 5. First, the legend’s title matches to one of the column’s name (Condition) in the data frame df2. Second, labels within legends are identical to the string characters that are provided in the Condition column of df2. So, these similarities indicate that the legend’s title and labels have been automatically generated according to the given data frame. If the legend is created in this quick approach (by forcing sm_add_legend() to derive one from a sample plot), the title and the labels cannot be customized although the title can be removed.

# Compute the average and standard error for each SF and Condition level
df2_amb_avg <- df2_amb %>%
  group_by(logSF, Condition) %>%
  summarise(
    avgBP = mean(absBP),
    stdErr = sm_stdErr(absBP), .groups = "drop"
  )

head(df2_amb_avg)

## # A tibble: 6 × 4
##   logSF Condition  avgBP stdErr
##   <dbl> <fct>      <dbl>  <dbl>
## 1    -1 One       0.0769 0.0182
## 2    -1 Two       0.283  0.0649
## 3    -1 Three     0.199  0.0720
## 4     0 One       0.234  0.151 
## 5     0 Two       0.491  0.0705
## 6     0 Three     0.374  0.135

Since we have one empty panel that is available for plotting (10th panel of Figure 5), we can add an additional panel, which shows the average data of the nine subjects with error bars (ex. standard error). This panel showing the average data should have the same x- and y-limits as those of the individual subjects’ panels. Next, we compute the average and standard errors of the data from nine individuals for each independent variable (logSF) and experimental condition (Condition), and store the resulting data frame into the object df2_amb_avg. The initial step can be achieved using functions from the dplyr package, such as group_by() and summarise(). group_by() does not change the data frame at the surface level. Instead, it changes its underlying structure so that the following functions that will be called later for computations within summarise() will be done separately for each grouped variable’s level. The two computations - mean and standard error - are conducted using the functions mean() and sm_stdErr(), respectively. The latter is a shortcut function from the smplot2 package. The grouping will remain even after the computation has been performed, so it is crucial to undo the grouping by setting .groups = 'drop' in summarise(). More information about these functions can be found in Chapter 7 of the documentation webpage (https://smin95.github.io/dataviz).

# Figure 6 - 10th panel showing the average data
avg_plot <- ggplot(data = df2_amb_avg, aes(
  x = logSF, y = avgBP, group = Condition,
  shape = Condition, fill = Condition, color = Condition
)) +
  geom_line(linewidth = 1) +
  geom_point(size = 5, color = "white", stroke = 1) +
  geom_linerange(aes(ymin = avgBP - stdErr, ymax = avgBP + stdErr), linewidth = 1) +
  scale_color_manual(values = sm_palette(3)) +
  scale_fill_manual(values = sm_palette(3)) +
  scale_shape_manual(values = c(21, 22, 23)) +
  sm_hgrid() +
  scale_y_continuous(limits = c(0, 3)) +
  scale_x_continuous(
    limits = c(-1.3, 3.3),
    labels = c(0.5, 1, 2, 4, 8)
  ) +
  annotate("text", label = "Average", x = -0.3, y = 2.65, size = 5.5,
           fontface='bold')

Figure 6. A composite plot with two rows and five columns with a common legend that is located at the bottom-right area of the figure. The first nine panels display each subject’s data from the Amblyopia group, while the last panel shows the average data with error bars, which represent standard errors.

With the newly created data frame df2_amb_avg, we can plot the average data using the same mapping specifications as those in the individual plots in the lapply() function. Average data are plotted as points with white borders using the geom_point() function. The lines are drawn to join the points with geom_line(), and the error bars without caps are displayed using geom_linerange(), which is a useful function for indicating intervals of some range. The aesthetic mapping is defined in geom_linerange() so that vertical lines with certain ranges can be plotted at each level of logSF (x-axis); we explicitly specify the minimum (ymin = avgBP - stdErr) and maximum (ymax = avgBP + stdErr) of the vertical range to be equal to the range of the standard error of the average data. We do not use lapply() function here because we need to make one plot.

# Figure 6 - Combine all the subplots into a composite plot
all_plots <- list(indv_plots_label1, avg_plot)

plots_tgd3 <- sm_put_together(
  all_plots = all_plots,
  title = "Individual data and average (subplotting with one variable)",
  xlabel = "Spatial frequency (c/deg)",
  ylabel = "Visual deficit", ncol = 5, nrow = 2,
  wmargin = -4.5, hmargin = -4.5, labelRatio = 0.9
)

The limits of both x- and y-axes, as well as the thematic background (i.e., sm_hgrid()), are set to be identical to those of the individual plots. Also, we annotate the average plot with the bolded text 'Average' using annotate(), where we can specify its coordinate to be at the top-left of the panel (x = -0.3, y = 2.65) in the units of the plotted data (x = logSF, y = avgBP). The plot output is then saved in the object avg_plot.

Then, we store all ten plots (9 individuals’ plots in indv_plots_label1 + one average plot in avg_plot) that we have generated into one list using the function list() and then assign the output to the object all_plots. The all_plots object will be the input for sm_put_together(), which will create a composite plot using the plots, title and axis labels with a layout (ncol = 5 and nrow = 2).

Since we have ten panels to plot in a layout with five columns and two rows, there should already be a limited amount of available space for the legend (see Figure 6 for our final output). So, to effectively use the remaining plotting space, we will have to build and customize a legend using the function sm_common_legend() rather than relying on the automatically generated legend from sm_add_legend(). After creating a legend manually, we can then add it to the composite plot using sm_add_legend() at a specific location within the combined figure. This option requires more work but it is more flexible.

To do so, we need to essentially create a new plot using the standard procedure of ggplot2 (see codes below). This includes setting the mapping the x and y variables to certain aesthetics. Points are also drawn using geom_point() so that they are included in the legend. The legend labels have also been changed, as specified in the two scale_*() functions. Finally, we finish creating the legend by using sm_common_legend(), which essentially hides all features of a normal graph, such as points and axis lines that will be plotted otherwise. As a result, the output legend2 only prints the legend components when it gets called. We set the legend to have a horizontal orientation with no borders (border = FALSE). The text size of the legend can also be adjusted using the argument textRatio, which has been set to 1.1 in this example; this means that the text size of the legend is 1.1x larger than the default from a given theme. Lastly, legend_spacing controls the amount of blank space in the legend.

# Figure 6 - Create a legend manually 
legend2 <- ggplot(data = df2_amb, aes(
  x = logSF, y = absBP, group = Condition,
  shape = Condition, fill = Condition
)) +
  geom_point(size = 4.5, color = "white") +
  scale_fill_manual(
    values = sm_palette(3),
    labels = c(
      "Condition 1 ", "Condition 2 ",
      "Condition 3 "
    )
  ) +
  scale_shape_manual(
    values = c(21, 22, 23),
    labels = c(
      "Condition 1 ", "Condition 2 ",
      "Condition 3 "
    )
  ) +
  sm_common_legend(
    title = FALSE, direction = "horizontal", border = FALSE,
    textRatio = 1.1, legend_spacing = .9
  )

The customized legend can be added to the composite plot with the function sm_add_legend() at a specific coordinate (x = 0.84, y = 0.05; bottom-right region of Figure 6). Since we have manually created the legend with sm_common_legend(), there is no need for us to supply inputs for other arguments in sm_add_legend(), such as direction, border and sampleplot, all of which will be ignored. The final output - a composite figure that shows both individual plots and a panel that shows the average data (Figure 6) - is saved using ggsave() from the ggplot2 package.

# Figure 6 - Save the figure with a legend as a vector file
plots_tgd3_legend <- sm_add_legend(
  combined_plot = plots_tgd3, legend = legend2, x = 0.84,
  y = 0.05
)

ggsave("together3.pdf", plots_tgd3_legend,
  width = 15, # inches
  height = 6.6
) 

Readers might realize that they could also generate Figures 4-6 with facet_wrap(). Indeed, when subplotting data using one variable, using facet_wrap() might be simpler. However, the advantage of using smplot2’s pipeline with lapply() is that it remains very similar even if more variables or lapply() functions are added (next two examples).

Key advantages of smplot2

The smplot2 package can provide benefits to both entry-level and advanced R users.

To begin with, a major advantage of smplot2 for incoming users, as noted by a recent review from a group of clinicians (Gandhi, Tripathy, Pawale, & Bhawalkar, 2024), is that it flattens the learning curve of ggplot2 (item #1 in Table 2). The visualization functions are flexible, and their aesthetics have been optimized for the general format of scientific journals (Min & Zhou, 2021). More than 300 reproducible examples are provided in the documentation page (https://smin95.github.io/dataviz), so users can freely use and modify these codes for their own purposes. In addition, the codes of the package have been reviewed for quality and stability across different computing systems by CRAN. Some of the functions that users from eclectic fields and levels of experience have used are raincloud plots (Chen et al., 2023; Gómez-Robles, Nicolaou, Smaers, & Sherwood, 2024), regression analyses (Hamad, Alcaraz, & Villarreal, 2024; Ilyés, Paulik, & Keresztes, 2023), forest plots (Grobler & Kramer, 2023) in both standalone and composite forms.

For users with working knowledge of R and ggplot2, smplot2 has potential to impact how they perform complex and sophisticated data visualizations. Specifically, it provides key functions for them to integrate the practices of data visualization using ggplot2 and the programmatic approach as smplot2 overcomes the limited flexibility of aesthetics at the level of composite figures in ggplot2. Namely, it provides a complete, flexible and linear workflow for combining multiple ggplot2 outputs into a composite plot. It also integrates the programmatic approach, which can generate multiple ggplot2 outputs, into the visualization pipeline by handling different (nested) structures of list objects from lapply() functions or other methods (ex. map()) that are compatible with ggplot2. Furthermore, it enables users to adjust marginal space and annotate both within and across subplots in any form after a composite plot has been constructed, encouraging users to apply the programmatic approach rather than to create each plot separately. Therefore, it will motivate users to search for solutions within their scripts rather than to find third-party packages that resolve issues in plotting. In sum, the package has potential to empower users by allowing them to create more customizable, dynamic and expressive figures, promoting the reproducibility of complex visualization routines, and linearizing the workflow of visualizing a composite plot.

Numerous packages, such as ggfortify (Tang et al., 2016), ggstatsplot (Patil, 2021) and GGally (Schloerke et al., 2021), have been developed to allow users to easily plot data using different types of graphs in a few lines of codes (shortcut functions; item #2 in Table 2), thereby extending the functionalities of ggplot2 and flattening the steep learning curve for beginners. There are also packages, such as grid, patchwork and gridExtra, that provide functions for users to create composite figures in ggplot2 in various layouts from combining discrete ggplot2 objects (item #3 in Table 2). This approach has been widely used so that users can achieve a maximum flexibility of aesthetics of the combined figure (see Figure 1). Nevertheless, they do not offer significant versatility for users after subplots (multiple ggplot2 objects) have been combined into a composite plot, thereby encouraging users to create plots separately and shirking away from applying programmatic practices (item #4 in Table 2). For instance, after multiple ggplot2 objects are combined into one form, controlling the positions of legends and annotations, as well as extent of margin between subplots, in the combined figure becomes more difficult (items #5-7 in Table 2), a task that can be easily performed in Python’s matplotlib. This has made users to implement practices that go against the principles of open science, such as using a vector graphics software (ex. Adobe Illustrator) to annotate the final figure generated from R. These restrictions can now be lifted with smplot2, which linearizes the workflow for complex data visualizations (item #8 in Table 2) and elevates the level of customization for aesthetics in situations where users want to stitch multiple ggplot2 objects together to construct a composite plot.

R or Python?

The dispute about which of ggplot2 and matplotlib is better for data visualization has been ongoing for some time (Ozgur, Colliau, Rogers, & Hughes, 2017). A well-known plotting package that complements matplotlib, seaborn (Waskom, 2021) has captivated a wide user base in Python with its beautiful aesthetics and shortcut functions for plotting. The two libraries (seaborn and matplotlib) embrace the programmatic approach, requiring users to apply iterations and conditional statements to plot data. Although this steepens the learning curve for users, it increases flexibility for aesthetics, allowing users to dynamically control each component of the figure. A comparable library to matplotlib in R is ggplot2, which is convenient for plotting different types of graphs without the requirement for users to understand concepts of programming, such as loops and functional methods, primarily due to its layered approach. This simplicity, along with the fact that ggplot2 can generally reproduce figures from matplotlib with less lines of code, has expanded its user base rapidly (see Figure 1). However, this layered approach comes at a cost because it hinders users from controlling the aesthetics using the programmatic approach. Although ggplot2 can be superior in many aspects of visualizations to matplotlib, notably for concisely plotting different types of graphs with its declarative syntax, its design can complicate the workflow for users when it comes to subplotting and creating composite figures, leaving Python’s matplotlib slightly more suitable for performing complex visualizations (see Table 2 for their comparisons).

Throughout the tutorial, I have compared Python’s matplotlib and R’s ggplot2 closely to demonstrate that the gap between ggplot2 and matplotlib has been minimized with smplot2 in the realms of subplotting and flexibility. With the arrival of smplot2, it is now possible to linearize the process of subplotting with its clear starting and ending points because the package integrates the interface of ggplot2 and the programmatic approach.

Why use the programmatic approach?

So far, the programmatic approach has not been ideal in ggplot2 because it creates various ggplot2 objects that need to be joined together using other packages. Unfortunately, the level of aesthetic control decreases steeply from when a plot is built as a single ggplot2 output to when multiple outputs are combined into a composite figure, encouraging users to generate each subplot separately. However, in this tutorial, I have demonstrated the efficiency of the programmatic approach with three examples using smplot2.

I support this plotting method for several reasons. First, complex data visualizations, such as composite plots, can be performed concisely. Second, it increases code readability and reproducibility because the pipeline remains very similar regardless of the number of variables or lapply() functions. Third, it lifts aesthetic limitations of composite plots by integrating the native R programming practices with ggplot2’s declarative syntax.

For example, users can create a complex composite plot, such as a lower triangular matrix form, without relying on external packages. They can use lapply() function to create empty panels in specific panels, and then combine them using sm_put_together(). The panels will be arranged in a triangular layout. To create an empty plot, users can type ggplot(NULL) + sm_common_legend() (see examples in Chapter 7 of the documentation webpage), which has no aesthetic mappings (no legend). After creating a composite plot with sm_put_together(), users can also add annotations in any forms at any coordinates within the composite figure using the layered approach of ggplot2. In summary, smplot2’s programmatic approach with lapply() can empower users to perform sophisticated visualizations with ggplot2.

Closing remarks

In this tutorial, I have introduced smplot2, an R package that provides a structured workflow for plotting by integrating a programmatic approach, as well as visualization and layout functions for advanced data visualizations. The defaults of the plots generated by the package are simple and minimalistic, and have also been optimized for subplotting so that individual components of the figure are still clearly visible in a composite plot. Also, the functions introduce a linear process of creating a composite figure by giving users a full control of aesthetics at multiple stages of plotting in ggplot2. I hope that the package can encourage more users to use R as part of their visualization routines.