class: center, middle, inverse, title-slide # R Project Structure ## How to organize files in your R projects ### Giuseppe Tinti Tomio ### 2021-06-22 --- class: inverse, center, middle # Motivation ### Otherwise, this presentation would be a nap opportunity --- # Motivation Have you faced any of these problems lately? - Feel things are constantly disorganized - Cannot reproduce your analysis in your friend's computer - Don't remember how to run your analysis - Are afraid of changing one line and breaking everything Then you will benefit from this work! --- class: inverse, center, middle # Spoilers ### So you know this is really worth it --- # Spoilers In this presentation, I will: - Introduce RStudio projects - Teach a powerful, yet simple, project template - Show how to extend it (e.g. `{shiny}` apps) - Discuss a bit about version control - Mention some tools for advanced users --- class: inverse, center, middle # Enough! Let's start --- # Project structure - Project structure is a technical name for how you organize your files in your project - The goal is to **save time** by enforcing **organization** - Always aim for the simplest structure that does the job .footnote[You can find examples of projects that follow the structures [here](https://github.com/GiuseppeTT/R-Project-Structure/tree/main/example).] --- class: inverse, center, middle # Let's meet our structures! --- class: inverse, center, middle # No structure ### Because everything starts as a draft --- # No structure <PRE class="fansi fansi-output"><CODE><span style='color: #0000BB; font-weight: bold;'>my-project/</span> <span style='color: #555555;'>├── </span><span style='font-weight: bold;'>data.csv</span> <span style='color: #555555;'>├── </span><span style='font-weight: bold;'>professor-instructions.pdf</span> <span style='color: #555555;'>├── </span><span style='font-weight: bold;'>pretty-figure.png</span> <span style='color: #555555;'>└── </span><span style='font-weight: bold;'>analysis.R</span> </CODE></PRE> --- class: center, middle <img src="data:image/png;base64,#../inst/image/drake-setwd.png" width="75%" /> --- # No structure (RStudio project) <PRE class="fansi fansi-output"><CODE><span style='color: #0000BB; font-weight: bold;'>my-project/</span> <span style='color: #555555;'>├── </span><span style='font-weight: bold;'>data.csv</span> <span style='color: #555555;'>├── </span><span style='font-weight: bold;'>professor-instructions.pdf</span> <span style='color: #555555;'>├── </span><span style='font-weight: bold;'>pretty-figure.png</span> <span style='color: #555555;'>├── </span><span style='font-weight: bold;'>analysis.R</span> <span style='color: #555555;'>└── </span><span style='font-weight: bold;'>my-project.Rproj</span> </CODE></PRE> .footnote[You can find more information about RStudio project [here](https://www.tidyverse.org/blog/2017/12/workflow-vs-script/), [here](https://r4ds.had.co.nz/workflow-projects.html) and [here](https://support.rstudio.com/hc/en-us/articles/200526207-Using-Projects).] --- class: inverse, center, middle # Basic template ### 80% of results for 20% of effort --- # Basic template <PRE class="fansi fansi-output"><CODE><span style='color: #0000BB; font-weight: bold;'>my-project/</span> <span style='color: #555555;'>├── </span><span style='color: #0000BB; font-weight: bold;'>data/</span> <span style='color: #555555;'>| └── </span><span style='font-weight: bold;'>data.csv</span> <span style='color: #555555;'>├── </span><span style='color: #0000BB; font-weight: bold;'>extra/</span> <span style='color: #555555;'>| └── </span><span style='font-weight: bold;'>professor-instructions.pdf</span> <span style='color: #555555;'>├── </span><span style='color: #0000BB; font-weight: bold;'>output/</span> <span style='color: #555555;'>| └── </span><span style='font-weight: bold;'>pretty-figure.png</span> <span style='color: #555555;'>├── </span><span style='color: #0000BB; font-weight: bold;'>R/</span> <span style='color: #555555;'>├── </span><span style='font-weight: bold;'>analysis.R</span> <span style='color: #555555;'>└── </span><span style='font-weight: bold;'>my-project.Rproj</span> </CODE></PRE> --- # Basic template <PRE class="fansi fansi-output"><CODE><span style='color: #0000BB; font-weight: bold;'>my-project/</span> <span style='color: #555555;'>├── </span><span style='color: #0000BB; font-weight: bold;'>data/</span> <span style='color: #555555;'>├── </span><span style='color: #0000BB; font-weight: bold;'>extra/</span> <span style='color: #555555;'>├── </span><span style='color: #0000BB; font-weight: bold;'>output/</span> <span style='color: #555555;'>├── </span><span style='color: #0000BB; font-weight: bold;'>R/</span> <span style='color: #555555;'>├── </span><span style='font-weight: bold;'>analysis.R</span> <span style='color: #555555;'>└── </span><span style='font-weight: bold;'>my-project.Rproj</span> </CODE></PRE> --- class: inverse, center, middle # Basic template extensions ### Only a Sith deals in absolutes --- # Extensions: subfolders <PRE class="fansi fansi-output"><CODE><span style='color: #0000BB; font-weight: bold;'>my-project/</span> <span style='color: #555555;'>├── </span><span style='color: #0000BB; font-weight: bold;'>data/</span> <span style='color: #555555;'>| ├── </span><span style='color: #0000BB; font-weight: bold;'>clean/</span> <span style='color: #555555;'>| └── </span><span style='color: #0000BB; font-weight: bold;'>raw/</span> <span style='color: #555555;'>├── </span><span style='color: #0000BB; font-weight: bold;'>extra/</span> <span style='color: #555555;'>├── </span><span style='color: #0000BB; font-weight: bold;'>output/</span> <span style='color: #555555;'>| ├── </span><span style='color: #0000BB; font-weight: bold;'>figure/</span> <span style='color: #555555;'>| ├── </span><span style='color: #0000BB; font-weight: bold;'>model/</span> <span style='color: #555555;'>| └── </span><span style='color: #0000BB; font-weight: bold;'>table/</span> <span style='color: #555555;'>├── </span><span style='color: #0000BB; font-weight: bold;'>R/</span> <span style='color: #555555;'>├── </span><span style='font-weight: bold;'>analysis.R</span> <span style='color: #555555;'>├── </span><span style='font-weight: bold;'>clean.R</span> <span style='color: #555555;'>└── </span><span style='font-weight: bold;'>my-project.Rproj</span> </CODE></PRE> --- # Extensions: R Markdown (simplified) <PRE class="fansi fansi-output"><CODE><span style='color: #0000BB; font-weight: bold;'>my-project/</span> <span style='color: #555555;'>├── </span><span style='color: #0000BB; font-weight: bold;'>data/</span> <span style='color: #555555;'>├── </span><span style='color: #0000BB; font-weight: bold;'>extra/</span> <span style='color: #555555;'>├── </span><span style='color: #0000BB; font-weight: bold;'>output/</span> <span style='color: #555555;'>| ├── </span><span style='font-weight: bold;'>presentation.html</span> <span style='color: #555555;'>| └── </span><span style='font-weight: bold;'>report.pdf</span> <span style='color: #555555;'>├── </span><span style='color: #0000BB; font-weight: bold;'>R/</span> <span style='color: #555555;'>├── </span><span style='font-weight: bold;'>presentation.Rmd</span> <span style='color: #555555;'>├── </span><span style='font-weight: bold;'>report.Rmd</span> <span style='color: #555555;'>└── </span><span style='font-weight: bold;'>my-project.Rproj</span> </CODE></PRE> --- # Extensions: R Markdown <PRE class="fansi fansi-output"><CODE><span style='color: #0000BB; font-weight: bold;'>my-project/</span> <span style='color: #555555;'>├── </span><span style='color: #0000BB; font-weight: bold;'>data/</span> <span style='color: #555555;'>├── </span><span style='color: #0000BB; font-weight: bold;'>extra/</span> <span style='color: #555555;'>├── </span><span style='color: #0000BB; font-weight: bold;'>output/</span> <span style='color: #555555;'>| ├── </span><span style='font-weight: bold;'>presentation.html</span> <span style='color: #555555;'>| └── </span><span style='font-weight: bold;'>report.pdf</span> <span style='color: #555555;'>├── </span><span style='color: #0000BB; font-weight: bold;'>R/</span> <span style='color: #555555;'>├── </span><span style='color: #0000BB; font-weight: bold;'>Rmd/</span> <span style='color: #555555;'>| ├── </span><span style='font-weight: bold;'>presentation.Rmd</span> <span style='color: #555555;'>| └── </span><span style='font-weight: bold;'>report.Rmd</span> <span style='color: #555555;'>├── </span><span style='font-weight: bold;'>render.R</span> <span style='color: #555555;'>└── </span><span style='font-weight: bold;'>my-project.Rproj</span> </CODE></PRE> --- # Extensions: R Markdown Remember to set the "Knit Directory" option to "Project Directory" so your R Markdown files will knit relative to the project folder instead of `Rmd/` ![](data:image/png;base64,#../inst/image/knit-directory-options.png)<!-- --> --- # Extensions: shiny <PRE class="fansi fansi-output"><CODE><span style='color: #0000BB; font-weight: bold;'>my-project/</span> <span style='color: #555555;'>├── </span><span style='color: #0000BB; font-weight: bold;'>data/</span> <span style='color: #555555;'>├── </span><span style='color: #0000BB; font-weight: bold;'>extra/</span> <span style='color: #555555;'>├── </span><span style='color: #0000BB; font-weight: bold;'>output/</span> <span style='color: #555555;'>├── </span><span style='color: #0000BB; font-weight: bold;'>R/</span> <span style='color: #555555;'>| ├── </span><span style='font-weight: bold;'>functions.R</span> <span style='color: #555555;'>| ├── </span><span style='font-weight: bold;'>global.R</span> <span style='color: #555555;'>| ├── </span><span style='font-weight: bold;'>server.R</span> <span style='color: #555555;'>| └── </span><span style='font-weight: bold;'>ui.R</span> <span style='color: #555555;'>├── </span><span style='font-weight: bold;'>app.R</span> <span style='color: #555555;'>└── </span><span style='font-weight: bold;'>my-project.Rproj</span> </CODE></PRE> .footnote[You can find an example of a shiny app [here](https://shiny.rstudio.com/gallery/radiant.html).] --- class: inverse, center, middle # Intermediate template ### You don't need it until you do --- # Intermediate template <PRE class="fansi fansi-output"><CODE><span style='color: #0000BB; font-weight: bold;'>my-project/</span> <span style='color: #555555;'>├── </span><span style='color: #0000BB; font-weight: bold;'>data/</span> <span style='color: #555555;'>├── </span><span style='color: #0000BB; font-weight: bold;'>extra/</span> <span style='color: #555555;'>├── </span><span style='color: #0000BB; font-weight: bold;'>output/</span> <span style='color: #555555;'>├── </span><span style='color: #0000BB; font-weight: bold;'>R/</span> <span style='color: #555555;'>├── </span><span style='font-weight: bold;'>.gitignore</span> <span style='color: #555555;'>├── </span><span style='font-weight: bold;'>README.md</span> <span style='color: #555555;'>├── </span><span style='font-weight: bold;'>analysis.R</span> <span style='color: #555555;'>└── </span><span style='font-weight: bold;'>my-project.Rproj</span> </CODE></PRE> --- # Intermediate template Version control: - Version control is a technical name for git/GitHub - Basicaly a `CTRL+Z` on steroids - Solves problems like `Project_v3_final_truly_final_version2.zip` - Essential for teamwork coding - Great for sharing your work! .footnote[You can find more information about git and GitHub [here](https://happygitwithr.com/), [here](https://r-pkgs.org/git.html) and [here](https://guides.github.com/activities/hello-world/).] --- class: inverse, center, middle # Advanced structure ### A different way to think, a stronger way to code --- # Advanced structure Use the package structure (yeah, not intuitive): - Established structure - Free dependency management with `devtools::install_deps()` - Access to a lot of useful packages: - `{devtools}` for development - `{roxygen2}` for documentation - `{testthat}` for unit testing - Access to a lot of pre-made solutions - Easy to share with `devtools::install_github("repository/project")` .footnote[You can find more information about the package structure [here](https://r-pkgs.org/).] --- # Advanced structure Some advanced tools: - `{here}` to build reliable relative paths - `{usethis}` to setup project - `{targets}` to structure analysis - `{renv}` to manage R packages strictly - `{lintr}` to enforce code consistency - `{rsconnect}` and/or GitHub Pages to host presentations, reports, dashboards, apis, etc - `docker` to solve **all** dependency problems - GitHub Actions to automate everything above --- class: inverse, center, middle # Key takeaways ### The only thing here you need to pay attention to --- # Key takeaways Key takeaways: - If your project is going to take more than one **day**, use at least the **basic** structure - If your project is going to take more than one **coder**, try to use at least the **intermediate** structure - If your project is going to take **a lot of** time and/or people, consider the **advanced** structure - Extend them as necessary, they are flexible! - BUT, don't overcomplicate