R Projects
morals
“For every minute spent organizing, an hour is earned.” — (maybe) Benjamin Franklin.
“A good system shortens the road to the goal.” — Anonymous
“Nobody has ever said ‘I regret having such organized R code’” — Me
in brief…
An R project enables your work to be bundled in a portable, self-contained folder. Within the project, all the relevant scripts, data files, figures/outputs, and history are stored in sub-folders and importantly - the working directory is the project’s root folder.
—The Epidemiologist R Handbook
why wouldn’t you?
from Jenny Bryan’s talk https://speakerdeck.com/jennybc/zen-and-the-art-of-workflow-maintenance
from Jenny Bryan’s talk https://speakerdeck.com/jennybc/zen-and-the-art-of-workflow-maintenance
R projects allow you …
- to have one folder per code project;
- to have one git repository per project;
- and to run one R session that’s tied to that project
creating an R project
you should see New Project in the File Menu in RStudio
creating an R project
that will launch the New Project Wizard which will guide you through the project creation process
creating an R project
that will launch the New Project Wizard which will guide you through the project creation process
creating an R project
that will launch the New Project Wizard which will guide you through the project creation process
opening R projects
there are a few ways you can open an R project
opening R projects
there are a few ways you can open an R project
opening R projects
there are a few ways you can open an R project
opening R projects
expect to iterate
i want to stress that on any major project, you will likely need to iterate substantially on the code between the first version and the final version.
prototyping
therefore, sometimes it can be useful to prototype your work just to get a sense of what needs to be done, and then later on move onto a more robust workflow.
suggested project layout
working in a single file
use the outline in RStudio
working with multiple files
versus:
use the goto file/function
(on Windows/Mac/Linux): pressing Ctrl+. [period] will open the Goto Function/File popup:
use the here package
original photo from https://commons.wikimedia.org/wiki/File:Burned_laptop_secumem_11.jpg
If the first line of your R script is
setwd("C:\Users\jenny\path\that\only\I\have")I will come into your office and SET YOUR COMPUTER ON FIRE 🔥.
If the first line of your R script is
rm(list = ls())I will come into your office and SET YOUR COMPUTER ON FIRE 🔥.
use the here package
the payoff of the here package is that it will automatically detect the root of your package and construct paths based off it.
meaning, you can write code like the following without having to worrying about where your working directory is set to or using absolute paths that are specific to your computer:
extras
renv
renv let’s you control exactly what versions of packages are used within an R project and ensure that your collaborators also use exactly the same package versions.
the workflow is pretty simple:
install.packages("renv")
renv::init() # to initialize a new package lockfile
# work in the project as normal
renv::snapshot() # to save the packages used
# keep working ...
renv::snapshot() # take an updated snapshot
# then when your collaborators want to load
# up the package versions as you've locked them
# into the project:
renv::restore()this prevents one of the very hardest bugs to debug: silent differences in functionality between versions of the same R package.
learn more about renv: https://rstudio.github.io/renv/
renv helps you to implement a principle called encapsulation:
meaning that your code is bundled together with its dependencies in order to ensure a consistent, usable interface.
targets
the targets package allows users to write scripts that explicitly declare which code produces what outputs depending on what inputs and the result is that targets is able to run your workflow from start to finish updating any processes where the underlying data or code have changed.
this avoids the problem of having to ask yourself “do i need to update this intermediate output? i can’t remember if i changed the data or code that underlies it.”
learn more about targets: https://books.ropensci.org/targets/
rocker
what if i need the absolute most possible reproducibility because my code has to execute exactly the same no matter the person running it?
then the rocker project may be the solution for you: the rocker project provides docker (containerized) images to support R programming.
(this is quite a bit beyond our course.)
key takeaways
- use R Projects to help organize your code
- use sections within your code to help organize .R files
- use the names of your .R files to help you stay organized
- expect to iterate!
- use the here package to make working with paths easy
- use renv and targets to make reproducing your analysis easy
references
- https://kdestasio.github.io/post/r_best_practices/
- https://www.rforecology.com/post/organizing-your-r-studio-projects/
- https://speakerdeck.com/jennybc/zen-and-the-art-of-workflow-maintenance