-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathACDI_VOCA_R_Policy.Rmd
181 lines (111 loc) · 11.2 KB
/
ACDI_VOCA_R_Policy.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
---
title: "ACDI/VOCA R Policy"
date: "`r Sys.time()`"
output: html_document
---
```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE, warning = FALSE)
r = getOption("repos")
r["CRAN"] = "http://cran.us.r-project.org"
options(repos = r)
```
## RStudio
RStudio is an IDE for the R programming language and is the IDE of choice for ACDI/VOCA for using R. Split into two editions, RStudio for Desktop and RStudio Server, it is an incredibly empowering tool that allows one to use R to its full potential. The different panels in RStudio such as "Environment", "Files", "Help", "History" allows for easy organization and interacting with all the files and objects in your analysis.
Above is what a RStudio set up might look like. You can spend time to position and size each of the panels however you want along with a great many other aesthetical aspects like the code font and color.
## R Projects
Using R Projects is a vital part of keeping your work separately contained with its own working directory, work space, history, and source documents. Instead of cluttering up your environment with multiple objects from multiple projects you can have a number of different projects opened in its own window so things from one project won't interfere with another.
A great resource to get started with R Projects is [here](https://support.rstudio.com/hc/en-us/articles/200526207-Using-Projects).
For a general overview of a project-oriented workflow in R, consult this website (still work-in-progress) [here](https://whattheyforgot.org/project-oriented-workflow.html) written by Jenny Bryan and Jim Hester from R Studio. For a shorter blog post version of the above see [here](https://www.tidyverse.org/articles/2017/12/workflow-vs-script/
).
## GitHub
Now that you have everything organized by using Projects you might want to backup and version control your code and analyses using GitHub. Using GitHub will also allow you to coordinate and collaborate with other analysts on the same project, you will never again have to search your email for "datafile_revised.data" or "final_final_final_draft3.doc"!
A great introduction to switching over to a version control system for your projects can be read [here](https://peerj.com/preprints/3159/).
For connecting your RStudio Project to Git and GitHub check out this [chapter](https://happygitwithr.com/rstudio-git-github.html) of the book, "Happy Git with R" by Jenny Bryan.
## The Tidyverse and Coding Style
The Tidyverse is a set of R packages specifically designed for doing data science. The packages are consistent in their underlying design and structure which makes it very easy to learn. In regards to syntax and coding style, ACDI VOCA follows the [tidyverse style guide](https://style.tidyverse.org/) for consistent development of our code and tools. One of the main strengths of the tidyverse is that the code is very easily readable by a human compared to base R code. Some great examples of this can be seen [here](https://tavareshugo.github.io/data_carpentry_extras/base-r_tidyverse_equivalents/base-r_tidyverse_equivalents.html) in a great webpage that shows how to do something in both base R and the tidyverse!
The best way to get oriented with the tidyverse packages is to go through Hadley Wickham's [R for Data Science](https://r4ds.had.co.nz/) book which is provided online and for free! You can also go visit the Slack group for R4DS [here](https://rfordatascience.slack.com/) to get online help.
Some particular notes on how we write R code:
- For commenting lines out we use ONE `#` whereas if we want to make a comment in the code we use TWO `##`.
```{r, eval=FALSE}
data %>%
select(this, that, everything()) %>%
## Calculate values here:
mutate(nutrition10 = nutrition * 10,
ham_production = ham + production - costs) %>%
## We need to filter by values over 5000:
filter(nutrition10 > 5000) %>%
## No need to arrange by DESC order anymore:
#arrange(desc(nutrition10))
```
- Avoid using `for` loops or the `apply()` family of functions (`sapply`, `lapply`, `vapply`, etc.) and use the `map()` functions from the `purrr` package instead. Note that there is nothing wrong with using `for` loops in R necessarily but we want to keep everything consistent across the codebase.
```{r}
library(tidyverse)
## calculate the mean for 10 observations of a randomly generated normal distribution
1:10 %>%
map(rnorm, n = 10) %>%
map_dbl(mean)
```
- For naming functions and arguments we use snakecase. Ex. `ConnectToMEF()` and `fieldToMod = "Indicators"`.
```{r}
AddThenSubtract <- function(entryNumber, subtractionNumber) {
sum <- entryNumber + 25 - subtractionNumber
sum
}
AddThenSubtract(entryNumber = 5, subtractionNumber = 3.5)
```
## Installing an R Package
There is a tab in R Studio that helps you manage installing packages.
From here you can choose from where you want to install a package, either from CRAN or a local `.tar.gz` or `.zip` file. Then you just type the name of the package in, be very careful with the proper capitalization and underscore/dash in the names! Then, make sure you are installing the package into the proper directory, check whether you want to install dependencies or not and click install. Remember that after installing you need to load the package with a `library()` call every new session.
If you want to install from the console or in a script:
```{r}
install.packages("nycflights13")
library(nycflights13)
## let's look at one of the datasets from our newly installed package!
glimpse(airlines)
```
Not all packages are available on CRAN, here's how you would install a package from GitHub:
```{r eval=FALSE}
remotes::install_github("ACDIVOCATech/bulletchartr")
library(bulletchartr)
```
## Where to find inspiration and HELP!
R is an open-source language with tons of community support online and in print. A great way to read up on the latest R news is to go on Twitter and search for `#rstats`. You should also subscribe to [R Bloggers](https://www.r-bloggers.com/) & [R Weekly](https://rweekly.org/) to get a curated stream of news, blog posts, and tutorials provided by thousands of R users from across the world.
For getting help, go over to [StackOverflow](https://stackoverflow.com) and look up questions tagged with `[r]` and any other R package you might be having trouble with. Another good resource that is solely dedicated to R problems and discussion is [RStudio Community](https://community.rstudio.com/). One can also try asking for help on Twitter via the `#rstats` hash tag as well! There is also the `R for Data Science` Slack ([here](https://www.rfordatasci.com/)) for a more interactive community to get help and learn more about R.
## Create/develop R packages
At ACDI/VOCA we have a whole suite of packages that helps us gather and process data from our databases and output them into a variety of dashboards and visualizations. The [R Packages](http://r-pkgs.had.co.nz/) book by Hadley Wickham is a great and free online resource for those who want to create their own package to help with their analysis or contribute to one of our own existing packages.
When collaborating on packages (this can apply to projects too) it is important to create your own branch alongside the main stream of development. This allows you and others to work in parallel without overwriting each other's work. A good way to organize things is that you leave the main "master" branch alone while everybody
When using an ACDI/VOCA R package, please remember to PULL the latest version from Github from the Github panel in RStudio. When contributing to any of our R packages please create your own branch and when you're done submit a Pull Request to the package authors. For an introduction on contributing to open-source using GitHub, see [here](/~https://github.com/firstcontributions/first-contributions).
### Testing for LEAP packages
We create tests as a way to flag errors and to help prevent future errors whenever we change the code in any one of our packages. Using continuous integration tools such as TRAVIS CI after every commit/push, a whole suite of tests run to check if everything still runs fine with the new changes. As the LEAP packages are all connected to creating assets for the LEAP dashboard, in **each** LEAP package we have an `overall-runs` test file that runs the entire LEAP workflow to make sure all assets can be created for each LEAP project after a change in the code. The `overall-runs` tests run in addition to any of the package-specific tests we might have.
## Working on a ACDI/VOCA repo or package
1. Create a branch with `usethis::pr_init("very-brief-description-#IssueNumber")`
2. Make your changes to the code/documentation/tests.
3. Re-run documentation & re-build the package (Windows: `Ctrl+Shift+D` to rerun roxygen and `Ctrl+Shift+B` to re-build/install the package).
4. Commit your code and make sure you reference the issue in your commit message(s) (check out [this](https://help.github.com/en/github/writing-on-github/autolinked-references-and-urls) for how to do so). Push up to Github.
5. Check TRAVIS to see if your branch passed the tests.
6. If tests pass, you can begin the `Pull Request + Merge` process on the Github repo.
7. If you made multiple commits, instead of just merging via `Merge pull request`, click on the drop-down menu and click on `Squash and merge`.
8. Delete your branch on Github.
9. Pull new version of the Master into the server. If it's a package remember to Install/Rebuild it on the server after you pull it in.
10. Switch back to master on your local RStudio and then delete the branch on your local: `git branch -d name-of-branch`
## Misc
Here are some general best practices that should be followed:
- Inputs into complex functions should be stated explicitly, example: DO THIS: `function(arg1 = x, arg2 = y)` instead of this: `function(x,y)`. It's a bit more annoying, but does help resolve conflicts, especially when working with packages like `ACDIVOCAdataGetter` that are continuously in active development.
- Use `tibble` and `as_tibble` rather than `data.frame` and `as.data.frame`
When you are deleting a table from the database:
1. Use `schemaFinder()` to check that the table is not references by other tables.
2. Run the macro-checker to ensure that it's not in any macros.
3. Delete the table via Access.
4. Check if any related forms have been deleted, including the tile.
## For Admins: how to test pull requests:
1. Git fetch
2. Switch branch to one to test
3. Build Package using “BUILD > MORE > CLEAN AND REBUILD”. Alternatively, use R CMD INSTALL –preclean in console.
4. Run tests (Ctrl + Shift + T). If this passes, continue
5. See if Issue has been resolved. If yes, Merge with Master, and delete branch.
6. Pull Master into the server, turn off PT/GQ runners on crontab, run `Day_Deleter()` and stay vigilant for 30 mins. All should be good.
7. Delete local branch (run `git gc` or `git prune` or `git branch -D branch_name`).