Good workflow practices

Prerequisites

Naming files

Three principles of naming files

  • machine readable
  • human readable
  • plays well with default ordering (e.g. alphabetical and numerical ordering)

(Jenny Bryan)

for the purposes of this bootcamp an additional principle is that file names follow

  • tidyverse style (all lower case letters, words separated by HYPHEN)

README.md

  • README file is the first file users read. In our case a user might be our future self, a teammate, or (if open source) anyone.

  • There can be multiple README files within a single directory: e.g. for the general project folder and then for a data subfolder. Data folder README’s can possibly contain codebook (data dictionary).

  • It should be brief but detailed enough to help user navigate.

  • a README should be up-to-date (can be updated throughout a project’s lifecycle as needed).

  • On GitHub we use markdown for README file (README.md). Good news: emojis are supported.

README examples

R Packages

Default

Microsoft products have Copyright. Images used based on fair use for educational purposes.

R Packages

Optional

R packages

  • When you download R, you actually download base R.

  • But there are MANY optional packages you can download.

  • Good part: There is an R package for (almost) everything, from complex statistical modeling packages to baby names.

  • Bad part: At the beginning it can feel overwhelming.

  • All this time we have actually been using R packages.

R packages

What do R packages have? All sorts of things but mainly

  • functions

  • datasets

R packages

Try running the following code:

beep()
Error in beep(): could not find function "beep"

Why are we seeing this error?

Installing packages

Using install.packages()

In your Console, install the beepr package

install.packages("beepr")

We do this in the Console because we only need to do it once.

Using Packages pane

Packages Pane > Install

Letting RStudio Install

If you save your file and using a package RStudio will tell you that you have not installed the package.

Using packages

Using beep() from beepr

Option 1

library(beepr)
beep()

More common usage.

Useful if you are going to use multiple functions from the same package. E.g. we have used many functions (ggplot, aes, geom_…) from the ggplot2 package. In such cases, usual practice is to put the library name in the first R chunk in the .Rmd file.

Using beep() from beepr

Option 2

beepr::beep()

Useful when you are going to use a function once or few times. Also useful if there are any conflicts. For instance if there is some other package in your environment that has a beep() function that prints the word beep, you would want to distinguish the beep function from the beepr package and the beep function from the other imaginary package.

Open Source

  • Any one around the world can create R packages.

  • Good part: We are able to do pretty much anything R because someone from around the world has developed the package and shared it.

  • Bad part: The language can be inconsistent.

  • Good news: We have tidyverse.

Tidyverse

The tidyverse is an opinionated collection of R packages designed for data science. All packages share an underlying design philosophy, grammar, and data structures. tidyverse.org

Tidyverse

In short, tidyverse is a family of packages. From practical stand point, you can install many tidyverse packages at once (and you did this). By doing that you installed all the following packages.

  • ggplot2
  • dplyr
  • tidyr
  • readr
  • purrr
  • tibble
  • stringr
  • forcats

We can also load multiple tidyverse packages all at the same time.

library(tidyverse)
── Attaching core tidyverse packages ──────────────────────── tidyverse 2.0.0 ──
✔ dplyr     1.1.2     ✔ readr     2.1.4
✔ forcats   1.0.0     ✔ stringr   1.5.0
✔ ggplot2   3.4.2     ✔ tibble    3.2.1
✔ lubridate 1.9.2     ✔ tidyr     1.3.0
✔ purrr     1.0.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

Fun fact

library(magrittr)

Treachery of Images by René Magritte

Image for Treachery of Images is from University of Alabama website and used under fair use for educational purposes.

Importing .csv Data

readr::read_csv("dataset.csv")

Importing Excel Data

readxl::read_excel("dataset.xlsx")

Importing Excel Data

readxl::read_excel("dataset.xlsx", sheet = 2)

Importing SAS, SPSS, Stata Data

library(haven)
# SAS
read_sas("dataset.sas7bdat")
# SPSS
read_sav("dataset.sav")
# Stata
read_dta("dataset.dta")

Where is the dataset file?

Importing data will depend on where the dataset is on your computer. However we use the help of here::here() function. This function sets the working directory to the project folder (i.e. where the .Rproj file is).

read_csv(here::here("data/dataset.csv"))

Collaboration on GitHub

Collaboration on GitHub

Collaboration on GitHub

Collaboration on GitHub

Collaboration on GitHub

Collaboration on GitHub

Collaboration on GitHub

Collaboration on GitHub

If each change is made by one collaborator at a time, this would not be an efficient workflow.

Collaboration on GitHub

Collaboration on GitHub

Collaboration on GitHub

Collaboration on GitHub

1 - commit

2 - pull (very important)

3 - push

Collaboration on GitHub

Collaboration on GitHub

Collaboration on GitHub

Opening an issue

We can create an issue to keep a list of mistakes to be fixed, ideas to check with teammates, or note a to-do task. You can assign tasks to yourself or teammates.

Closing an issue

If you are working on an issue, it makes sense to refer to issue number in your commit message (e.g. “add first draft of alternate texts for #4”). If your commit resolves the issue then you can use key words such as “fixes #4” or “closes #4” to close the issue. Issues can also be manually closed.

It is also a good practice to save session information as package versions change, in order to be able to reproduce results from an analysis we need to know under what technical conditions the analysis was conducted.

sessionInfo()
R version 4.3.0 (2023-04-21)
Platform: aarch64-apple-darwin20 (64-bit)
Running under: macOS Ventura 13.4

Matrix products: default
BLAS:   /Library/Frameworks/R.framework/Versions/4.3-arm64/Resources/lib/libRblas.0.dylib 
LAPACK: /Library/Frameworks/R.framework/Versions/4.3-arm64/Resources/lib/libRlapack.dylib;  LAPACK version 3.11.0

locale:
[1] en_US.UTF-8/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8

time zone: America/Los_Angeles
tzcode source: internal

attached base packages:
[1] stats     graphics  grDevices utils     datasets  methods   base     

other attached packages:
 [1] magrittr_2.0.3  lubridate_1.9.2 forcats_1.0.0   stringr_1.5.0  
 [5] dplyr_1.1.2     purrr_1.0.1     readr_2.1.4     tidyr_1.3.0    
 [9] tibble_3.2.1    ggplot2_3.4.2   tidyverse_2.0.0

loaded via a namespace (and not attached):
 [1] gtable_0.3.3     jsonlite_1.8.4   compiler_4.3.0   tidyselect_1.2.0
 [5] scales_1.2.1     yaml_2.3.7       fastmap_1.1.1    R6_2.5.1        
 [9] generics_0.1.3   knitr_1.42       munsell_0.5.0    pillar_1.9.0    
[13] tzdb_0.4.0       rlang_1.1.1      utf8_1.2.3       stringi_1.7.12  
[17] xfun_0.39        timechange_0.2.0 cli_3.6.1        withr_2.5.0     
[21] digest_0.6.31    grid_4.3.0       rstudioapi_0.14  hms_1.1.3       
[25] lifecycle_1.0.3  vctrs_0.6.2      evaluate_0.21    glue_1.6.2      
[29] fansi_1.0.4      colorspace_2.1-0 rmarkdown_2.22   tools_4.3.0     
[33] pkgconfig_2.0.3  htmltools_0.5.5