Site icon R-bloggers

Creating template files with R

[This article was first published on R on Nicola Rennie, and kindly contributed to R-bloggers]. (You can report issue about the content on this page here)
Want to share your content on R-bloggers? click here if you have a blog, or here if you don't.

Over the past few months, I’ve found myself fine-tuning the structure of my R scripts for #TidyTuesday, and each week they have similar sections: load packages, load data, data wrangling, make a plot, save the plot, and so on. What I’ve ended up doing recently is copying and pasting the script from the previous week, and then removing the unnecessary parts. And I do the same thing with the README files for GitHub – there’s (almost) always a title, a .png file with the final chart, and a .gif file (recorded with {camcorder}) showing the evolution of the chart. And, you guessed it, I usually copy and paste the file from the previous week then update the file names.

I’m sure many of you will have similar problems – where the interactive nature of the task means you can’t fully automate it, but you’re also doing something sort of similar repeatedly. Like many things in the world of programming, if you find yourself copying and pasting the same thing several times, there is almost certainly a better way of doing it. And in this case there is – template files!

Creating folders and files < svg class="anchor-symbol" aria-hidden="true" height="26" width="26" viewBox="0 0 22 22" xmlns="http://www.w3.org/2000/svg"> < path d="M0 0h24v24H0z" fill="currentColor"> < path d="M3.9 12c0-1.71 1.39-3.1 3.1-3.1h4V7H7c-2.76.0-5 2.24-5 5s2.24 5 5 5h4v-1.9H7c-1.71.0-3.1-1.39-3.1-3.1zM8 13h8v-2H8v2zm9-6h-4v1.9h4c1.71.0 3.1 1.39 3.1 3.1s-1.39 3.1-3.1 3.1h-4V17h4c2.76.0 5-2.24 5-5s-2.24-5-5-5z">

But first, let’s make somewhere to keep our new files! For each week, I have a week folder with the name format yyyy-mm-dd nested inside a year folder with the format yyyy, and inside that folder I have a .R file with a name in the format yyyymmdd.R and a README.md file.

Note: It wasn’t always this organised and I lament the days of my dd-mm-yyyy file naming and how difficult it still is to find things…

All of these folders and files can be constructed based on the date alone. We’re eventually going to build a function with the date as an argument (called date_chr). Let’s start by defining a date as a variable, then extracting the year and the date (without the - separators) from it.

1
2
3
date_chr <- "2023-08-22"
yr <- sub("-.*", "", date_chr)
date_strip <- stringr::str_remove_all(date_chr, "-")

