1.1 What we’ll cover

Developments in generative artificial intelligence (AI) using large language models (LLMs) is revolutizing the way the people code. We have covered in many past Code Clubs how to use ggplot2 in R to make the plots of your dreams, and today we are going to talk about aiding that process using AI.

By the end of the session, you should be more comfortable with using AI to aid in your plotting. Specifically, we’ll cover:

• The basics of ggplot2 syntax
• Using AI to make a simple plot
• Using prompts to refine that plot more
• Prompting to make a much more complicated figure

1.2 Before we start

We are going to be working in Positron for the rest of the semester. If you haven’t done so already, please:

1. Install Positron: download the appropriate installer from the download page, and run it. There are installers for Windows, macOS, and Linux.

2. Make sure you have a recent R (4.4.0 or higher) installed; Positron does not come with its own copy of R.

2.1 Opening a folder (replaces RStudio Projects)

Let’s open a new folder for today’s session:

1. You can use the folder you created last month when you learned about Positron from Jelmer, or you can create a new folder to use today. You can create it in any way, such as with your computer’s File Explorer / Finder.

   I would suggest putting this folder within a folder for Code Club, for example: Documents > codeclub > 26-au (or put another way: ~/Documents/codeclub/26-au). Again, it would be fine to use the same folder from our August session.

2. Open this folder in Positron by clicking the Open Folder button shown above¹.

3. Positron will reload and ask whether you want to trust the folder. Click Yes, I trust the authors and optionally check the box above it.

Why are Projects or open folders needed? These encourage good practices:

• Keep each research project in its own self-contained folder
• Use paths relative to the folder root, not absolute paths
• Avoid using setwd()

They also make a lot of Positron’s features work better, such as the Explorer, Search, and version control support.

2.2 Setting up Positron to use GitHub Copilot with Posit Assistant

You can set up Posit Assistant to work with a variety of different LLMs. Today we will set it up for using GitHub Copilot.

The two main AI tools we have are:

1. Code completions where you get AI suggested completions as you type
2. Agentic chat using Posit Assistant where you can both get code suggestions and have the agent run the code for you.

2.3 Starting an R session

Near the top-right corner of the Positron window is the so-called interpreter picker, which lets you choose which installation of R (or Python) to use for your session.

If Positron found your R installation, it may have started a session already — then it would look similar to what’s shown in the screenshot on the right (with the R version number corresponding to what you have installed).

3.1 Installing and loading the tidyverse

Before we start going through the syntactical basics, we need to have ggplot2 installed in R. If you were here last time, you’ll already have the tidyverse (and ggplot2 is one of the packages contain in this meta-package), but if you weren’t then you will need to first download it using install.packages(). Then you can load the tidyverse by calling it with the function library().

library(tidyverse)

We are going to use the penguins dataset that comes preloaded with base R. If you want to see all of these datasets, you can run library(help = "datasets")

glimpse(datasets::penguins)

Rows: 344
Columns: 8
$ species     <fct> Adelie, Adelie, Adelie, Adelie, Adelie, Adelie, Adelie, Ad…
$ island      <fct> Torgersen, Torgersen, Torgersen, Torgersen, Torgersen, Tor…
$ bill_len    <dbl> 39.1, 39.5, 40.3, NA, 36.7, 39.3, 38.9, 39.2, 34.1, 42.0, …
$ bill_dep    <dbl> 18.7, 17.4, 18.0, NA, 19.3, 20.6, 17.8, 19.6, 18.1, 20.2, …
$ flipper_len <int> 181, 186, 195, NA, 193, 190, 181, 195, 193, 190, 186, 180,…
$ body_mass   <int> 3750, 3800, 3250, NA, 3450, 3650, 3625, 4675, 3475, 4250, …
$ sex         <fct> male, female, female, NA, female, male, female, male, NA, …
$ year        <int> 2007, 2007, 2007, 2007, 2007, 2007, 2007, 2007, 2007, 2007…

