-
Notifications
You must be signed in to change notification settings - Fork 0
/
02-projects.Rmd
173 lines (130 loc) · 6.71 KB
/
02-projects.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
# Projects
## Project structure
Some example structures:
```
project
└───data/
└───derived/
└───raw/
└───R/
└───script/
└───graphics/
└───README.md
```
or
```
project/
└───README.md
└───input/
└───output/
└───R/
└───graphics/
```
We'll use the [SocCaribou](https://github.com/wildlifeevoeco/SocCaribou) project as an example throughout the following sections.
### README
A `README.md` file should always be included and stores plenty of information about the project. Installation instructions, TODOs, description or purpose of the project, authors, news, known bugs or limitations, instructions for contributing, link to license, etc.
For example, the SocCaribou README:
```md
## Space-use and social organization in a gregarious ungulate: testing the conspecific attraction and resource dispersion
[](https://zenodo.org/badge/latestdoi/173167283)
- Authors:
- Mélissa Peignier
- [Quinn M.R. Webber](https://qwebber.weebly.com/)
- [Erin Koen](https://sites.google.com/site/erinlkoen/)
- [Michel P. Laforge](https://mammalspatialecology.weebly.com/)
- [Alec L. Robitaille](http://robitalec.ca)
- [Eric Vander Wal](http://weel.gitlab.io)
This repository contains the code accompanying the paper “Space-use and
social organization in a gregarious ungulate: testing the conspecific
attraction and resource dispersion”. Scripts are under `scripts/` and
reused functions are in `R/`. This project uses standard R package
structure and can therefore be installed with `devtools`. This also
helps declare external package dependencies required for the analysis.
Please note that while functions are included here, they are not tested
for use in other projects and may not be suitable (at least not in their
current version).
## Abstract
Animals use a variety of proximate cues to assess habitat quality when resources
vary spatiotemporally. Two non-mutually exclusive strategies to assess habitat
quality involve either direct assessment of landscape features or observation of
social cues from conspecifics as a form of information transfer about forage
resources. [...]
```
Other examples:
* [`spatsoc` README](https://github.com/ropensci/spatsoc/blob/master/README.md)
* [`bookdown` README](https://github.com/rstudio/bookdown/blob/master/README.md)
* [`rstudio-education/stats545`](https://github.com/rstudio-education/stat545/blob/master/README.md)
More on README's
* [Make a README](https://www.makeareadme.com/)
* [Github's About READMEs](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-readmes)
### Scripts
R scripts can be organized into `scripts/` and `R/`. The `scripts/` folder
holds analysis scripts, often (ideally) numbered in the order they should
be run in. For example, in the SocCaribou project there's `1-Data-Cleaning.R`
then `2-HomeRangeAnalysis.R`. See Jenny Bryan's
[project oriented workflow](https://rstats.wtf/project-oriented-workflow.html).
The `R/` folder is used for functions. Functions help us chunk out
larger project into manageable pieces of code.
[This section](https://books.ropensci.org/targets/functions.html)
of the `targets` manual has a great overview of the two approaches.
It doesn't have to be one or the other - if you have a discrete chunk of code
that needs to be applied multiple times, or might be useful in another project,
etc, just write it as a function and drop it into your `R/` folder. In addition,
the `R/` folder is recognized if you turn your project into a package or a
research compendium as the standard place and structure for functions.
See the [SocCaribou](https://github.com/wildlifeevoeco/SocCaribou) project
that has both an `R/` folder and a `scripts/` folder.
```
SocCaribou
├── R
│ ├── dynamic_network.R
│ ├── hr_network.R
│ └── step_length.R
├── scripts
│ ├── 1-DataCleaning.R
│ ├── 2-HomeRangeAnalysis.R
│ ├── 3-SiteFidelityAnalysis.R
│ ├── 4-SocialNetworkAnalysis.R
│ ├── 5-Randomizations.R
│ ├── 6-MergeTidyFiles.R
│ └── 7-DataAnalysis.R
...
```
### Data
Always start with raw data. Keep raw data raw in a `raw-data/` folder.
Then use scripts to prepare and organize your data -
never modify it by hand. This way, you can go always go back to the raw data in
case anything changes in your preparation steps.
Intermediate and output data can be sorted into `input/` and `output/` folders and
saved as an `.Rds` files using the base R functions:
`saveRDS()` and `readRDS()`. More details in
[Efficient R / Binary file formats](https://csgillespie.github.io/efficientR/input-output.html#binary-file-formats). Or if you use `data.table`, use `fread` and `fwrite` to read/write CSV files.
If your dates are stored in the ISO standard format, they will be automatically
converted to `POSIXct` by `fread`.
## Metadata
Keep track of where the raw data comes from, how it was generated, by who, when,
etc using metadata. See the [`metadata`](https://gitlab.com/weel/metadata)
project. Use this project to write metadata for your data. Talk to Alec about
contributing/using it!
https://weel.gitlab.io/metadata
### Etc
Other elements include:
* LICENSE file - [Choose an open source license](https://choosealicense.com/)
* `graphics/` or `figures/` folder for figures and plots
* `manuscript/` or `paper/` folder for storing the manuscript
* `man/` folder for storing the documentation of your functions
* [Keep a ChangeLog / News file](https://keepachangelog.com/en/1.0.0/). Traditionally in the R community, it is stored in a `NEWS.md` file.
## RStudio projects
Always work within RStudio Projects to avoid `setwd()` hell. If you share an
RStudio Project (`.RProj`) with someone else, they can immediately use it
without changing working directories or paths to files.
Details: [Efficient R / Project Management](https://csgillespie.github.io/efficientR/set-up.html#project-management)
and [Project oriented workflow](https://rstats.wtf/project-oriented-workflow.html)
## Slides {#projects-slides}
[Slides](https://slides.robitalec.ca/git-and-projects.html) and [Resources](https://gitlab.com/robit.a/workshops/-/archive/master/workshops-master.zip?path=git-and-projects)
```{r, echo = FALSE}
knitr::include_url('https://slides.robitalec.ca/git-and-projects.html')
```
## Resources {#projects-resources}
* [Efficient Setup](https://csgillespie.github.io/efficientR/set-up.html) and [Efficient Input/Output](https://csgillespie.github.io/efficientR/input-output.html) in Efficient R
* [Jenny Bryan's What They Forgot](https://rstats.wtf/project-oriented-workflow.html)