-
Notifications
You must be signed in to change notification settings - Fork 0
/
structures.Rmd
227 lines (162 loc) · 11.2 KB
/
structures.Rmd
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
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
---
title: "Structures"
output: rmarkdown::html_vignette
vignette: >
%\VignetteIndexEntry{Structures}
%\VignetteEngine{knitr::rmarkdown}
%\VignetteEncoding{UTF-8}
---
```{r, include = FALSE}
knitr::opts_chunk$set(
collapse = TRUE,
comment = "#>"
)
root <- tempfile()
dir.create(root)
knitr::opts_knit$set(
root.dir = root
)
# Activate crayon
## https://github.com/r-lib/crayon/issues/24
options(crayon.enabled = TRUE)
old_hooks <- fansi::set_knit_hooks(
knitr::knit_hooks,
which = c("output", "message", "error")
)
```
`{structured}` revolves around the concept of structures, which is a fancy name for project templates. Well, strongly *structured* templates. So, it is essential to understand those structures to select the most adequate for your project.
`{structured}` defines projects by a combination of two values. The first is **project level** and determines the **complexity** of your project^[We should always aim for the simplest solution, but sometimes complexity is unavoidable.]. The second is **project type** and specifies **how** your project will solve your problem. The next sections give more details about each option those values can assume. Finally, at the end of this tutorial, we will also show you some ways to extend these structures to your needs.
Before we start, it is important to load some packages.
```{r}
# Uncomment to install packages
## install.packages("fs")
## install.packages("remotes")
## remotes::install_github("GiuseppeTT/structured")
# Load packages
library(fs)
library(structured)
```
## Project level
### Basic
The "basic" project level is simple, minimal, but complete enough to accommodate all the project types. In other words, it is a perfect starting point for newbies and an excellent use for quick and simple projects.
The structure is composed of the following files:
```{r}
structure_project(
"basic-project",
level = "Basic",
type = "None"
)
dir_tree("basic-project", all = TRUE)
```
The purpose of each file/folder is the following:
- `data/` Save all the pertaining data. For example, csv tabular data, the cleaned version of the csv tabular data or even a SQLite database file.
- `output/` Save anything generated that is not data. For instance, figures, tables, models, documents, etc.
- `extra/` Save any file that is not data, output or code but is related to the project. Some cases are professor instructions about a class assignment and meeting notes.
- `R/` Save auxiliary R files. That is, files that are not run directly. Some examples are `ui.R` and `server.R`, which are used by the `{shiny}` package.
- `R/functions.R` Write your R functions used in the rest of the project. This helps keeping your code clean, similar to the effect of adding subfolder such as `data/` to organize your files.
- `basic-project.Rproj` (`<project directory name>.Rproj`) RStudio project file. The [Project-oriented workflow](https://www.tidyverse.org/blog/2017/12/workflow-vs-script/) article and the [Workflow: projects](https://r4ds.had.co.nz/workflow-projects.html) chapter are great reference. In short, this little guy allows you to break free from all the evil that comes from `setwd("path/that/only/works/on/my/computer")` and use `read_csv("data/my-data.csv")` directly.
### Intermediate
If the objective of the "basic" project level is getting the job done, the goal of the "intermediate" project level is getting the job done and sharable. Even if it means sharing with yourself six months in the future.
The structure is composed of the following files:
```{r}
structure_project(
"intermediate-project",
level = "Intermediate",
type = "None"
)
dir_tree("intermediate-project", all = TRUE)
```
The purpose of the additional file/folders are the following:
- `README.md` Write must read instructions about your project. Some useful topics are a quick description of what the project is about and steps on how to run it.
- `.gitignore` This file represents more than its functionality. The idea here is that you use [git](https://git-scm.com/) to version control your project. This way you will never be afraid again of changing one line and breaking everything. Plus, it makes team coding much better. The [Happy Git With R](https://happygitwithr.com/) notes and the [Git and Github](https://r-pkgs.org/git.html) chapter are great resources to learn git for R users.
## Project type
### Script
**Examples:** [basic version](https://github.com/GiuseppeTT/structured-examples/tree/main/basic-script) and [intermediate version](https://github.com/GiuseppeTT/structured-examples/tree/main/intermediate-script)
The "script" project type is the most direct approach to solving a problem. You simply code your analysis in a script, run it and its done. The product files should be available in the `output/` directory.
Using the "basic" project level, the structure is composed of the following files:
```{r}
structure_project(
"script-project",
level = "Basic",
type = "Script"
)
dir_tree("script-project", all = TRUE)
```
The purpose of the additional file/folders are the following:
- `analysis.R` Code your analysis. Some common steps are reading data, cleaning data, computing statistics and plotting.
### R Markdown (Simplified)
**Examples:** [basic version](https://github.com/GiuseppeTT/structured-examples/tree/main/basic-r-markdown-simplified) and [intermediate version](https://github.com/GiuseppeTT/structured-examples/tree/main/intermediate-r-markdown-simplified)
The "R markdown (simplified)" project type is designed for easily creating documents from R Markdown files. Just use the `knit` button in your RStudio to render the Rmd file and copy the generated document to the `output/` folder.
Using the "basic" project level, the structure is composed of the following files:
```{r}
structure_project(
"r-markdown-simplified-project",
level = "Basic",
type = "R Markdown (Simplified)"
)
dir_tree("r-markdown-simplified-project", all = TRUE)
```
The purpose of the additional file/folders are the following:
- `analysis.Rmd` Write and code your analysis. Some common sections are database description (read data), results (compute statistics) and conclusion. If you want to learn more about R Markdown, check its [documentation](https://rmarkdown.rstudio.com/).
### R Markdown
**Examples:** [basic version](https://github.com/GiuseppeTT/structured-examples/tree/main/basic-r-markdown) and [intermediate version](https://github.com/GiuseppeTT/structured-examples/tree/main/intermediate-r-markdown)
The "R markdown" project type offers a more programmatic approach to generating documents than the "R markdown (simplified)" project type. Instead of relying on the `knit` button, you run a script that will automatically render all Rmd documents and move them to the `output/` folder.
Using the "basic" project level, the structure is composed of the following files:
```{r}
structure_project(
"r-markdown-project",
level = "Basic",
type = "R Markdown"
)
dir_tree("r-markdown-project", all = TRUE)
```
The purpose of the additional file/folders are the following:
- `Rmd/` Save any R Markdown file.
- `Rmd/analysis.Rmd` Write and code your analysis. Some common sections are database description (read data), results (compute statistics) and conclusion. If you want to learn more about R Markdown, check its [documentation](https://rmarkdown.rstudio.com/).
- `render.R` You do not have to do anything as this script is automatically configured. Just run it to render the R Markdown files.
**Observation:** If you want to use the `knit` button in this structure, you need to configure the knit directory to the project directory. You can do that by clicking "Knit" -> "Knit Directory" -> "Project Directory". For more information, check the [The working directory for R code chunks](https://bookdown.org/yihui/rmarkdown-cookbook/working-directory.html) subchapter.
### Targets
**Examples:** [basic version](https://github.com/GiuseppeTT/structured-examples/tree/main/basic-targets) and [intermediate version](https://github.com/GiuseppeTT/structured-examples/tree/main/intermediate-targets)
The "targets" project type is specially useful for big and slow to run analysis. The idea here is to leverage the `{targets}` package to organize your analysis code even more and run only the necessary parts when changing something.
Using the "basic" project level, the structure is composed of the following files:
```{r}
structure_project(
"targets-project",
level = "Basic",
type = "Targets"
)
dir_tree("targets-project", all = TRUE)
```
The purpose of the additional file/folders are the following:
- `_targets.R` Code your analysis workflow. I recommend reading the `{targets}` [documentation](https://docs.ropensci.org/targets/)
### Shiny
**Examples:** [basic version](https://github.com/GiuseppeTT/structured-examples/tree/main/basic-shiny) and [intermediate version](https://github.com/GiuseppeTT/structured-examples/tree/main/intermediate-shiny)
The "shiny" project type offers a different approach to projects. Instead of producing some static files (e.g., images and pdfs), it uses the `{shiny}` package to build a web application. One big use case are interactive dashboards (check the `{shinydashboard}` package).
Using the "basic" project level, the structure is composed of the following files:
```{r}
structure_project(
"shiny-project",
level = "Basic",
type = "Shiny"
)
dir_tree("shiny-project", all = TRUE)
```
The purpose of the additional file/folders are the following:
- `R/global.R` Define global variables. For instance, a data frame containing the data to be presented in the dashboard.
- `R/ui.R` Define the app UI (user interface). In plain English, what the user sees and interact in their browser.
- `R/server.R` Define the app server. In other words, the code responsible for doing calculations, generating plots, etc.
- `app.R` You do not have to do anything as this script is automatically configured. Just run it to host the shiny application. For more information, check the `{shiny}` [documentation](https://shiny.rstudio.com/).
### None
The "none" project type is, well..., nothing. It adds no file nor folder to the project, except for the files already included by the chosen project level. In summary, it is good option if you just want the raw template without an optioned approach to solve your problem.
Using the "basic" project level, the structure is composed of the following files:
```{r}
structure_project(
"none-project",
level = "Basic",
type = "None"
)
dir_tree("none-project", all = TRUE)
```
## Extensions
All the presented structures were designed with the special consideration to be flexible. Therefore, if you feel you need to add a file, folder or even delete some, please do so!
The "subfolder script extension" example ([basic version](https://github.com/GiuseppeTT/structured-examples/tree/main/extension-subfolder-basic-script) and [intermediate version](https://github.com/GiuseppeTT/structured-examples/tree/main/extension-subfolder-intermediate-script)) illustrates this process. It adds subfolders such as `data/clean/` and `output/figure/` to further divide the data and output files. Moreover, the `analysis.R` script was moved to the `script/` folder along with a new `clean.R` file responsible for cleaning the data before the analysis.