generated from DaniMori/rproj-template
-
Notifications
You must be signed in to change notification settings - Fork 0
/
README.Rmd
184 lines (135 loc) · 6.02 KB
/
README.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
---
output: github_document
editor_options:
markdown:
wrap: 80
canonical: false
---
```{r config}
#| echo: false
# TODO: Substitute "<repository-name>" by your own repository name, e.g.:
# REPOSITORY_NAME <- "my-amazing-repo"
REPOSITORY_NAME <- "<repository-name>"
# TODO: Substitute "<username>" by your own GitHub user name, e.g.:
# GITHUB_USERNAME <- "JohnDoe"
GITHUB_USERNAME <- "<username>"
```
# Repository ``r REPOSITORY_NAME``
<!-- TODO: Add a repository description -->
<This is a free text repository description.>
# License
<!-- TODO: Choose a license and update this section, if necessary -->
This template is licensed under the
[Creative Commons Attribution 4.0 International license][license]. Please
see the [license file][licfile].
[license]: https://creativecommons.org/licenses/by/4.0/
[licfile]: LICENSE.md
## Attributions
### Rstudio project template
This project makes use of the [rproj-template][selflink] Github template
created by [Daniel Morillo][profile] and licensed under the
[Creative Commons Attribution 4.0 International license][license].
[selflink]: https://github.com/DaniMori/rproj-template
[profile]: https://github.com/DaniMori
<!-- TODO: Add attributions to other software components, if necessary -->
### <Software component>
# Project installation
## Software components
Start by installing the following software components:
```{r software-versions}
#| echo: false
r_version <- paste(version$major, version$minor, sep = '.')
rs_version <- rstudioapi::versionInfo()$long_version
rs_version_dl <- rs_version |> stringr::str_replace('\\+', '-')
q_version <- quarto::quarto_version()
git_version <- gitr::git_version()
```
- [R version `r r_version`][R]:
In Windows, using the [binary installer][inst] is recommended.
[R]: https://cran.rstudio.com/bin/windows/base/old/`r r_version`/
[inst]: https://cran.rstudio.com/bin/windows/base/old/`r r_version`/R-`r r_version`-win.exe
- [Rstudio Desktop][RS]: Although not strictly necessary, it is recommended
to install the Rstudio IDE; for strict reproducibility, use build
[`r rs_version` for Windows 10/11][RSv].
[RS]: https://posit.co/download/rstudio-desktop/
[RSv]: https://download1.rstudio.org/electron/windows/RStudio-`r rs_version_dl`.exe
- [Quarto publishing system][Q]: An additional component used by Rstudio to
generate and publish literate computing outputs. For strict reproducibility
please use build `r q_version`; On Windows, use [the 64-bit installer][QW].
[Q]: https://quarto.org/
[QW]: https://github.com/quarto-dev/quarto-cli/releases/download/v`r q_version`/quarto-`r q_version`-win.msi
- [Git client][G]: Install the Git client in order to be able to clone locally
the project repository.
On Windows, use [the 64-bit Windows installer][GW].
[G]: https://git-scm.com/download
[GW]: https://github.com/git-for-windows/git/releases/download/v`r git_version`.windows.1/Git-`r git_version`-64-bit.exe
## Installing the project locally
This project is hosted as a GitHub repository.
It can be cloned as a local Git repository following [these instructions][CR]
(steps 2 through 7).
Note that this will create a local copy of ('clone') the GitHub repository as an
Rstudio project in the folder specified.
The URL that must be entered into the `Repository URL` text box is:
```
https://github.com/`r GITHUB_USERNAME`/`r REPOSITORY_NAME`
```
[CR]: https://book.cds101.com/using-rstudio-server-to-clone-a-github-repo-as-a-new-project.html#step---2
**IMPORTANT:** It is totally unrecommended to clone a git repository inside a
cloud storage folder (e.g., Dropbox, OneDrive). Please note that GitHub serves
the purpose of backing up the repository, so no cloud storage is necessary.
Similarly, cloning the repository in a network folder may cause problems with
the `renv` environment (see below); do it at your own risk!
After cloning the repository,
the Rstudio project will open automatically in the Rstudio IDE.
If it doesn't, or you want to return later to the project in Rstudio,
you can do so by double clicking on the file `rstudio_project.Rproj`
that has been created in the project folder when cloning the repository.
**NOTE:** It is common practice to avoid using and versioning `.Rprofile` files.
However, this project uses [package `renv`][renv]
to create a reproducible environment,
which needs the `.Rprofile` file that lives in the root directory of the
project. **Please DO NOT delete or edit this file**; it will install and
activate the `renv` package and make it ready for restoring the environment.
[renv]: https://cran.r-project.org/package=renv
## Restoring the environment
The reproducible environment created by `renv` must be restored to install all
the packages this project needs to be built properly. If `renv` does not
initialize automatically (check the console for messages about this), you will
need to manually install the package first:
```r
install.packages("renv")
```
Once it is successfully installed, use the "renv" -\> "Restore library..."
button in Rstudio's "Packages" tab to restore the environment. Alternatively,
you can type in the console:
```r
renv::restore(prompt = FALSE)
```
# Repository structure
The file structure of this repository is as follows:
```
`r REPOSITORY_NAME`
|
|--- apps (To store apps, e.g. in Shiny)
|
|--- dat (To store input datasets; must NEVER be checked-in to Github)
|
|--- doc (To store important documentation of the project)
| |
| |--- minutes (To store meeting minutes)
|
|--- notebooks (Notebooks to explore data and test processes live here)
|
|--- output (Processing outputs; files must be individually "checked-in"
| when necessary)
|
|--- R (R functions created for this project live here)
|
|--- renv (System library necesssary for `renv` to work. DON'T TOUCH)
|
|--- src (Source scripts that implement the main processes)
|
|--- www (Project assets, e.g., images, bibliography files, etc.)
```
Use the folders as indicated to store the different files and generate the
outputs of the processes.