Assuming that we’re in the directory where we want to create folders (e.g. the root of the #TidyTuesday repository), then we can make the year and week folders if they don’t already exist:

1
2
3
4
5
new_folder <- file.path(yr, date_chr)
if (!file.exists(new_folder)) {
  dir.create(new_folder, recursive = TRUE)
  message("Created new folder")
}

Here, the recursive = TRUE argument means that all elements of the path e.g. both the2023 and the nested 2023-08-22 folders are created if they need to be. Once we have folders, it’s time to add some (empty) files! Let’s create a .R file named 20230822.R, making sure we check if it exists first to avoid accidentally overwriting any existing work. We can also optionally return a message to say the file has successfully been created.

1
2
3
4
5
new_file <- file.path(yr, date_chr, paste0(date_strip, ".R"))
if (!file.exists(new_file)) {
  file.create(new_file)
  message("Created '.R' file")
}

We can do the same for the README.md file:

1
2
3
4
5
new_readme <- file.path(yr, date_chr, "README.md")
if (!file.exists(new_readme)) {
  file.create(new_readme)
  message("Created 'README.md' file")
}

Now let’s put some things into those files…

Creating a template README file < svg class="anchor-symbol" aria-hidden="true" height="26" width="26" viewBox="0 0 22 22" xmlns="http://www.w3.org/2000/svg"> < path d="M0 0h24v24H0z" fill="currentColor"> < path d="M3.9 12c0-1.71 1.39-3.1 3.1-3.1h4V7H7c-2.76.0-5 2.24-5 5s2.24 5 5 5h4v-1.9H7c-1.71.0-3.1-1.39-3.1-3.1zM8 13h8v-2H8v2zm9-6h-4v1.9h4c1.71.0 3.1 1.39 3.1 3.1s-1.39 3.1-3.1 3.1h-4V17h4c2.76.0 5-2.24 5-5s-2.24-5-5-5z">

Let’s start with a template for the README.md file since it’s a little bit simpler. An example of one of my README files looks like this:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
<h1 align="center"> Refugees </h1>

<p align="center">
  <img src="/2023/2023-08-22/20230822.png" width="60%">
</p>

The making of this visualisation was also recorded using the {camcorder} package.

<p align="center">
  <img src="/2023/2023-08-22/20230822.gif" width="60%">
</p>

Here, I’m using HTML code rather than just Markdown since GitHub understands it, and it gives me a bit more control over how the images and text appear. Let’s generalise this and replace the specific dates with variables:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
<h1 align="center"> Title </h1>

<p align="center">
  <img src="/yr/date_chr/date_strip.png" width="60%">
</p>

The making of this visualisation was also recorded using the {camcorder} package.

<p align="center">
  <img src="/yr/date_chr/date_strip.gif" width="60%">
</p>

We can save this as a readme-template.md file. If you plan to add this into an R package, you can save this file in the inst folder. Otherwise, keep it somewhere that you know where it is, e.g. in a utils folder in your #TidyTuesday repository. Now we want to copy the contents of this template file, replace the yr, date_chr, and date_strip variables with the actual values, and write to our newly created README.md file:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# copy lines to README file
readme_txt <- readLines("readme-template.md")

# replace placeholder text with variables
readme_txt <- gsub(pattern = "yr", replacement = yr, x = readme_txt)
readme_txt <- gsub(pattern = "date_chr", replacement = date_chr, x = readme_txt)
readme_txt <- gsub(pattern = "date_strip", replacement = date_strip, x = readme_txt)

# write to file
writeLines(readme_txt, con = new_readme)
message("'README.md' contents copied")

Creating a template .R file < svg class="anchor-symbol" aria-hidden="true" height="26" width="26" viewBox="0 0 22 22" xmlns="http://www.w3.org/2000/svg"> < path d="M0 0h24v24H0z" fill="currentColor"> < path d="M3.9 12c0-1.71 1.39-3.1 3.1-3.1h4V7H7c-2.76.0-5 2.24-5 5s2.24 5 5 5h4v-1.9H7c-1.71.0-3.1-1.39-3.1-3.1zM8 13h8v-2H8v2zm9-6h-4v1.9h4c1.71.0 3.1 1.39 3.1 3.1s-1.39 3.1-3.1 3.1h-4V17h4c2.76.0 5-2.24 5-5s-2.24-5-5-5z">

The process for creating, copying, and writing the .R file will be similar to the README template process. Let’s start by creating a file r-template.R. This will be very specific to your use case, and for me it’s a file that’s evolved over several years of #TidyTuesday contributions. In this file, I’ll

Again, like the README file, instead of hard-coding any date values, I’ll replace them with the yr, date_chr, and date_strip variables:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
# Load packages -----------------------------------------------------------

library(tidyverse)
library(showtext)
library(patchwork)
library(camcorder)
library(ggtext)
library(nrBrand)
library(glue)


# Load data ---------------------------------------------------------------

tuesdata <- tidytuesdayR::tt_load(date_chr)


# Load s --------------------------------------------------------------

_add_google("Roboto", "roboto")
showtext_auto()


# Define colours ----------------------------------------------------------

bg_col <- ""
text_col <- ""
highlight_col <- ""


# Data wrangling ----------------------------------------------------------



# Start recording ---------------------------------------------------------

gg_record(
  dir = file.path(yr, date_chr, "recording"),
  device = "png",
  width = 7,
  height = 5,
  units = "in",
  dpi = 300
)


# Define text -------------------------------------------------------------

social <- nrBrand::social_caption(
  bg_colour = bg_col,
  icon_colour = highlight_col,
  _colour = text_col,
  _family = "roboto"
)
title <- ""
st <- ""
cap <- paste0(
  "**Data**: <br>", social
)


# Plot --------------------------------------------------------------------



# Save gif ----------------------------------------------------------------

gg_playback(
  name = file.path(yr, date_chr, paste0(date_strip, ".gif")),
  first_image_duration = 4,
  last_image_duration = 20,
  frame_duration = .25,
  background = bg_col
)

Setting up comment sections in R files can be really helpful for organising and structuring your code in a more modular way – it also means you code is partly pre-commented! Here, I’ve also loaded a personal R package, {nrBrand}, that writes the plot caption with social media icons. If you want to find out more about how to create your own, you can read my previous blog post on Adding social media icons to charts with {ggplot2}. Using the tidytuesdayR::tt_load() function, which takes a date as input, means I can automatically load the data in as well – although I still need to look at the rfordatascience repository to find out what the data actually is!

Now let’s do the same thing as before: and copy the contents of this template file, edit to change the variable values, and write to the .R file we already created:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
# copy lines to .R file
r_txt <- readLines("r-template.R")

# replace placeholder text with variables
r_txt <- gsub(pattern = "yr", replacement = paste0("\"", yr, "\""), x = r_txt)
r_txt <- gsub(pattern = "date_chr", replacement = paste0("\"", date_chr, "\""), x = r_txt)
r_txt <- gsub(pattern = "date_strip",vreplacement = paste0("\"", date_strip, "\""), x = r_txt)

# write to new file
writeLines(r_txt, con = new_file)
message("'.R' contents copied")

The only thing that’s different about this code is the replacement argument. Here, we want to make sure that we copy with quotation marks, not just the variable value. For example, we want to replace date_chr with "2023-08-22" not 2023-08-22.

Building a function < svg class="anchor-symbol" aria-hidden="true" height="26" width="26" viewBox="0 0 22 22" xmlns="http://www.w3.org/2000/svg"> < path d="M0 0h24v24H0z" fill="currentColor"> < path d="M3.9 12c0-1.71 1.39-3.1 3.1-3.1h4V7H7c-2.76.0-5 2.24-5 5s2.24 5 5 5h4v-1.9H7c-1.71.0-3.1-1.39-3.1-3.1zM8 13h8v-2H8v2zm9-6h-4v1.9h4c1.71.0 3.1 1.39 3.1 3.1s-1.39 3.1-3.1 3.1h-4V17h4c2.76.0 5-2.24 5-5s-2.24-5-5-5z">

Although you could leave all this code in a script, it will be much easier to use if you wrap it into a function. When putting this code into a function, there were a couple of key things I kept in mind:

1
2
3
4
# check date in correct format
if (is.na(as.Date(date_chr, format = "%Y-%m-%d"))) {
  stop("'date_chr' in incorrect format. Should be yyyy-mm-dd.")
}
< details> < summary>Show code: see the complete function
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
use_tt_template <- function(date_chr = "2023-08-22",
                            readme = TRUE) {
  # check date in correct format
  if (is.na(as.Date(date_chr, format = "%Y-%m-%d"))) {
    stop("'date_chr' in incorrect format. Should be yyyy-mm-dd.")
  }
  # get year from date
  yr <- sub("-.*", "", date_chr)
  date_strip <- stringr::str_remove_all(date_chr, "-")
  # make folder
  new_folder <- file.path(yr, date_chr)
  if (!file.exists(new_folder)) {
    dir.create(new_folder, recursive = TRUE)
    message("Created new folder")
  }
  # make new file
  new_file <- file.path(yr, date_chr, paste0(date_strip, ".R"))
  if (!file.exists(new_file)) {
    file.create(new_file)
    message("Created '.R' file")
    # copy lines to .R file
    r_txt <- readLines(system.file("r-template.R",
      package = "usefunc",
      mustWork = TRUE
    ))
    # replace placeholder text with variables
    r_txt <- gsub(
      pattern = "yr",
      replacement = paste0("\"", yr, "\""),
      x = r_txt
    )
    r_txt <- gsub(
      pattern = "date_chr",
      replacement = paste0("\"", date_chr, "\""),
      x = r_txt
    )
    r_txt <- gsub(
      pattern = "date_strip",
      replacement = paste0("\"", date_strip, "\""),
      x = r_txt
    )
    # write to new file
    writeLines(r_txt, con = new_file)
    message("'.R' contents copied")
  }

  if (readme) {
    # make new README file
    new_readme <- file.path(yr, date_chr, "README.md")
    if (!file.exists(new_readme)) {
      file.create(new_readme)
      message("Created 'README.md' file")
      # copy lines to README file
      readme_txt <- readLines(system.file("readme-template.md",
        package = "usefunc",
        mustWork = TRUE
      ))
      # replace placeholder text with variables
      readme_txt <- gsub(
        pattern = "yr", replacement = yr, x = readme_txt
      )
      readme_txt <- gsub(
        pattern = "date_chr", replacement = date_chr, x = readme_txt
      )
      readme_txt <- gsub(
        pattern = "date_strip", replacement = date_strip, x = readme_txt
      )
      # write to file
      writeLines(readme_txt, con = new_readme)
      message("'README.md' contents copied")
    }
  }
  message("Template successfully copied!")
}

Additional resources < svg class="anchor-symbol" aria-hidden="true" height="26" width="26" viewBox="0 0 22 22" xmlns="http://www.w3.org/2000/svg"> < path d="M0 0h24v24H0z" fill="currentColor"> < path d="M3.9 12c0-1.71 1.39-3.1 3.1-3.1h4V7H7c-2.76.0-5 2.24-5 5s2.24 5 5 5h4v-1.9H7c-1.71.0-3.1-1.39-3.1-3.1zM8 13h8v-2H8v2zm9-6h-4v1.9h4c1.71.0 3.1 1.39 3.1 3.1s-1.39 3.1-3.1 3.1h-4V17h4c2.76.0 5-2.24 5-5s-2.24-5-5-5z">

If you’ve never made a function in R before, the R for Data Science book has some excellent information and examples to get started!

If you’re interested in automating parts of your data science workflows, I’d highly recommend you look into GitHub Actions (or GitLab CI/CD). You can read about how I used GitHub Actions to refresh data and redeploy a Shiny app on a schedule in my blog post from last year on Automatically deploying a Shiny app for browsing #RStats tweets with GitHub Actions. I could do something similar here if I wanted to create these template files automatically every Tuesday morning!


Image: giphy.com

To leave a comment for the author, please follow the link and comment on their blog: R on Nicola Rennie.

R-bloggers.com offers daily e-mail updates about R news and tutorials about learning R and many other topics. Click here if you're looking to post or find an R/data-science job.
Want to share your content on R-bloggers? click here if you have a blog, or here if you don't.
Exit mobile version