What it is …

“Facilitate easy and accurate reproducibility of all steps of research: Results, process and comprehension – from raw data to finished output”

Why

• To help yourself not get lost
• Documentation (formal/legal)
• Reproducibility (from A-Z)
• Reuseability (different outputs)
• Recycling (reassemble for other purposes)

Levels of research reproducibility

::: {.cell}

:::

Aim for (**)

Comments in R code and markdown

R code

# This is a single-line comment in R code
# ...there are no multi-line comments
x <- 2 + 2 # ...but inline comments are okay

# NOTE: The hash tag has different meanings
# in R code and markdown!

Markdown

#| echo: true
#| eval: false

<!--

This is a multi-line comment ..
..in markdown

-->

<!-- This is a single line comment -->

Where to put comments?

(..click the tabs)

# this is definitely okay
x <- 2 + 2

# ...but is the following okay?
tibble(x=1:10, y=2:11) %>% # ..Is this okay?
  filter(y>5 & # How about breaking in the middle..
  x != 9) # ..of a statement like 'filter'?

# A tibble: 5 × 2
      x     y
  <int> <int>
1     5     6
2     6     7
3     7     8
4     8     9
5    10    11

Keep it simple!

# Comment lines before the code
# can be multiple lines and does
# not disturb your reading of the
# code ... best practice!

x <- 2 + 2 # use inline comments sparringly
y <- x^2 - c(2, 5, 8, 10:14) # ..the are distracting!

Meaningful comments

What comments would be relevant here?

# 1
d <- read.csv("my_data_file.csv")

# 2
d <- d %>% filter(id != "241269-1212")

# 3
d <- d %>% 
  mutate(s=factor(c("M", "F"))[as.numeric(substr(id,nchar(id),nchar(id))) %% 2])

# ?? comments necessary ??
d <- read.csv("my_data_file.csv")

# excluded because participant entered an invalid CPR number
d <- d %>% filter(id != "2321369-1212")

# set 's' to F(emale) or M(ale) depending on odd/even last digit in CPR
d <- d %>% 
  mutate(s=factor(c("M", "F"))[as.numeric(substr(id,nchar(id),nchar(id))) %% 2])

Commenting your code

Main points

• Always comment your code
• Comments should explain your thinking : ‘why’
• With good code the ‘how’ is self-evident
  • If your code can not be self-evident: explain in comments

Using white space

In markdown, there's  
an important difference
between '_new-line_' and '_empty-line_'.

...white space matters!

Check out Soft wrap long lines in the Code menu.

Commenting your project

Maintain a README.md file in each project, at the root level

• A simple description of the project purpose (the ‘why’)
• People involved
• Data sources etc
• List most important components (data and files)

Especially important for larger, more complex projects with many data sources, collaborators, etc

Commenting your project

Maintain a data definition (markdown) file in data file project, in the same folder as the data file itself

• Where does data come from?
• What are the individual variables in the data
  • E.g. ‘weight’ is self-explanatory … but is it kg or lb, is it measured or self reported, etc?
• How is data in different files related to each other?
  • E.g. the file ‘clean_data.rds’ might be generated by the script ‘clean_my_data.R’ on the basis of data file ‘raw_data.csv’

Especially important for larger, more complex projects with many data sources, collaborators, etc

Meaning

Let variable, function and file names convey meaning.

# 1 
d <- d %>% 
  mutate(s=factor(c("M", "F"))[as.numeric(substr(id,nchar(id),nchar(id))) %% 2])

# 2 
d_m <- d %>% filter(s=="M")

Suggest alternative code and variable names for this code

Meaning

Let variable, function and file names convey meaning.

# 1 
data <- data %>% 
  mutate(sex=factor(c("M", "F"))[as.numeric(substr(id,nchar(id),nchar(id))) %% 2])

# 2 
data_males_only <- data %>% filter(sex=="M")

Making the meaning even clearer…

data <- data %>% 
  mutate(sex=cpr2sex(id))

Alas, the function cpr2sex does not exist in base R or Tidyverse

# Requires a custom function like this -- which could be sourced from file

cpr2sex <- function(x) {
  # This function takes a string (x), presumed to be a valid Danish CPR
  # and return "F", "M" or NA depending on the last character in the string
  # If the last CPR character is an even number, it indicates female sex, and
  # an odd number indicates male sex.
  if (str_sub(x, str_length(x), str_length(x)) %in% c("0","2","4","6","8")) {
    return("F") 
  } else {
    return("M") 
  } 
  return(NA) # Last character in CPR is not a ciffre
}

Compound names

• Do use under_scores
• Do not use camelCase
• Do not use kebab-case

Nouns and verbs

make_larger_by_10 <- function(x) {
  return(x+10)
}

ten_larger <- make_larger_by_10(112)

# For instance:
# selected_data <- data %>% select(..)

Names

Main points

• Names should be meaningful
• Use under_scores, not CamelCase, nor kebab-case
• Function names should be verbs
• Variable names should be nouns

R Projects

One project in one folder!

The project root folder

Should contain

• RStudio project (*.RProj)
• README.md
• sessionInfo.txt
• Your main R scripts
• Your RMarkdown and quarto scripts
• Relevant subfolders (/custom_functions, /gfx, /data, etc)

Using subfolders

Use the here() function to refer subfolders.

Using relative paths with ./ and ../ can also work

Do not use absolute filesystem paths like C:/users/Einstein/Documents/

The ubiquituos versioning nightmare

Files and folders

Make and use your own folder/sub-folder template for new projects

File types

• Text always preferable to binary files
• Markup files (HTML, XML, etc) are human readable, but can be complex
• Application files (.odt, .docx) are often either binary files or very complex markup files

gfx/prefer_text_files.pdf

gfx/prefer_text_files.pdf

gfx/prefer_text_files.xml

File types

Stick to simple, human-readable files like R-scripts, markdown, csv files, etc, as far into the process as you can and only generate pdf, word, tiff, jpeg etc files as the final step.

Weird characters?

It’s probably the character encoding (Microsoft Excel again!) – just stick to UTF8/UTF16

Files and folders

Main points

• Use a strict folder structure you can handle – make a template!
• Use relational folder paths if possible
• Use human-readable files only if possible (txt, md, Rmd, csv, etc)
• Only use non-human readable files for ‘final output’ (pdf, docx, xlsx, etc)