I am clipping below a bit of the []ggplot2 cheatsheet](https://github.com/rstudio/cheatsheets/blob/main/data-visualization.pdf) to see how the developesr explain the basis of plotting.

The general syntax is like this:

data |> # start with dataframe and pipe to ggplot()
  ggplot(aes(x = _x-variable_, # inside aes set variables mapped to visual aspects
             y = _y-variable_, 
             color = _color-variable)) + 
    geom_*() + # add a geometry - the type of plot
    scale_*() + # set how data maps to visual aspects 
    theme_*() + # adjust the overall look of the plot
    labs() + # add labels - title, axes, legend

You can find the full ggplot2 cheatsheet also for reference.

1.1 What we’ll cover

Every Code Club session so far has used RStudio. Today we’ll spend the session in a different program: Positron, a newer data science IDE from Posit, the same company that makes RStudio.

By the end of the session, you should be able to open your own work in Positron, find your way around, and decide for yourself whether you want to keep using it. Specifically, we’ll cover:

• Installing Positron and opening a folder
• Touring the interface
• Exploring data — the Data Explorer, Variables pane, and Plots pane
• Customizing Positron — keyboard shortcuts, settings, and extensions

1.2 Why is there a new IDE?

Basically, Posit wanted better support for other programming languages, particularly Python, alongside R. This turned out to be harder with RStudio than starting fresh, so they created a new IDE: Positron.

Positron is built on Code OSS, the open-source version of the popular general-purpose code IDE called Visual Studio Code (VS Code). It adds data science features that RStudio has but VS Code does not, such as a Variables pane, a Plots pane, and a Data Explorer.

1.3 Why should you consider switching?

If you use Python alongside R, or are already familiar with VS Code, Positron is a natural choice and I’d strongly recommend switching.

If you use R only, you may not need to switch, but should still consider it, because:

• New features: While Posit has committed to maintaining and updating RStudio, major new features are now going to Positron first. And some features may never make it to RStudio, because Positron is more adaptable.

• AI support: This is much more flexible in Positron, where you can connect to different model providers and subscriptions, and even use Claude Code. In RStudio, you can only use AI via a Posit AI subscription. We’ll demonstrate using AI assistance in Positron in the next session!

And two more minor points:

• Data Explorer: Positron’s Data Explorer can open data files (CSV, Excel, etc.) directly, without having to load them in R at all.

• Remote connections: A niche feature, but it was important to me: Positron can be connected to the Ohio Supercomputer Center and any other remote server. This isn’t possible with RStudio and while you can use RStudio directly at OSC through OSC OnDemand, this has its downsides. (Happy to expand on this for any OSC users!)

1.4 Before we start

If you haven’t done so already, please:

1. Install Positron: download the appropriate installer from the download page, and run it. There are installers for Windows, macOS, and Linux.

2. Make sure you have a recent R (4.4.0 or higher) installed; Positron does not come with its own copy of R.

2.1 Opening a folder (replaces RStudio Projects!)

1. Create a new folder on your computer. You can create it in any way, such as with your File Explorer / Finder.

   I would suggest putting this folder within a folder for Code Club, for example: Documents > codeclub > positron (or put another way: ~/Documents/codeclub/positron).

2. Open this folder in Positron by clicking the Open Folder button shown above¹.

3. Positron will reload and ask whether you want to trust the folder. Click Yes, I trust the authors and optionally check the box above it.

Why are Projects or open folders needed? These encourage good practices:

• Keep each research project in its own self-contained folder
• Use paths relative to the folder root, not absolute paths
• Avoid using setwd()

They also make a lot of Positron’s features work better, such as the Explorer, Search, and version control support.

2.2 Starting an R session

If not, click the picker, and choose your version of R (you may have to click New Console Session before you see the options).

Once a session is running, the R Console works just like in RStudio. Try it:

1 + 1

[1] 2

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

x <- 1

x

Error:
! object 'x' not found

2.3 Packages and a script

We’ll use the flights dataset from the nycflights13 package: every flight that departed New York City in 2013. I picked a relatively large dataset, so we can see some of the nice features of the Data Explorer later.

First, let’s install the packages we need:

install.packages("tidyverse")
install.packages("nycflights13")

Now, let’s create a new R script:

• This can be done in several ways, but here is one: Click File (or the “New” button) > New File..., then select “R File”.

• Save it right away (File > Save or Save As, or Cmd/Ctrl+S) in your current folder as explore.R.

I recommend that you add all the code below to this script, and run it from the script (instead of typing it into the console).

Load the two packages we’ll use:

library(tidyverse)
library(nycflights13)

Run the code with Cmd/Ctrl+Enter — the same shortcut as in RStudio. Also as in RStudio, this moves the cursor down after running the current line (or your selection of a part of a line or multiple lines).

2.4 The Command Palette

The Command Palette is Positron’s main way to access the program’s functionality. It may take some getting used to, but is very handy and powerful.

To open the Command Palette, press Cmd+Shift+P (Mac) or Ctrl+Shift+P (Windows).

A search box will appear at the top of the window: start typing what you want to do, and Positron will fuzzy-match it against every piece of functionality (command) it knows. Here are some things you might think of looking for in the Command Palette:

• Type theme → Preferences: Color Theme
• Type restart → Interpreter: Restart Active Interpreter Session
• Type settings → Preferences: Open Settings (UI)

3.1 The five regions

Almost every pane in Positron can be resized (like in RStudio) and dragged somewhere else (much more flexible than in RStudio). There are also layout presets.

3.2 The Activity and Primary Side Bars

The Activity Bar is the strip of icons on the far left. Clicking an icon swaps out what’s shown in the Primary Side Bar right next to it. Among the options are:

4.1 The Variables pane

Look at the Variables pane on the right: flights should now be listed there. It’s the equivalent of RStudio’s Environment pane, and like there, you can expand objects to look inside them by clicking the arrow next to an object’s name.

Try expanding flights. You should see each column, its type, and a preview of its contents.

4.2 The Data Explorer

The Data Explorer is Positron’s equivalent of RStudio’s View() function, but with a lot more functionality. Click the small table icon next to flights in the Variables pane, and it should open as an editor Tab and look something like this:

The Data Explorer has three parts:

• The data grid — the spreadsheet-like view of your rows and columns
• The summary panel — per-column statistics and a small distribution plot. May be hidden by default: if you don’t see it, look for an arrow on the left-hand side of the spreadsheet view.
• The filter bar — for temporarily filtering rows

# Make a copy of the data as a CSV file, so we have a data file to work with
dir.create("data")
write_csv(flights, "data/flights.csv")

4.3 Plots

Let’s create a plot, so we can see where it appears. Copy the following code into the plots.R script and run it:

ggplot(flights, aes(x = arr_delay)) +
  geom_histogram(bins = 100, fill = "steelblue", color = "grey20") +
  geom_vline(xintercept = 0, color = "tomato1", linetype = "dashed") +
  scale_x_continuous(limits = c(-100, 300)) +
  scale_y_continuous(
    expand = expansion(mult = c(0, 0.05)),
    labels = scales::comma_format()
  ) +
  labs(x = "Arrival delay (minutes)", y = "Number of flights") +
  theme_bw(base_size = 14) +
  theme(panel.grid.minor = element_blank())

Warning: Removed 10041 rows containing non-finite outside the scale range
(`stat_bin()`).

Warning: Removed 2 rows containing missing values or values outside the scale range
(`geom_bar()`).

The Plots pane behaves much like RStudio’s, including the back/forward arrows through your plot history. Two things to try:

• The expand button, which pops the plot out into a large editor tab.
• Click the circle icon (to the right of “Auto”), and you should see options “Dark Filter” and “Follow Theme” (and the default “No Filter”): Dark Filter will show the plot on a dark background, and Follow Theme will match your color theme. Handy for those who prefer a dark theme for their IDE!

5.1 Extensions

Positron has many extensions (add-ins) that you can install, in large part because most VS Code extensions are compatible with Positron. To find and install extensions, click the Extensions icon in the Activity Bar (four blocks, with one set apart from the other three). Some useful ones:

x=c(1,2,   3,4)
y   <-1:10

ggplot(flights, aes(x = arr_delay)) + geom_histogram(bins = 100, fill = "steelblue", color = "grey20") +
  scale_y_continuous(expand = expansion(mult = c(0, 0.05)), labels = scales::comma_format())

5.2 Settings: the UI and the JSON file

The main way to change Positron’s settings is the Settings UI: open the Command Palette and run Preferences: Open Settings (UI). We’ll explore some Editor-related settings next.

5.3 Editor features and settings

"editor.emptySelectionClipboard": false

5.4 Keyboard shortcuts (keybindings)

Open the Command Palette and run Preferences: Open Keyboard Shortcuts to see every action (command) you can perform in Positron, and their current shortcut (if it has one) in a searchable list — type a command name or describe the action you want (e.g. run line) to find it.

You can click any row to record a new shortcut, and right-click to reset it back to default.

"workbench.keybindings.rstudioKeybindings": true

1.1 The Final Check

On Day 2, we learned about the ultimate package spellcheck: devtools::check(). This function is the gatekeeper for publishing.

Run it now in your console:

devtools::check()

Look at the bottom of your console output. Your goal before proceeding is 0 Errors, 0 Warnings, and 0 Notes!

Errors: Your package is fundamentally broken. Must be fixed.

Warnings: Your package works, but you did something risky. Must be fixed if you want to go to CRAN.

Notes: Minor formatting suggestions. CRAN reviewers might let a Note slide, but it’s best practice to resolve them.

2.1 Step 1: Version Control with Git

Your project needs to be a Git repository before it can go to GitHub. The usethis package makes this a one-liner. Run this in your console:

usethis::use_git()

RStudio will ask if it is okay to commit your files and restart. Select “Yes” to both.

2.2 Step 2: Authentication (The Tricky Part!)

To send code from your local computer to GitHub, GitHub needs to know it’s really you. We do this using a Personal Access Token.

1. Create the Token: Run this command. It will open a GitHub webpage in your browser.

usethis::create_github_token()

2. Scroll down on the webpage and click “Generate Token”.

3. Copy the token (it looks like a long string of random letters and numbers). Do not lose this!

4. Give the Token to R: Go back to RStudio and run:

5. Paste your token into the console when prompted and hit Enter.

2.3 Step 3: Push to GitHub

Now that RStudio and GitHub are linked, you can push your package to the cloud!

usethis::use_github()

# They only need to run this once
install.packages("remotes")
remotes::install_github("your-username/vizwizard")

3.1 Step 1: Cross-Platform Testing

Your computer is only one operating system. R has a built-in “inspector” that checks your package, but CRAN requires your package to work on all operating systems. devtools provides ways to send your package to external servers to be tested.

Run these and wait for the email results:

# Test on a CRAN-like Windows server
devtools::check_win_devel()

# Test on a CRAN-like Mac server
devtools::check_mac_release()

3.2 Step 2: The Final Submission

If your local devtools::check() is totally clean, and your cross-platform checks came back green, you are ready to submit!

devtools::release()

R will ask you a series of questions to double-check that you are absolutely ready. Once you say yes, it bundles your package and emails it to the CRAN team. You will usually hear back from a volunteer reviewer within a few days.

4.1 Problem 1: The DESCRIPTION File Dependency Error

Scenario: You ran devtools::check() and got the following Error:

Error: namespace ‘ggplot2’ is not available and has been NOTED.

usethis::use_package("ggplot2")

4.2 Problem 2: The “Undocumented Argument” Warning

Scenario: You ran devtools::check() and received a Warning:

Warning: Undocumented arguments in documentation object ‘pub_scatter’: ‘color_var’

4.3 Problem 3: The CRAN Rejection

Scenario: You submitted to CRAN, but two days later you get an email from a reviewer saying:

“Please do not use T and F in your code. Spell out TRUE and FALSE. Please fix and resubmit.”

Conclusion: You Did It! Congratulations! Over the last three days, you have conquered one of the steepest learning curves in the R ecosystem. You’ve learned how to harness usethis to generate boilerplate code , use tidy evaluation ({{ }}) for custom functions , bundle data, and ultimately share your work with the world. +2

Whether you keep your packages local, put them on GitHub, or send them to CRAN, you are now an R Package Developer. Happy coding!

1.1 The Problem: Where does the data go?

When you write a normal R script, you usually load data from your computer.

Windows users might use a path like read_csv("C:/Users/Name/Documents/my_data.csv").

Mac users might use a path like read_csv("~/Documents/my_data.csv").

If you share your package with a colleague on a different operating system, those hard-coded paths will instantly break!

1.2 The Solution: R packages have a special built-in way to store data so that it is always available whenever you type library(vizwizard), regardless of whether the user is on a Mac or a PC.

2.1 Step 1: Set up the raw data folder

Run this command in your console:

usethis::use_data_raw(name = "lab_demographics")

What this does: It creates a new folder called data-raw/ and opens a script inside it. This script is basically your “scratchpad.” It’s where you put the code that reads your messy CSVs and cleans them up.

2.2 Step 2: Write your cleaning code and save the data

Inside that new data-raw/lab_demographics.R script, you might write something like this:

# 1. Pretend we are loading and cleaning a dataset here
# (For this example, we will just create a small dataframe from scratch)
lab_demographics <- data.frame(
  group = c("Control", "Treatment A", "Treatment B"),
  target_n = c(100, 50, 50),
  active = c(TRUE, TRUE, FALSE)
)

# 2. THE MAGIC STEP: Save it to the package!
usethis::use_data(lab_demographics, overwrite = TRUE)

What this does: use_data() takes your cleaned dataframe and secretly compresses it into a special .rda (R Data) file inside a hidden data/ folder.

Now, if you install your package and restart R, you can just type lab_demographics into the console and the data will appear, as if by magic!

Practice: Exporting your own simple dataset

Your Turn: Create a very simple dataset called my_favorite_colors that contains a dataframe of two columns: color_name and hex_code. Save it to your package using usethis::use_data().

# Create the dataset directly in your workspace
my_favorite_colors <- data.frame(
  color_name = c("Navy", "Forest Green", "Crimson"),
  hex_code = c("#000080", "#228B22", "#DC143C")
)

# Save it so it lives inside your package forever!
usethis::use_data(my_favorite_colors, overwrite = TRUE)

3.1 Tutorial: Density Plots with Means

On Day 1, we learned that when we pass unquoted column names (like body_mass_g) into our custom functions, we have to wrap them in “curly-curly” braces ({{ }}).

Let’s use that rule to build a function that adds multiple layers to a plot. We are going to make a pub_density() function. It will:

Draw a density plot (a smoothed-out histogram).

Automatically calculate the overall average (mean) of the data.

Draw a dashed vertical line right at that average.

#' Create a Publication-Ready Density Plot with a Mean Line
#'
#' @param data A dataframe
#' @param numeric_var The numeric variable to plot (unquoted)
#' @return A ggplot object
#' @export
pub_density <- function(data, numeric_var) {
  
  # Step 1: Calculate the mean of the variable the user provides
  # We use drop_na() so the mean calculation doesn't fail if there are blanks!
  mean_val <- data %>% 
    drop_na({{ numeric_var }}) %>% 
    summarize(avg = mean({{ numeric_var }})) %>% 
    pull(avg) # 'pull' extracts just the number out of the dataframe
  
  # Step 2: Build the plot
  ggplot(data, aes(x = {{ numeric_var }})) +
    # Layer 1: The density curve
    geom_density(fill = "lightblue", alpha = 0.6, color = "darkblue") +
    # Layer 2: The vertical line for the mean
    geom_vline(xintercept = mean_val, color = "red", linetype = "dashed", size = 1) +
    # Layer 3: Clean up the theme
    theme_minimal(base_size = 14) +
    labs(subtitle = paste("The red dashed line represents the mean:", round(mean_val, 2)))
}

# Test it out on the penguins dataset!
pub_density(penguins, body_mass_g) +
  labs(title = "Distribution of Penguin Body Mass", x = "Body Mass (g)")

Warning: Using `size` aesthetic for lines was deprecated in ggplot2 3.4.0.
ℹ Please use `linewidth` instead.

Warning: Removed 2 rows containing non-finite outside the scale range
(`stat_density()`).

Practice: The Simple Violin Plot

Your Turn: Write a function called pub_violin. It should take a dataframe, a categorical x_var, and a numeric y_var. It should output a geom_violin() plot. Make sure the violins are filled with a color based on the x_var.

#' Create a Simple Violin Plot
#'
#' @param data A dataframe
#' @param x_var A categorical variable for the x-axis (unquoted)
#' @param y_var A numeric variable for the y-axis (unquoted)
#' @return A ggplot object
#' @export
pub_violin <- function(data, x_var, y_var) {
  
  ggplot(data, aes(x = {{ x_var }}, y = {{ y_var }}, fill = {{ x_var }})) +
    # Trim = FALSE makes the violin tails look a bit more natural
    geom_violin(trim = FALSE, alpha = 0.7) +
    theme_classic(base_size = 14) +
    theme(
      legend.position = "none" # Hide the legend since the x-axis already tells us the groups!
    )
}

# Test it out!
pub_violin(penguins, species, flipper_length_mm) +
  labs(title = "Penguin Flipper Lengths by Species")

Warning: Removed 2 rows containing non-finite outside the scale range
(`stat_ydensity()`).

7.1 Tips for getting good R Package code from AI:

Be specific about the Tidyverse: R has changed a lot in 10 years. If you ask an AI for a plot, it might give you ancient Base R code.

1.1 An R package example

An example of an R package I, Neel, made was in order to solve an issue that recurs in the field of health sciences often - what is the best (standardized) way to code for various clinical indices? For instance, everyone might code a fibrosis index differently in a programming language due to logical nuances or due to complex logic, omit it entirely due to technological complexity. To solve this issue, I spent around 1.5 years coding every single clinical formula into R as a simple programming workflow to ensure this issue wouldn’t be faced!

This is a helpful resource whenever you want to see documentation for packages online, and you can find many more on rdocumentation.org! By lesson 3, you will have all the tools to have your own package listed on rdocumentation.org, and published to the entire R community to download and use for their own purposes!

Today, we are going to focus on:

• Setting up an R package skeleton using the usethis package.

• Understanding how to pass unquoted variable names into functions (Tidy Evaluation).

• Writing a function for a publication-ready ggplot2 histogram.

• Writing a function for a professional summary table using gt.

• Let’s start by loading the tools we will use to build and test our new package.

library(devtools) # Core package development tools

Loading required package: usethis

library(usethis)  # Automates the tedious parts of package setup
library(tidyverse) # For ggplot2 and dplyr

── Attaching core tidyverse packages ──────────────────────── tidyverse 2.0.0 ──
✔ dplyr     1.2.0     ✔ readr     2.2.0
✔ forcats   1.0.1     ✔ stringr   1.6.0
✔ ggplot2   4.0.2     ✔ tibble    3.3.1
✔ lubridate 1.9.5     ✔ tidyr     1.3.2
✔ purrr     1.2.1     

── Conflicts ────────────────────────────────────────── tidyverse_conflicts() ──
✖ dplyr::filter() masks stats::filter()
✖ dplyr::lag()    masks stats::lag()
ℹ Use the conflicted package (<http://conflicted.r-lib.org/>) to force all conflicts to become errors

library(gt)       # For generating professional tables
library(palmerpenguins) # For testing our functions with real data

Attaching package: 'palmerpenguins'

The following objects are masked from 'package:datasets':

    penguins, penguins_raw

2.1 The Basics of usethis

Historically, setting up an R package meant manually creating specific folders (R/, man/), writing a strictly formatted DESCRIPTION file, and managing a NAMESPACE. It was tedious and frustrating.

The usethis package automates all of this boilerplate work. It sets up the exact directory structure R expects.

To create a new package, you simply use the create_package() function.

# Create a new package called "vizwizard" on your desktop
usethis::create_package("~/Desktop/vizwizard")

Running this will open a brand new RStudio session. Take a look at the Files pane—you’ll see a DESCRIPTION file (which holds metadata about your package) and an R/ folder.

The R/ folder is where all your custom functions will live. We never create R scripts manually in a package. Instead, we use use_r() to generate them properly.

# Create a script to hold our plotting functions
usethis::use_r("plots")

# Create a script to hold our table functions
usethis::use_r("tables")

2.2 Writing a Plotting Function

The Problem: Functions and ggplot2

Let’s say you want to write a function that takes a dataset and plots a histogram of a specific variable. A naive approach might look like this:

# THIS WILL NOT WORK!
bad_histogram <- function(data, my_variable) {
  ggplot(data, aes(x = my_variable)) +
    geom_histogram()
}

If you try to run bad_histogram(penguins, flipper_length_mm), R will throw an error saying object ‘flipper_length_mm’ not found.

Why? Because R is looking for a standalone object named flipper_length_mm in your global environment, rather than looking inside the penguins dataset. Standard ggplot2 functions know how to look inside the dataframe, but our custom function doesn’t automatically pass that behavior along.

2.3 The Solution: Tidy Evaluation and {{ }}

To solve this, we use something called Tidy Evaluation, specifically the “curly-curly” operator: {{ }}.

Wrapping our variable arguments in {{ }} tells R: “Don’t evaluate this right now. Wait until you are inside the ggplot2 or dplyr function, and then evaluate it in the context of the provided dataframe.”

Let’s write a proper function inside our new R/plots.R file. We will create a standardized, publication-ready histogram.

#' Create a Publication-Ready Histogram
#'
#' @param data A dataframe
#' @param var A numeric variable to plot (unquoted)
#' @param title A string for the plot title
#' @return A ggplot object
#' @export
pub_histogram <- function(data, var, title = "Histogram") {
  
  # Notice the curly-curly around 'var'
  ggplot(data, aes(x = {{ var }})) +
    geom_histogram(fill = "#2c3e50", color = "white", bins = 30) +
    theme_classic(base_size = 14) +
    theme(
      plot.title = element_text(face = "bold", hjust = 0.5),
      axis.title = element_text(face = "bold"),
      panel.grid.major.y = element_line(color = "grey90", linetype = "dashed")
    ) +
    labs(title = title, y = "Count")
}

Let’s test it out using our penguins dataset to see if our custom styling is applied automatically!

# Test our new function
pub_histogram(penguins, flipper_length_mm, "Penguin Flipper Lengths")

Warning: Removed 2 rows containing non-finite outside the scale range
(`stat_bin()`).

2.4 Writing a Professional Table Function

The same {{ }} rules apply when writing wrappers for dplyr pipelines and gt tables.

Let’s write a function for R/tables.R. We want to take any dataset, group it by a categorical variable, summarize a numeric variable (getting the Mean, SD, and Count), and output a clean, styled HTML table using the gt package.

#' Create a Summary Statistics Table
#'
#' @param data A dataframe
#' @param group_var A categorical variable to group by (unquoted)
#' @param sum_var A numeric variable to summarize (unquoted)
#' @return A gt table object
#' @export
pub_summary_table <- function(data, group_var, sum_var) {
  
  data %>% 
    # Remove NAs specifically for the columns we care about
    drop_na({{ group_var }}, {{ sum_var }}) %>% 
    group_by({{ group_var }}) %>% 
    summarize(
      Mean = mean({{ sum_var }}),
      SD = sd({{ sum_var }}),
      N = n()
    ) %>% 
    # Pass the summarized data into gt()
    gt() %>% 
    tab_header(
      title = md("**Summary Statistics**")
    ) %>% 
    fmt_number(
      columns = c(Mean, SD),
      decimals = 2
    ) %>% 
    # Apply a built-in clean theme
    opt_stylize(style = 1, color = "blue")
}

Let’s test our table function to quickly summarize penguin body mass by species!

pub_summary_table(penguins, species, body_mass_g)

2.5 Practice

Your Turn: Custom Scatterplot

Write a function called pub_scatter that takes a dataset, an x variable, a y variable, and a color variable, and returns a cleanly formatted scatterplot.

#' Create a Publication-Ready Scatterplot
#'
#' @param data A dataframe
#' @param x_var The variable for the x-axis (unquoted)
#' @param y_var The variable for the y-axis (unquoted)
#' @param color_var The variable to color points by (unquoted)
#' @return A ggplot object
#' @export
pub_scatter <- function(data, x_var, y_var, color_var) {
  
  ggplot(data, aes(x = {{ x_var }}, y = {{ y_var }}, color = {{ color_var }})) +
    geom_point(size = 3, alpha = 0.8) +
    theme_minimal(base_size = 14) +
    theme(
      legend.position = "bottom",
      plot.title = element_text(face = "bold")
    ) +
    scale_color_viridis_d() # Use a colorblind friendly palette
}

# Test it out
pub_scatter(penguins, flipper_length_mm, body_mass_g, species) +
  labs(title = "Penguin Size by Species")

Warning: Removed 2 rows containing missing values or values outside the scale range
(`geom_point()`).

The “Metadata”: DESCRIPTION, Documentation, and NAMESPACE Writing the functions is only half the battle. To make your code a true R package, R needs to know some metadata: what the package is called, who wrote it, what other packages it relies on, and how users can get help.

The DESCRIPTION File

When we ran usethis::create_package(), it automatically generated a file called DESCRIPTION in our project directory. If you click on it in the Files pane, it looks something like this:

Package: vizwizard Title: What the Package Does (One Line, Title Case) Version: 0.0.0.9000 Authors@R: person(“First”, “Last”, , “first.last@example.com”, role = c(“aut”, “cre”), comment = c(ORCID = “YOUR-ORCID-ID”)) Description: What the package does (one paragraph). License: use_mit_license(), use_gpl3_license() or friends to pick a license Encoding: UTF-8 Roxygen: list(markdown = TRUE) RoxygenNote: 7.2.3

This is the ID card of your package. As a package developer, you should fill out the Title, update the Authors@R with your own information, and write a brief Description.

2.6 Handling Dependencies

Our custom functions use ggplot2, dplyr, and gt. If a colleague installs vizwizard, R needs to know to install those packages for them, too.

A golden rule of package development: never type package names into the DESCRIPTION file manually. It is too easy to make a typo or format it incorrectly. Instead, let usethis do the heavy lifting safely:

# Run these directly in your console to add dependencies to your DESCRIPTION file
usethis::use_package("ggplot2")
usethis::use_package("dplyr")
usethis::use_package("gt")

you check your DESCRIPTION file now, you’ll see a new Imports: section listing these packages!

Generating Manual (man/) Files with roxygen2

Whenever you get stuck in R, what do you do? You type ?function_name into the console to pull up the help file. Those help files live in the man/ (manual) folder of a package.

Historically, writing these .Rd (R documentation) files was a nightmare of custom formatting. Today, we use the roxygen2 package to make it incredibly easy.

If you look back at our pub_histogram and pub_summary_table functions from earlier, you’ll notice I snuck in some special comments starting with #’ right above the code:

#' Create a Publication-Ready Histogram
#'
#' @param data A dataframe
#' @param var A numeric variable to plot (unquoted)
#' @param title A string for the plot title
#' @return A ggplot object
#' @export

These are roxygen comments!

@param defines the arguments your function takes.

@return explains what the function outputs.

@export is crucial: it tells R to make this function available to the public when they run library(vizwizard). Without it, the function is “internal” and hidden from the user.

added headers and backticks ### Putting it all together: devtools::document()

Right now, those are just comments in a script. To actually generate the help files and update our package’s metadata, we run one magical command in the console:

# Translates your #' comments into actual help files!
devtools::document()

When you run this, two amazing things happen:

The man/ folder is populated: You will see files like pub_histogram.Rd appear in your file directory. You can now type ?pub_histogram into your console to see your very own custom help page!

The NAMESPACE file is updated: This file acts as the “border control” of your package, explicitly listing which functions are @exported for public use. Just like the dependencies, never edit the NAMESPACE file by hand. Let devtools::document() handle it.

2.7 Bonus Practice: The “Jitter” Boxplot

Boxplots are great, but showing the raw data points on top of them is even better for transparency.

Write a function called pub_boxplot that takes a dataset, a categorical variable for the x-axis, and a numeric variable for the y-axis. It should return a cleanly formatted boxplot with the raw data points overlaid as a “jitter” plot.

#' Create a Publication-Ready Boxplot with Jittered Points
#'
#' @param data A dataframe
#' @param cat_var A categorical variable for the x-axis (unquoted)
#' @param num_var A numeric variable for the y-axis (unquoted)
#' @return A ggplot object
#' @export
pub_boxplot <- function(data, cat_var, num_var) {
  
  ggplot(data, aes(x = {{ cat_var }}, y = {{ num_var }}, fill = {{ cat_var }})) +
    # Add the boxplot, making the outliers invisible since we are plotting raw points anyway
    geom_boxplot(outlier.shape = NA, alpha = 0.7) +
    # Add the raw data points, slightly jittered so they don't overlap perfectly
    geom_jitter(width = 0.2, alpha = 0.5, color = "black") +
    theme_minimal(base_size = 14) +
    theme(
      legend.position = "none", # Hide the legend since the x-axis already labels the groups
      plot.title = element_text(face = "bold"),
      panel.grid.major.x = element_blank() # Clean up vertical grid lines
    ) +
    scale_fill_viridis_d(option = "mako") # Use a clean, colorblind-friendly palette
}

# Test it out
pub_boxplot(penguins, species, bill_length_mm) +
  labs(
    title = "Penguin Bill Length by Species",
    x = "Species",
    y = "Bill Length (mm)"
  )

Warning: Removed 2 rows containing non-finite outside the scale range
(`stat_boxplot()`).

Warning: Removed 2 rows containing missing values or values outside the scale range
(`geom_point()`).

2.1 General syntax

The general syntax of a function is like this:

name_of_function <- function(arguments) {
  insert_code_here()
}

You can pass multiple arguments to a function, but we are going to start simply with a function that takes one argument.

2.2 Functions with one argument

Here, I am writing a little function to do something simple, like calculate from millimeters to inches.

mm_to_inch <- function(value_in_mm) {
  value_in_mm * 0.0393701 # code to convert from mm to inch
}

Here, we would call value_in_mm our argument or parameter. Remember that this is a user-defined term, you could call this x, i, or really whatever you want. I like giving the arguments easy-to-read and easy-to-remember names.

Now that we’ve made a function, we can see it in our environment under the “Functions” header.

If we click on this item, we can see the details of the function.

If we start typing our function, and put our cursor between the parentheses and press tab, we can also see some information about our function.

We can now pass arguments to our new function, here we will try passing 100 mm and see what that would be in inches.

mm_to_inch(value_in_mm = 100)

[1] 3.93701

Because our function only takes one argument, we can be less explicit and remove value_in_mm and get the same result.

mm_to_inch(100)

[1] 3.93701

We also might want to pass a whole column or vector to our function, which we can also do.

mm_to_inch(penguins$bill_length_mm)

  [1] 1.539371 1.555119 1.586615       NA 1.444883 1.547245 1.531497 1.543308
  [9] 1.342520 1.653544 1.488190 1.488190 1.618111 1.519686 1.362205 1.440946
 [17] 1.523623 1.673229 1.354331 1.811025 1.488190 1.484253 1.413387 1.503938
 [25] 1.527560 1.389765 1.598426 1.594489 1.492127 1.594489 1.555119 1.464568
 [33] 1.555119 1.610237 1.433072 1.543308 1.527560 1.661418 1.480316 1.566930
 [41] 1.437009 1.606300 1.417324 1.736221 1.456694 1.559056 1.618111 1.476379
 [49] 1.417324 1.665355 1.559056 1.578741 1.377953 1.653544 1.358268 1.629922
 [57] 1.535434 1.598426 1.437009 1.480316 1.405513 1.625985 1.480316 1.618111
 [65] 1.433072 1.637796 1.397639 1.618111 1.413387 1.645670 1.318898 1.562993
 [73] 1.559056 1.803151 1.397639 1.685040 1.610237 1.464568 1.425198 1.657481
 [81] 1.362205 1.688977 1.444883 1.381891 1.468505 1.625985 1.429135 1.452757
 [89] 1.507875 1.531497 1.405513 1.618111 1.338583 1.559056 1.425198 1.606300
 [97] 1.500001 1.586615 1.303150 1.700788 1.377953 1.614174 1.484253 1.488190
[105] 1.492127 1.562993 1.519686 1.503938 1.500001 1.700788 1.500001 1.795277
[113] 1.562993 1.661418 1.559056 1.681103 1.519686 1.468505 1.405513 1.618111
[121] 1.425198 1.484253 1.582678 1.629922 1.385828 1.598426 1.527560 1.633859
[129] 1.535434 1.736221 1.515749 1.696851 1.448820 1.476379 1.500001 1.618111
[137] 1.401576 1.582678 1.456694 1.562993 1.582678 1.598426 1.263780 1.602363
[145] 1.468505 1.535434 1.543308 1.440946 1.417324 1.488190 1.417324 1.633859
[153] 1.814962 1.968505 1.917324 1.968505 1.874017 1.830710 1.787403 1.838584
[161] 1.704725 1.842521 1.610237 1.929135 1.791340 1.905513 1.803151 1.940946
[169] 1.653544 1.937009 1.818899 1.917324 1.976379 1.775592 1.830710 1.822836
[177] 1.688977 1.814962 1.751969 1.881891 1.897639 1.968505 1.862206 1.685040
[185] 1.775592 2.346458 1.933072 1.905513 1.677166 1.748032 1.732284 1.917324
[193] 1.681103 1.952757 1.783466 1.952757 1.988190 1.716536 1.791340 1.988190
[201] 1.767717 1.779529 1.834647 1.909450 1.775592 1.972442 1.830710 1.771654
[209] 1.724410 1.791340 1.700788 1.984253 1.783466 1.818899 1.799214 2.137796
[217] 1.803151 1.960631 1.818899 1.948820 1.712599 1.996064 1.877954 1.826773
[225] 1.897639 1.830710 1.826773 1.913387 1.870080 2.011812 1.779529 1.779529
[233] 1.933072 2.066930 1.866143 1.968505 1.767717 2.000001 1.708662 2.019686
[241] 1.870080 2.051182 1.870080 2.055119 1.791340 1.948820 1.751969 2.000001
[249] 1.944883 1.846458 1.905513 2.011812 1.909450 2.200789 1.858269 1.933072
[257] 1.862206 1.842521 1.641733 2.102363 1.704725 1.893702 1.988190 1.960631
[265] 1.712599 2.027560 1.818899 2.169293 1.751969 1.921261 1.858269       NA
[273] 1.842521 1.984253 1.779529 1.964568 1.830710 1.968505 2.019686 1.787403
[281] 2.074804 1.779529 1.814962 2.019686 1.811025 2.019686 1.834647 2.035434
[289] 1.850395 2.047245 1.807088 1.988190 1.980316 2.283466 1.826773 1.937009
[297] 1.669292 1.909450 1.700788 1.992127 1.838584 2.047245 1.988190 1.948820
[305] 1.826773 2.078741 1.610237 2.133859 1.673229 2.007875 1.956694 1.870080
[313] 1.874017 2.047245 1.846458 2.106300 1.929135 1.818899 2.003938 1.791340
[321] 2.003938 2.000001 1.972442 1.929135 2.027560 1.960631 1.893702 2.023623
[329] 1.799214 1.996064 1.673229 2.055119 1.779529 1.940946 1.976379 1.795277
[337] 2.043308 1.842521 1.799214 2.196852 1.712599 1.952757 2.000001 1.976379

Instead of just printing this information, we might want to save it in our dataframe, which we can do by nesting our function within a mutate() function. Remember that mutate() works with the syntax new_column = function(existing_variables). Also remember that by default, new columns are added after the last column (and if you want to also reorder, you can do that with select()).

penguins |> 
  mutate(bill_length_inch = mm_to_inch(bill_length_mm))

# A tibble: 344 × 9
   species island    bill_length_mm bill_depth_mm flipper_length_mm body_mass_g
   <fct>   <fct>              <dbl>         <dbl>             <int>       <int>
 1 Adelie  Torgersen           39.1          18.7               181        3750
 2 Adelie  Torgersen           39.5          17.4               186        3800
 3 Adelie  Torgersen           40.3          18                 195        3250
 4 Adelie  Torgersen           NA            NA                  NA          NA
 5 Adelie  Torgersen           36.7          19.3               193        3450
 6 Adelie  Torgersen           39.3          20.6               190        3650
 7 Adelie  Torgersen           38.9          17.8               181        3625
 8 Adelie  Torgersen           39.2          19.6               195        4675
 9 Adelie  Torgersen           34.1          18.1               193        3475
10 Adelie  Torgersen           42            20.2               190        4250
# ℹ 334 more rows
# ℹ 3 more variables: sex <fct>, year <int>, bill_length_inch <dbl>

2.3 Embedding built in functions

We can also use other functions inside our function. For example, R does not by default have a function that calculates the coefficient of variation for a variable. We can write that ourselves though so it’s fine.

# calculate the coefficient of variation by 
# dividing the standard deviation by the mean
cv <- function(x) {
        (sd(x)/mean(x))
}

2.4 Functions with two arguments

We can also write functions that take more than one argument. Here is a simple example for calculating BMI, which is weight in kg divided by height in meters squared.

calculate_bmi <- function(weight_kg, height_cm) {
  weight_kg/(height_cm/100)^2
}

calculate_bmi(weight_kg = 80, height_cm = 180)

[1] 24.69136

If you provide your arguments in the order they are expected (here, weight_kg and then height_cm), then you don’t need to specify which is which. But, iif you want to give the arguments in a different order you need to be explicit.

# this is wrong
calculate_bmi(180, 80)

[1] 281.25

# this is better
calculate_bmi(height_cm = 180, weight_kg = 80)

[1] 24.69136

2.5 Functions with one argument practice

Write two functions that convert between degrees Fahrenheit and degrees Celsius and test to see if they work.

# create a function to convert F to C
degF_to_degC <- function(deg_F) {
  (deg_F - 32) * (5/9)
}

# create a function to convert C to F
degC_to_degF <- function(deg_C) {
  (deg_C * (9/5)) + 32
}

degF_to_degC(deg_F = 32)

[1] 0

degF_to_degC(deg_F = 100)

[1] 37.77778

degC_to_degF(deg_C = 0)

[1] 32

degC_to_degF(deg_C = -40)

[1] -40

2.6 Plotting functions

Now that we are a little comfortable with writing functions, we can make ones that are a little more complicated.

We can also write a function to make our plot.

species_bill_plotting <- function(focal_species) {
    penguins |> 
    filter(species == focal_species) |> 
    drop_na() |> 
    ggplot(aes(x = bill_length_mm, y = bill_depth_mm, color = sex)) +
    geom_point() + 
    geom_smooth(method = "lm", # use a linear model
                se = FALSE) + # turn off confidence interval
    scale_color_brewer(palette = "Dark2") +
    labs(title = focal_species, # put the species name as the title
         x = "Bill length (mm)",
         y = "Bill depth (mm)",
         color = "Sex", 
         caption = "Data collected from LTER, Antarctica") + 
    theme_classic() 
}

Then, we can pass our argument to the plot, here, the name of the species we want to plot. This is a useful tool for making many plots with the same structure.

species_bill_plotting("Adelie")

`geom_smooth()` using formula = 'y ~ x'

We can then pass this function in a for loop with some simpler looking code (because the bulk of it is elsewhere).

penguin_species <- unique(penguins$species)

for (focal_species in penguin_species) {
  # pass each focal species to the species_bill_plotting function
  plot <- species_bill_plotting(focal_species)

# save the plots
  filename <- glue("figs/{focal_species}_bill-dimensions.png") # create filename
  ggsave(filename, plot) # save the plot to file
}

Saving 7 x 5 in image
`geom_smooth()` using formula = 'y ~ x'
Saving 7 x 5 in image
`geom_smooth()` using formula = 'y ~ x'
Saving 7 x 5 in image
`geom_smooth()` using formula = 'y ~ x'

2.7 Writing plotting functions practice

Write a function to make a series of boxplots that show the difference in body_mass_g between male and female penguins by species. Feed one species to your function to check if it works (you don’t need to iterate with it yet).

# create the function
body_mass_by_sex_plotting <- function(focal_species) {
    penguins |> 
    filter(species == focal_species) |> 
    drop_na(sex, body_mass_g) |> 
    ggplot(aes(x = sex, y = body_mass_g, color = sex)) +
      geom_boxplot() +
      theme_minimal() +
      scale_color_brewer(palette = "Dark2") +
      theme(legend.position = "none") + # don't need one bc duplicative with x-axis
      labs(x = "Sex",
        y = "Body mass (grams)",
        title = focal_species)
}

# apply the function to Adelie penguins
body_mass_by_sex_plotting("Adelie")

3.1 About lists

A list is a new data structure for Code Club. A list can contain other data structures, like data frames, vectors or others, within it.

To see what a list looks like, we will look under the hood at the object that comprises a ggplot plot. We have one in our environment called plot so let’s look at that.

View(plot)

We can see that in this case, plot is a list which contains 11 objects, many of which also contain sub-objects. For example, data is a dataframe that. contains the data underlying our plot. It is a tibble type of dataframe with 68 rows and 8 columns.

If I want to access that first item in the list, I can do that in a few different ways.

I can use the dollar sign operator $ to extract parts of the list

plot$data

# A tibble: 68 × 8
   species   island bill_length_mm bill_depth_mm flipper_length_mm body_mass_g
   <fct>     <fct>           <dbl>         <dbl>             <int>       <int>
 1 Chinstrap Dream            46.5          17.9               192        3500
 2 Chinstrap Dream            50            19.5               196        3900
 3 Chinstrap Dream            51.3          19.2               193        3650
 4 Chinstrap Dream            45.4          18.7               188        3525
 5 Chinstrap Dream            52.7          19.8               197        3725
 6 Chinstrap Dream            45.2          17.8               198        3950
 7 Chinstrap Dream            46.1          18.2               178        3250
 8 Chinstrap Dream            51.3          18.2               197        3750
 9 Chinstrap Dream            46            18.9               195        4150
10 Chinstrap Dream            51.3          19.9               198        3700
# ℹ 58 more rows
# ℹ 2 more variables: sex <fct>, year <int>

Or, I can use indexing to extract out the first item in our list.

plot[1]

$data
# A tibble: 68 × 8
   species   island bill_length_mm bill_depth_mm flipper_length_mm body_mass_g
   <fct>     <fct>           <dbl>         <dbl>             <int>       <int>
 1 Chinstrap Dream            46.5          17.9               192        3500
 2 Chinstrap Dream            50            19.5               196        3900
 3 Chinstrap Dream            51.3          19.2               193        3650
 4 Chinstrap Dream            45.4          18.7               188        3525
 5 Chinstrap Dream            52.7          19.8               197        3725
 6 Chinstrap Dream            45.2          17.8               198        3950
 7 Chinstrap Dream            46.1          18.2               178        3250
 8 Chinstrap Dream            51.3          18.2               197        3750
 9 Chinstrap Dream            46            18.9               195        4150
10 Chinstrap Dream            51.3          19.9               198        3700
# ℹ 58 more rows
# ℹ 2 more variables: sex <fct>, year <int>

3.2 map()

The simplest of the functions in purrr is map(), which applies a function over each element of a vector, and returns a list. There are some basics we will have to go over for this to make sense.

The map(), we provide a vector/list to iterate over, and a function, like this:

map(.x = 1:5, # our vector to apply our function over
    function(x) x + 1) # what the function is

[[1]]
[1] 2

[[2]]
[1] 3

[[3]]
[1] 4

[[4]]
[1] 5

[[5]]
[1] 6

Now let’s get back to the function we wrote to make our plots - instead of incorporating this into a for loop, we can apply it within map() like this:

map(penguin_species, # vector to iterate over
    species_bill_plotting) # function to use

[[1]]

`geom_smooth()` using formula = 'y ~ x'

[[2]]

`geom_smooth()` using formula = 'y ~ x'

[[3]]

`geom_smooth()` using formula = 'y ~ x'

Wow that was simple!

We could also incorporate both the printing and saving of the plot into one function like this:

species_bill_plotting_saving <- function(focal_species) {
  
# create plot and assign it to something 
  plot_via_function <- penguins |> 
    filter(species == focal_species) |> 
    drop_na() |> 
    ggplot(aes(x = bill_length_mm, y = bill_depth_mm, color = sex)) +
    geom_point() + 
    geom_smooth(method = "lm", # use a linear model
                se = FALSE) + # turn off confidence interval
    scale_color_brewer(palette = "Dark2") +
    labs(title = focal_species, # put the species name as the title
         x = "Bill length (mm)",
         y = "Bill depth (mm)",
         color = "Sex", 
         caption = "Data collected from LTER, Antarctica") + 
    theme_classic() 
  
# print
  print(plot_via_function)
  
# save
  filename <- glue("figs/{focal_species}_bill-dimensions-via-function.png") # choose filename
  ggsave(filename, plot_via_function) # save the plot to file
}

Then, this code will:

1. Generate your plots
2. Print those plots for you to view in RStudio
3. Save those plots in a directory called figs in your working directory

map(penguin_species, # vector to iterate over
    species_bill_plotting_saving) # function to apply

`geom_smooth()` using formula = 'y ~ x'

Saving 7 x 5 in image
`geom_smooth()` using formula = 'y ~ x'
`geom_smooth()` using formula = 'y ~ x'

Saving 7 x 5 in image
`geom_smooth()` using formula = 'y ~ x'
`geom_smooth()` using formula = 'y ~ x'

Saving 7 x 5 in image
`geom_smooth()` using formula = 'y ~ x'

[[1]]
figs/Adelie_bill-dimensions-via-function.png

[[2]]
figs/Gentoo_bill-dimensions-via-function.png

[[3]]
figs/Chinstrap_bill-dimensions-via-function.png

3.3 Functions with more arguments practice

Try applying your function you made to create a series of boxplots for body mass by sex over each of the penguin species, though edit it so it both prints and saves your plots.

species_body_mass_sex_plotting_saving <- function(focal_species) {
  my_plot <- penguins |> 
    filter(species == focal_species) |> 
    drop_na(sex, body_mass_g) |> 
    ggplot(aes(x = sex, y = body_mass_g, color = sex)) +
      geom_boxplot() +
      theme_minimal() +
      scale_color_brewer(palette = "Dark2") +
      theme(legend.position = "none") + # don't need one bc duplicative with x-axis
      labs(x = "Sex",
        y = "Body mass (grams)",
        title = focal_species)

# print
  print(my_plot)
  
# save
  filename <- glue("figs/{focal_species}_body-mass-by-sex.png") # choose filename
  ggsave(filename, my_plot) # save the plot to file
}

map(penguin_species, # what to iterate over
    species_body_mass_sex_plotting_saving) # the function to iterate with

Saving 7 x 5 in image

Saving 7 x 5 in image

Saving 7 x 5 in image

[[1]]
figs/Adelie_body-mass-by-sex.png

[[2]]
figs/Gentoo_body-mass-by-sex.png

[[3]]
figs/Chinstrap_body-mass-by-sex.png

2.1 for loops, the basics

For loops iterate over some kind of sequence, performing an action, one element at a time. The basic syntax is like this:

for (item in list_of_items) { # items to iterate over
  # code that does something
  do_something(item) # this is a made up function
}

Let’s go through a simple example:

for (some_value in 1:5) {
  print(some_value * 2)
}

[1] 2
[1] 4
[1] 6
[1] 8
[1] 10

What is happening under the hood, is that your for loop is assigning each item in your vector (here, the integer values 1 through 5) to the object some_value, multiplying it by 2, and then printing it. If we want to be very explicit, this is exactly what is happening:

# iteration 1
some_value <- 1
print(some_value * 2)

[1] 2

# iteration 2
some_value <- 2
print(some_value * 2)

[1] 4

# iteration 3
some_value <- 3
print(some_value * 2)

[1] 6

# iteration 4
some_value <- 4
print(some_value * 2)

[1] 8

# iteration 5
some_value <- 5
print(some_value * 2)

[1] 10

If we do this again in the loop:

for (some_value in 1:5) {
  print(some_value * 2)
}

[1] 2
[1] 4
[1] 6
[1] 8
[1] 10

And check what some_value is at the end:

some_value

[1] 5

We can see that the value 5 (last of some_value) is currently assigned. This is not totally intuitive - you might think that some_value would hold all of the values that we set to that object in our loop but this is not true. This is good to remember since this is now an object lingering in our environment.

I have shown this use-case of a for loop because I think it helps you to see how it works - not because you would actually use it to do this task. Because R is a vectorized language, you don’t actually need a for loop to multiply every value by a number, we can do this task more simply below.

# multiply each element of the vector 1:5 by 2
1:5 * 2

[1]  2  4  6  8 10

Let’s do another example. I could create a for loop that simply prints something out for me. Here’s an example:

# create a vector of the names of my special flowers
my_special_flowers <- c("dahlias", "roses", "ranunculus")

# use a for loop to print this message for each flower
for (flower in my_special_flowers) {
  print(glue("I really like {flower}"))
}

I really like dahlias
I really like roses
I really like ranunculus

You can also make this conditional, meaning your for loop does one thing under certain conditions, and something else in another condition. We can accomplish this by nesting an if else statement within our for loop.

We are also making use of the function glue() (which we’ve gone over before) which allows easy pasting, like this:

my_location <- "Code Club"
glue("Welcome to {my_location}")

Welcome to Code Club

# a vector of solanaceous vegetables
my_vegetables <- c("Tomato", "Potato", "Pepper", "Eggplant")

for (vegetable in my_vegetables) {
# if the vegetable is tomato, print this message  
  if (vegetable == "Tomato") {
    print(glue("{vegetable} is my favorite Solanaceae vegetable"))
  }
# if the vegetable is anything else, print this message  
  else {
    print(glue("{vegetable} is a perfectly fine Solanaceae vegetable"))
  }
}

Tomato is my favorite Solanaceae vegetable
Potato is a perfectly fine Solanaceae vegetable
Pepper is a perfectly fine Solanaceae vegetable
Eggplant is a perfectly fine Solanaceae vegetable

2.2 for loops basics practice

Write a for loop that takes the vector of numbers -5, -3, 2, 4, 7 and prints their absolute value.

# create your vector of numbers to iterate over
my_vector <- c(-5, -3, 2, 4, 7)

# use a for loop to do the iterating
for (number in my_vector) {
  print(abs(number))
}

[1] 5
[1] 3
[1] 2
[1] 4
[1] 7

Write a for loop that, when given a number, will tell you whether an positive integer is odd or even. Don’t worry about negatives or zero here.

some_integers <- c(1, 5, 12, 401, 1000)

for (number in some_integers) {
# if the number is divisible by 2, print that its even 
  if (number %% 2 == 0) {
    print(glue("{number} is an even number"))
  }
# if the number is anything else, print that its odd 
  else {
    print(glue("{number} is an odd number"))
  }
}

1 is an odd number
5 is an odd number
12 is an even number
401 is an odd number
1000 is an even number

2.3 for loops, for plotting

So far, we have done things in a for loop do not really require a for loop to accomplish, though I want you to see how they work first with simpler examples. Making a bunch of plots at once is something that is really easier and less error prone with a for loop.

First let’s revisit our penguins data to create a base plot, and then iterate it over a variable to make multiples.

glimpse(penguins)

Rows: 344
Columns: 8
$ species           <fct> Adelie, Adelie, Adelie, Adelie, Adelie, Adelie, Adel…
$ island            <fct> Torgersen, Torgersen, Torgersen, Torgersen, Torgerse…
$ bill_length_mm    <dbl> 39.1, 39.5, 40.3, NA, 36.7, 39.3, 38.9, 39.2, 34.1, …
$ bill_depth_mm     <dbl> 18.7, 17.4, 18.0, NA, 19.3, 20.6, 17.8, 19.6, 18.1, …
$ flipper_length_mm <int> 181, 186, 195, NA, 193, 190, 181, 195, 193, 190, 186…
$ body_mass_g       <int> 3750, 3800, 3250, NA, 3450, 3650, 3625, 4675, 3475, …
$ sex               <fct> male, female, female, NA, female, male, female, male…
$ year              <int> 2007, 2007, 2007, 2007, 2007, 2007, 2007, 2007, 2007…

What if we want to create a plot comparing the bill_length_mm vs. bill_depth_mm for each species? We can:

• take our penguins data
• filter() for a single species
• make our plot

penguins |> 
# select only the Adelie penguins  
  filter(species == "Adelie") |> 
# remove missing values for our variables of interest  
  drop_na(bill_length_mm, bill_depth_mm, sex) |> 
  ggplot(aes(x = bill_length_mm, y = bill_depth_mm, color = sex)) +
    geom_point() + 
    geom_smooth(method = "lm", # use a linear model
                se = FALSE) + # turn off confidence interval
    scale_color_brewer(palette = "Dark2") +
    labs(title = "Adelie", # put the species name as the title
         x = "Bill length (mm)",
         y = "Bill depth (mm)",
         color = "Sex") +
    theme_classic() 

`geom_smooth()` using formula = 'y ~ x'

Now we have a plot, if we want to create one per species (in this case there are 3), we can use a for loop to do this.

# create a vector that has all the penguin species names
penguin_species <- unique(penguins$species)

# use a for loop to iterate over the penguin species
for (focal_species in penguin_species) {
# filter your df for each focal_species  
  one_penguin_species <- penguins |> 
    filter(species == focal_species) |> 
    drop_na(bill_length_mm, bill_depth_mm, sex) 
  
# plot
  plot <- one_penguin_species |>   
    ggplot(aes(x = bill_length_mm, y = bill_depth_mm, color = sex)) +
    geom_point() + 
    geom_smooth(method = "lm", # use a linear model
                se = FALSE) + # turn off confidence interval
    scale_color_brewer(palette = "Dark2") +
    labs(title = focal_species, # put the species name as the title
         x = "Bill length (mm)",
         y = "Bill depth (mm)",
         color = "Sex") +
    theme_classic() 

# print the plot
  print(plot)
}

We can also add to our for loop to save the plots in a location of our choosing. We can start by creating a new directory (in your working directory) called figs which is where we will store our figures.

# write code to create a directory called "figs" in our working directory
dir.create(path = "figs")

Instead of printing the plot, we are going to save it.

for (focal_species in penguin_species) {
# filter your df for each focal_species  
  one_penguin_species <- penguins |> 
    filter(species == focal_species) |> 
    drop_na(bill_length_mm, bill_depth_mm, sex) 
  
# plot
  plot <- one_penguin_species |>   
    ggplot(aes(x = bill_length_mm, y = bill_depth_mm, color = sex)) +
    geom_point() + 
    geom_smooth(method = "lm", # use a linear model
                se = FALSE) + # turn off confidence interval
    scale_color_brewer(palette = "Dark2") +
    labs(title = focal_species, # put the species name as the title
         x = "Bill length (mm)",
         y = "Bill depth (mm)",
         color = "Sex") +
    theme_classic() 

# save the plots
  filename <- glue("figs/{focal_species}_bill-dimensions.png") # create filename
  ggsave(filename = filename, 
         plot = plot) # save the plot to file
}

Saving 7 x 5 in image
`geom_smooth()` using formula = 'y ~ x'
Saving 7 x 5 in image
`geom_smooth()` using formula = 'y ~ x'
Saving 7 x 5 in image
`geom_smooth()` using formula = 'y ~ x'

Now time to practice.

2.4 for loops, for plotting practice

Write a for loop to make a series of boxplots that show the difference in body_mass_g between male and female penguins by species. Try both printing and saving the plots.

penguins |> 
  filter(species == "Adelie") |> 
  drop_na(body_mass_g, sex) |> 
  ggplot(aes(x = sex, y = body_mass_g, color = sex)) +
  geom_boxplot() +
  theme_minimal() +
  theme(legend.position = "none") + # don't need one bc duplicative with x-axis
  labs(x = "Sex",
        y = "Body mass (grams)",
        title = "Adelie")

for (focal_species in penguin_species) {
# filter your df for each focal_species  
  one_penguin_species <- penguins |> 
    filter(species == focal_species) |> 
    drop_na(bill_length_mm, bill_depth_mm, sex) 
  
# plot
  plot <- one_penguin_species |>   
    ggplot(aes(x = sex, y = body_mass_g, color = sex)) +
      geom_boxplot() +
      theme_minimal() +
      scale_color_brewer(palette = "Dark2") +
      theme(legend.position = "none") + # don't need one bc duplicative with x-axis
      labs(x = "Sex",
        y = "Body mass (grams)",
        title = "Adelie")

# print the plots  
  print(plot)

# save the plots
  filename <- glue("figs/{focal_species}_body-mass-by-sex.png") # create filename
  ggsave(filename = filename, 
         plot = plot) # save the plot to file
}

Saving 7 x 5 in image

Saving 7 x 5 in image

Saving 7 x 5 in image

1.1 What we’ll cover

Today, we’ll continue on the topic of preparing your plots for publication. Specifically, we’ll cover:

• Saving plots to file – with ggplot’s ggsave() (moved from last weeksince we didn’t get there)

• Advanced text formatting with ggtext. For example, italicizing individual words in axis titles and legends.

• Adding any kind of image to a plot, including:

  • An image inside a plot
  • A plot of an image in a multi-panel layout

1.2 Setup

library(tidyverse)

Warning: package 'ggplot2' was built under R version 4.5.2

Warning: package 'tidyr' was built under R version 4.5.2

── Attaching core tidyverse packages ──────────────────────── tidyverse 2.0.0 ──
✔ dplyr     1.1.4     ✔ readr     2.1.5
✔ forcats   1.0.1     ✔ stringr   1.6.0
✔ ggplot2   4.0.1     ✔ tibble    3.3.0
✔ lubridate 1.9.4     ✔ tidyr     1.3.2
✔ purrr     1.2.0     
── Conflicts ────────────────────────────────────────── tidyverse_conflicts() ──
✖ dplyr::filter() masks stats::filter()
✖ dplyr::lag()    masks stats::lag()
ℹ Use the conflicted package (<http://conflicted.r-lib.org/>) to force all conflicts to become errors

library(palmerpenguins)

Attaching package: 'palmerpenguins'

The following objects are masked from 'package:datasets':

    penguins, penguins_raw

library(patchwork)

theme_set(theme_classic(base_size = 13))
theme_update(
  panel.grid.major.y = element_line(color = "grey70", linewidth = 0.2)
)

p <- penguins |>
  drop_na() |> # Get rid of rows with NAs
  ggplot(aes(x = flipper_length_mm, y = body_mass_g)) +
  geom_point(aes(fill = species), shape = 21, size = 2) +
  scale_fill_brewer(palette = "Dark2") +
  scale_y_continuous(labels = scales::label_comma()) +
  labs(x = "Flipper length (mm)", y = "Body mass (g)")

p

2.1 Basic usage

Tell ggsave() about the filename and the plot you want to save:

ggsave(filename = "plot.png", plot = p)

Saving 7 x 5 in image

• The file type is determined by the extension you provide. Above, we used .png i.e. a PNG file, but there are other options, as we’ll see in a bit.

• We did not specify the width and height of the figure above, so it reports saving it to a default size of 7 × 5 inches.

ggsave(filename = "plot.png")

# Save to a "figures" subfolder in the current working directory:
ggsave(filename = "figures/plot.png", plot = p)

# Save to a specific folder on your computer:
ggsave(filename = "C:/Users/YourName/Documents/figures/plot.png", plot = p)

2.2 Controlling figure size

ggsave() accepts width and height arguments, with a default unit of inches¹:

ggsave(filename = "wide.png", plot = p, width = 6, height = 4)

The figure’s size may not seem to matter much, because you could always resize the figure on the computer, right? In fact, what does an inch even mean in the context of a figure displayed on a screen?

But these dimensions are important when considering the figure’s aspect ratio and the relative text size.

ggsave(filename = "tall.png", plot = p, width = 4, height = 6)

# "Small" figure — text will look relatively large
ggsave(filename = "small.png", plot = p, width = 4.5, height = 3)

# "Large" figure — text will look relatively small
ggsave(filename = "large.png", plot = p, width = 9, height = 6)

2.3 Raster vs. vector formats

When saving a figure, you have two fundamentally different types of format to choose from:

• Raster formats (PNG, JPEG, TIFF) store the image as a grid of pixels.
  Quality is fixed at save time using the figure’s “resolution” — but zoom in far enough and you’ll see pixelation. Among these formats, TIFF is generally preferred for scientific publications while PNG may also work, while JPEG should typically be avoided.

• Vector formats (SVG, PDF) store the image as geometric instructions — lines, curves, text.
  They render sharply at any size, and text is selectable and searchable. Among these formats, SVG is generally preferred or scientific publications.

For publication, vector formats are generally preferable when the journal accepts them. Figures will be crisp at any print size, and editors or co-authors can make minor tweaks in a vector editor such as InkScape or Illustrator.

To save to SVG format, we need the svglite package – let’s install that:

install.packages("svglite")
# (We don't need to load it with library() because ggsave() will use it 
#  automatically when we save to SVG)

As mentioned above, the filetype is simply specified in ggsave() using the file extension. Earlier, we saved to PNG, so let’s now practice saving to SVG:

ggsave(filename = "large.svg", plot = p, width = 9, height = 6)

ggsave(
  filename = "large_dpi300.png",
  plot = p,
  width = 6,
  height = 4,
  dpi = 300
  )

4.1 An image inside a plot

I think this is most easily done with the cowplot package, which has a draw_image() function to add images to ggplots. Install cowplot if you don’t have it already, then load it:

install.packages("cowplot")

library(cowplot)

Attaching package: 'cowplot'

The following object is masked from 'package:patchwork':

    align_plots

The following object is masked from 'package:lubridate':

    stamp

Now, we can add the image to our plot with ggdraw() and draw_image(), where:

• The x and y arguments specify the position of the image in the plot (between 0 and 1), with x being the left-most position and y being the bottom-most position. These are not the same as the x and y axes of the plot, but rather the position of the image relative to the plot area.

• The height and width arguments specify the size of the image relative to the plot (between 0 and 1). One thing to note is that the aspect ratio of the image is preserved, so even if you specify a square image like we do below, the actual image may not be square if the original image is not square. While it may seem odd in that case to specify both width and height, when omitting one of these, the function somehow has strange behavior with respect to the x and y coordinates. 🤷‍♂️

ggdraw(p) +
  draw_image("3penguins.png", x = 0.1, y = 0.65, height = 0.35, width = 0.35)

4.2 An example with multiple images

Say that we wanted to add a separate image for each penguin species in an appopriate part of the plot. First, download the following penguin images:

adelie_img_url <- "https://raw.githubusercontent.com/osu-codeclub/osu-codeclub.github.io/main/posts/S11E06_ggplot_06/adelie.png"
chinstrap_img_url <- "https://raw.githubusercontent.com/osu-codeclub/osu-codeclub.github.io/main/posts/S11E06_ggplot_06/chinstrap.png"
gentoo_img_url <- "https://raw.githubusercontent.com/osu-codeclub/osu-codeclub.github.io/main/posts/S11E06_ggplot_06/gentoo.png"

download.file(url = adelie_img_url, destfile = "adelie.png")
download.file(url = chinstrap_img_url, destfile = "chinstrap.png")
download.file(url = gentoo_img_url, destfile = "gentoo.png")

And add them to the plot:

ggdraw(p) +
  draw_image("adelie.png", x = 0.2, y = 0.6, height = 0.15, width = 0.15) +
  draw_image("chinstrap.png", x = 0.5, y = 0.25, height = 0.15, width = 0.15) +
  draw_image("gentoo.png", x = 0.4, y = 0.8, height = 0.15, width = 0.15)

p <- penguins |>
  drop_na() |>
  ggplot(aes(x = species, y = body_mass_g)) +
  geom_boxplot() +
  scale_y_continuous(
    labels = scales::label_comma(),
    # Manually specify the upper axis limitsand breaks to make room for the image
    limits = c(NA, 6800),
    breaks = seq(3000, 6000, by = 1000)
    ) +
  labs(x = NULL, y = "Body mass (g)")

ggdraw(p) +
  draw_image("adelie.png",    x = 0.20, y = 0.85, height = 0.15, width = 0.15) +
  draw_image("chinstrap.png", x = 0.48, y = 0.85, height = 0.15, width = 0.15) +
  draw_image("gentoo.png",    x = 0.75, y = 0.85, height = 0.15, width = 0.15)

p <- penguins |>
  drop_na() |>
  ggplot(aes(x = species, y = body_mass_g)) +
  geom_boxplot() +
  scale_y_continuous(labels = scales::label_comma()) +
  labs(x = NULL, y = "Body mass (g)") +
  theme(
    plot.margin = margin(t = 5, r = 5, b = 60, l = 5), # extra bottom margin
    )  

ggdraw(p) +
  draw_image("adelie.png",    x = 0.20, y = -0.01, height = 0.15, width = 0.15) +
  draw_image("chinstrap.png", x = 0.48, y = -0.01, height = 0.15, width = 0.15) +
  draw_image("gentoo.png",    x = 0.75, y = -0.01, height = 0.15, width = 0.15)

# Setting the image width as a variables
width <- 0.35

# Read in the image
raw <- readPNG("3penguins.png")
img <- rasterGrob(raw, width = unit(1, "npc"), height = unit(1, "npc"))

# Obtain the image's aspect ratio and compute the height from that:
# This is necessary because we need to specify the coordinates of all corners
# of the image when using inset_element(), and we want the aspect ratio to be correct.
aspect_ratio <- dim(raw)[1] / dim(raw)[2]
height <- width * aspect_ratio

# Create the plot with the inserted image
# (Setting the plot panel's aspect ratio to 1 seems necessary for the image's
#  aspect ratio to be correctly displayed.)
p +
  theme(aspect.ratio = 1) +
  inset_element(img, right = 0.4, left = 0.4 - width, top = 1, bottom = 1 - height)

# Set the width and save the desired box colors
width <- 0.15
colors <- RColorBrewer::brewer.pal(n = 8, name = "Dark2")

# Adelie
raw_ade <- readPNG("adelie.png")
img_ade <- rasterGrob(raw_ade, width = unit(1, "npc"), height = unit(1, "npc"))
aspect_ade <- dim(raw_ade)[1] / dim(raw_ade)[2]
ht_ade <- width * aspect_ade
box_ade <- ggplot() +
  theme_void() +
  theme(panel.border = element_rect(fill = NA, color = colors[1], linewidth = 2))

# Chinstrap
raw_chi <- readPNG("chinstrap.png")
img_chi <- rasterGrob(raw_chi, width = unit(1, "npc"), height = unit(1, "npc"))
aspect_chi <- dim(raw_chi)[1] / dim(raw_chi)[2]
ht_chi <- width * aspect_chi
box_chi <- ggplot() +
  theme_void() +
  theme(panel.border = element_rect(fill = NA, color = colors[2], linewidth = 2))

# Gentoo
raw_gen <- readPNG("gentoo.png")
img_gen <- rasterGrob(raw_gen, width = unit(1, "npc"), height = unit(1, "npc"))
aspect_gen <- dim(raw_gen)[1] / dim(raw_gen)[2]
ht_gen <- width * aspect_gen
box_gen <- ggplot() +
  theme_void() +
  theme(panel.border = element_rect(fill = NA, color = colors[3], linewidth = 2))

p +
  theme(aspect.ratio = 1) +
  inset_element(img_ade, right = 0.2, left = 0.2 - width, top = 0.6, bottom = 0.6 - ht_ade) +
  inset_element(box_ade, right = 0.2, left = 0.2 - width, top = 0.6, bottom = 0.6 - ht_ade) +
  inset_element(img_chi, right = 0.7, left = 0.7 - width, top = 0.3, bottom = 0.3 - ht_chi) +
  inset_element(box_chi, right = 0.7, left = 0.7 - width, top = 0.3, bottom = 0.3 - ht_chi) +
  inset_element(img_gen, right = 0.6, left = 0.6 - width, top = 0.9, bottom = 0.9 - ht_gen) +
  inset_element(box_gen, right = 0.6, left = 0.6 - width, top = 0.9, bottom = 0.9 - ht_gen)

4.3 An image in a multi-panel layout

Now, let’s explore adding an image to a multi-panel layout, so basically treating the image as just another plot in the layout.

For that, we’ll start with the same three-panel layout as in the previous session:

p_scatter <- penguins |> 
  drop_na() |>
  ggplot(aes(x = bill_length_mm, y = bill_depth_mm)) +
  geom_point() +
  facet_wrap(vars(species))
p_bar <- penguins |> 
  ggplot(aes(x = island)) +
  geom_bar()
p_box <- penguins |> 
  drop_na() |> 
  ggplot(aes(x = sex, y = body_mass_g)) +
  geom_boxplot()

p_scatter / (p_bar | p_box)

As a first step in including the penguin image, we’ll read it in as a graphical object with readPNG() and rasterGrob():

img <- rasterGrob(readPNG("3penguins.png"))

Next, we can add the image to the layout with patchwork’s wrap_elements() function:

# Store the image as a plot element with wrap_elements():
p_img <- wrap_elements(panel = img)

# Add the image to the layout with patchwork syntax:
(p_scatter + p_img) / (p_bar | p_box)

Above, the plot with the image is quite small, and this is because the image is being resized to fit the plot panel (that is, the area inside the axes of a plot). Note that it’s taking up the entire plot panel height, but because the image has a 1:1 aspect ratio, it is not taking up the entire plot panel width. While that makes it appear even smaller, it’s a good thing that the image’s aspect ratio is respected, or the image would look stretched.

Alternatively, we can tell wrap_elements() to use the entire plot area for the image with plot = (above, we used panel =):

p_img_big <- wrap_elements(plot = img)
(p_scatter + p_img_big) / (p_bar | p_box)

install.packages("magick")

library(magick)

Linking to ImageMagick 6.9.12.93
Enabled features: cairo, fontconfig, freetype, heic, lcms, pango, raw, rsvg, webp
Disabled features: fftw, ghostscript, x11

p_img_fixed <- image_ggplot(image_read("3penguins.png"))

Warning: `aes_string()` was deprecated in ggplot2 3.0.0.
ℹ Please use tidy evaluation idioms with `aes()`.
ℹ See also `vignette("ggplot2-in-packages")` for more information.
ℹ The deprecated feature was likely used in the magick package.
  Please report the issue at <https://github.com/ropensci/magick/issues>.

(p_scatter + p_img_fixed) / (p_bar + p_box)

1.1 What we’ll cover

Today, we’ll cover two topics to help you prepare your plots for publication. Specifically, we’ll have figures for scientific publications in mind, and will cover:

• Formatting plots – theme presets and customizing plot appearance with ggplot’s theme()
• Multi-panel layouts – with the patchwork package
• Saving plots to file – with ggplot’s ggsave()

1.2 Setup

library(tidyverse)

── Attaching core tidyverse packages ──────────────────────── tidyverse 2.0.0 ──
✔ dplyr     1.2.0     ✔ readr     2.2.0
✔ forcats   1.0.1     ✔ stringr   1.6.0
✔ ggplot2   4.0.2     ✔ tibble    3.3.1
✔ lubridate 1.9.5     ✔ tidyr     1.3.2
✔ purrr     1.2.1     
── Conflicts ────────────────────────────────────────── tidyverse_conflicts() ──
✖ dplyr::filter() masks stats::filter()
✖ dplyr::lag()    masks stats::lag()
ℹ Use the conflicted package (<http://conflicted.r-lib.org/>) to force all conflicts to become errors

library(palmerpenguins)

Attaching package: 'palmerpenguins'

The following objects are masked from 'package:datasets':

    penguins, penguins_raw

p <- penguins |>
  drop_na() |> # Get rid of rows with NAs
  ggplot(aes(x = flipper_length_mm, y = body_mass_g, fill = species)) +
  geom_point(shape = 21, size = 2) +
  scale_fill_brewer(palette = "Dark2") +
  scale_y_continuous(labels = scales::label_comma()) +
  labs(x = "Flipper length (mm)", y = "Body mass (g)")

p

2.1 Theme preset options

ggplot2 ships with several built-in theme functions. Here are some of the most useful alternatives to the default (which is called theme_gray()):

Let’s compare a few:

p + theme_bw()

p + theme_classic()

p + theme_minimal()

2.2 Scaling all text sizes with base_size()

All theme preset functions accept a base_size argument that scales the size of text and points in the plot – the larger the value, the larger the text (the default value is 11):

p + theme_classic(base_size = 10)

p + theme_classic(base_size = 15)

Note that this doesn’t mean all text will have the same size: instead, it is a scaling factor. So, axis titles will still remain similarly larger than axis text at tick labels, regardless of the base_size().

2.3 Customizing with theme()

Preset themes get you most of the way there, but theme() lets you adjust individual elements. You layer it on top of a preset:

p + theme_classic() + theme(...)

A first example of a theme() call – to make the legend title bold:

theme(legend.title = element_text(face = "bold"))

The theme() function has dozens of arguments to adjust elements such as legend.title, axis.text, panel.background, and so on. What makes its usage perhaps a bit overwhelming at first is that you will also need to know the type of element you want to adjust, which is specified with element_*() functions:

Below, we’ll see some examples of several of these.

p +
  theme_classic(base_size = 13) +
  theme(
    axis.title = element_text(size = 14, face = "bold.italic"),
    legend.title = element_text(face = "bold")
  )

p +
  theme_classic(base_size = 13) +
  theme(legend.position = "top")

p +
  theme_classic() +
  theme(
    legend.position = c(0.15, 0.85),  # upper-left corner
    legend.background = element_rect(color = "grey70")
  )

p +
  theme_bw() +
  theme(
    panel.grid.minor = element_blank(),
    panel.grid.major.x = element_blank(),
    panel.grid.major.y = element_line(linetype  = "longdash", linewidth = 0.5)
  )

theme_set(theme_classic(base_size = 13))

theme_update(
  panel.grid.major.y = element_line(color = "grey70", linewidth = 0.2)
)