contribution_guide_05-02-2021.Rmd

---
title: "Epi R Handbook: Contributions and style guide"
author: "Neale Batra, version 1.0.1"
date: "Produced `r format(Sys.time(), '%A %d %B %Y')`"
output:
  html_document:
    code_folding: show
    highlight: zenburn
    number_sections: no
    theme: sandstone
    toc: yes
    toc_collapse: no
    toc_depth: 3
    toc_float: yes
    #css: !expr here::here('css', 'style.css')
---


```{r setup, include=FALSE}
# THIS SETUP CHUNK IS NOT NEEDED IN YOUR PAGE
# This chunk is already at the very top of the handbook and sets default settings for figures, pixels, warnings, errors, etc.

knitr::opts_chunk$set(echo = TRUE,
                      collapse = TRUE,
                      fig.width = 8,
                      fig.height = 6,
                      dpi = 150,
                      warning = FALSE,
                      message = FALSE)
```


```{r klippy, echo=FALSE, include=TRUE}
# THIS CHUNK IS NOT NEEDED IN YOUR PAGE
# This chunk is at the top of the handbook and enables the clipboard feature throughout the whole handbook

# Enables "copy to clipboard" icons   https://rlesur.github.io/klippy/articles/klippy.html
klippy::klippy(position = c('top', 'right'))
```




<!-- ======================================================= -->
<!-- ======================================================= -->
<!-- ======================================================= -->
# Thanks for being here! {#overview .tabset .tabset-fade}

Everyone working on this project is doing so in their free time, so we appreciate whatever contributions you can offer, especially:  

* Writing or co-writing a page of the handbook  
* Offering edits or improvements to a page  
* Proof-reading a page for readability  
* General advice to core team about content and direction  


*This is a collaborative project. Any contributions you make are offered to the Core Team and subject to editorial changes. So please don't be offended if your code, content, or wording is changed or even removed in the process. We welcome hearing your point of view regarding any changes you disagree with.*  

Thanks for helping others leverage R for epidemiology and other good works!


<!-- ======================================================= -->
<!-- ======================================================= -->
<!-- ======================================================= -->
# Style and Mechanics of Contribution {#overview .tabset .tabset-fade}






<!-- ======================================================= -->
## Objectives and Audience(s)

**The problem:**  

* Field epidemiologists often work in low internet-connectivity environments and have limited technical support from HQ
* Epis learning or new to R often must Google and skim dozens of forum pages to complete common data manipulation and visualization epi tasks
* Most online R help resources are not task-centered nor epidemiology-focused

**Our objective**:  

**To make available a handbook covering common epidemiological tasks and outputs, with clear explanations, step-by-step instructions, and code examples.** We are *not* looking to reinvent the "how to learn R" wheel, but rather to be a reference book specifically for epidemiologists, which, if needed, can be downloaded offline and used in a setting or field deployment with poor/no internet access.  

**Audiences:**  

*Primary audience:*  Field epis and applied epidemiologists - urgently needing R code to modify in order to execute a task  

  * Those learning R and code-based workflows  
  * Those who know other software (STATA, SAS...) but need equivalent code in R  
  * Those working in poor-connectivity environments where extensive Google searching may be frustrating or impossible  
  * ...with written language that is simple and can be understood by non-native English speakers

*Secondary audience:*  Research, Governmental, and University epidemiologists, particularly:  

  * Those at institutions transitioning to using R  






<!-- ======================================================= -->
## Style

In your code, please maintain [tidyverse style](https://style.tidyverse.org/) as much as possible. A few key principles:  

* Most of the guidelines below can be broken, use your judgement
* In text, be concise, precise, and *avoid* abbreviations, contractions, and country-specific phrases  
  * Make all package names **bold** (e.g. **dplyr**) and functions in code-text with parentheses (e.g. `mutate()`)  
  * Bullets are nice and easy to read  
* Explanations should not rely on websites - users may be offline; links can be included but should not be required viewing  
* Prioritize using packages and functions that are *stable*, *commonly-used*, and do not require additional downloads  
* Use lots of `# comments` to explain the code to a beginner - be concise and previse please!  
* When using a function for the first time in a page, indicate its package in the accompanying text, or in code like `dplyr::mutate()`  
* Make use of magrittr pipes and dplyr verbs whenever practical  
* When making assignments, use `<-`, NOT `=`  
* Object names should use underscores such as `my_data`, NOT `my.data`, `mydata`, nor `myData`  
* Use *spaces* liberally, e.g. between almost everything  
* Avoid nesting functions within each other horizontally  
* Prefer code that is *vertically longer* and with appropriate **indents** and generally put a series of pipes on different lines  

For example, if arguments to a function do not all fit on one line, put each argument on its own line and indent:  

```{r, eval=F}
# an example from the handbook
linelist <- linelist %>% 
  mutate(new_var_dup    = id,                  # new variable - replicate another variable
         new_var_static = 7,                   # new variable - all values the same
         new_var_static = new_var_static + 5   # you can modify a variable multiple times
         new_var_calc   = (age / 12) + months  # new variable - calculation
         new_var_paste  = paste0(district, "(", province, ")") # new variable - pasting together values

```

And when piping an object through a series of changes:  

```{r, eval=F}
# Good
iris %>%
  group_by(Species) %>%
  summarize_if(is.numeric, mean) %>%
  ungroup() %>%
  gather(measure, value, -Species) %>%
  arrange(value)

# Bad
iris %>% group_by(Species) %>% summarize_all(mean) %>%
ungroup %>% gather(measure, value, -Species) %>%
arrange(value)
```

### Naming R code chunks  

In an Rmarkdown, code chunks can be named by putting a one-word name directly after the "r" that created the chunk, such as `basics_functions_argument`. Then after a comma after the chunk name you can add the other chunk settings.  

In this handbook, **avoid code chunks because they must be unique across the WHOLE handbook If there are duplicates it will prevent knitting!**  






<!-- ======================================================= -->
## Rmarkdown  


Please use this [cheatsheet](https://rstudio.com/wp-content/uploads/2015/02/rmarkdown-cheatsheet.pdf) to remind yourself of how to write good Rmarkdown (bullets, tables, headers, etc.)





<!-- ======================================================= -->
## Using Github and R to contribute

Here is an [online guide](https://happygitwithr.com/rstudio-git-github.html) to using Github and R. Some the below text is borrowed from this guide.  

### Overview of GitHub  
Github is a website that supports **collaborative projects** with **version control**.  In a nutshell, the project's files exist in the **Github repository** as a **"master"** version (called a **"branch"**). If you want to make a change to those files you must create a different branch (version) to build and test the changes in. Master remains unaffected by your changes until your branch is **merged** (after some verification steps) into the master branch. A **"commit"** is the saving of a smaller group of changes you make within your branch. A **Pull Request** is your request to merge your changes into the master branch.  

The way RStudio and Github interact is as follows:  

* There is a REMOTE version of the `Epi_R_handbook` R project that lives on Github website repository - master and other branches all exist and are viewable on this Github repository. Pull requests, issue tracking, and de-conflicting merges happens online here.  
* On your LOCAL computer, you **clone** a version of the entire Github repository (all the R project files, from *all* its branches/versions). Locally, you can make changes to the files of any branch and "commit" those changes (save them with an explanatory note). These changes are only stored locally on your computer until...  
* Your LOCAL repository/Rproject interacts with the REMOTE one by 1) **pulling** (updating local files from the remote ones of the same branch) and **pushing** (pushing local changes to the same branch of the remote repository)  
* The software *Git* on your computer underlies all this, and is used by RStudio. You don't have to interact with Git except *through* RStudio. While you can write Git command-line into the RStudio terminal, it is easier to just interact with Git through RStudio point-and-click buttons. As noted below, you may *occasionally* have to write Git commands in the RStudio terminal.  


```{r echo=F, out.width = "75%", out.height="75%", fig.align = "center"}
knitr::include_graphics(here::here("images", "GitHub-Flow.png"))
``` 
*Image [source](https://build5nines.com/introduction-to-git-version-control-workflow/)*


### First steps

1) **Register** for a free account with Github 
2) **Have R and RStudio** installed/updated  
3) **Install Git** to your computer (remember Git is a software on your computer accessed by RStudio, Github is a website)  
4) **Familiarize yourself** to the Github workflow by [reading about it](https://guides.github.com/introduction/flow/)  
5) **Become a contributor** to the [Epi_R_handbook Github repository](https://github.com/nsbatra/Epi_R_handbook) (email neale.batra@gmail.com)
6) **Clone** the Github repository to your computer  
     * In RStudio start a new project *File > New Project > Version Control > Git*  
     * In “Repository URL”, paste the URL *https://github.com/nsbatra/Epi_R_handbook.git* (link also available from repo main page, green "Code" button, HTTPS)
     * Accept the default project directory name `Epi_R_handbook`  
     * Take charge of – or at least notice! – where the Project will be saved locally  
     * Check "Open in new session" and click "Create project"  
     * You should now be in a new local RStudio project that is a clone of the `Epi_R_handbook` repository on Github
     
In your RStudio you will now have a Git tab in the same tab as your R Environment: 


```{r echo=F, out.width = "75%", out.height="75%", fig.align = "center"}
knitr::include_graphics(here::here("images", "Git_console.png"))
```  
Please note the buttons circled as they will be referenced later (from left to right):  

* Button to begin "commiting" your changes to your branch (will open a new window)  
* Arrows to PULL (update your local version of the branch with any changes to made your branch by others) and to PUSH (send any completed commits stored in your local version of the branch to the remote/Github version of your branch)  
* The Git tab in RStudio  
* Button to create a NEW branch of whichever version is listed to the right. **You almost always want to branch off of the master (after you PULL to update the master first)**.  
* The branch you are currently working in.  
* Below all this, changes you make to code or files will begin to appear  

### **To work on your Handbook page:**  

*Note: Last I heard, Github will soon change their terminology of "master" to "main", as it is an unnecessary reference to slavery*  

1) **Create a branch**  


* **Be in master branch** and then click the branch button/icon.  
* **Name your branch** with a one-word descriptive name (can use underscores if needed). You will see that locally, you are still in the project Epi_R_handbook, but you are no longer working on the master branch. Once created, the new branch will also appear on the Github website as a branch.  
*  **Make your changes**... to files, code, etc. Your changes are tracked.  
* **Commit the changes**. Every series of changes you make that are substantial (e.g. adding or updating a section, etc.), stop and *commit* those changes. Think of a commit as a "batch" of changes related to a common purpose.  
     * Press "Commit" in the git tab, opens new window  
     * Review the changes you made (green, red etc.)  
     * Highlight all the changes for the commit and "stage" them by checking their boxes or highlighting all the rows and clicking "stage all"  
     * Write a commit message that is short but descriptive (required) 
     * Press "commit" on the right side  
* Make and commit more changes, as many times as you would like  
* **PULL** - click the PULL icon (downward arrow) which updates the branch version on your local computer with any changes that have been made to it and stored in the remote/Github version  
     * PULL often. Don't hesitate. **Always pull before pushing**.  
* **PUSH** your changes up to the remote/Github version of your branch.  
     * You may be asked to enter your Github username and password.  
     * The first time you are asked, you may need to enter two Git command lines into the *Terminal* (the tab next to the R Console):
        * **git config --global user.email "you@example.com"**   (your Github email address), and  
        * **git config --global user.name "Your Github username"**  
     


2) **Request to merge your branch with master**  

Once done with your commits and pushed everything up to the remote Github repository, you may want to request that your branch be merged with the master branch. 

* Go to Epi_R_handbook Github repository  
* Use the branch drop-down to view your branch, not master
* At top you will see green button saying "Compare and Pull Request" for your branch. If not, look for another button that says pull request.
* Write a detailed comment and click "Create Pull Request"
* On the right, request a review from members of the project's core team. You need at least one review to be able to complete the merge.
* Once completed, delete your branch as explained below

3) **Delete your branch on Github**  

GO to the repository on Github and click the button to view all the branches (next to the drop-down to select branches). Now find your branch and click the trash icon next to it. Read more [here](https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/creating-and-deleting-branches-within-your-repository#deleting-a-branch)  

Be sure to also delete the branch locally on your computer:

* From RStudio, make sure you are in Master branch
* Switch to typing in the "terminal" (tab adjacent to the R console), and enter this: **git branch -d branch_name** , where "branch_name" is the name of your branch to be deleted  
* Refresh your Git tab and this branch should be gone.


**TEST IT**
You can test your ability to make changes, commits, pull requests, etc. by modifying this R script which is saved to the main Rproject folder: `test_your_abilities.R`


**Asked to provide password too often??**  
Instructions for connecting to the repository via a SSH key (more complicated): 
See chapters 10 and 11 of [this tutorial](https://happygitwithr.com/credential-caching.html#credential-caching)






<!-- ======================================================= -->
<!-- ======================================================= -->
<!-- ======================================================= -->
# Contributing content {#template .tabset .tabset-fade}

Here is an overview of how the handbook works:  

**Each page is stored within its own Rmarkdown file in the "new_pages" folder of the R project.**  

* Each page must begin with a first-level header (one #) that will become the chapter header.  
* You can make a new page using the file `_template.Rmd`.  

**To "render" a single page, or the entire book, use the *"bookdown_runfile.R"***  

* This contains commands you can run to properly create the entire book, or just one chapter. See this file for more details.  
* There are two versions of the handbook:  
  * Online version which is a "bookdown" of the "bs4" style - this looks really nice and has a great cross-book search function, but (at the moment) cannot be a stand-alone self-contained html file. So it is for online only.  
  * Offline version which is a "tabbed" html document - this has a ToC only on the right and the tabs don't work as nicely with the ToC. Also the search function doesn't exist and Ctrl+F only searches active tabs. But it is a self-contained html file and could be used offline.  
  * The commands reference other files which contain the list of pages to render and other settings; *"_bookdown.yml"* for the whole book and *"_small_bookdown.yml"* if you only want to render one or a few pages.  


Test your page routinely by rendering it. Then test rendering the entire handbook on your local cloned repo. If your page is breaking the handbook and you can't resolve it, alert the core team and temporarily put a # next to your page in "_bookdown.yml", so it does not stop the knitting of the entire handbook.  

Once you push your changes up *and a rendered handbook* to your online branch, and the branch is reviewed/approves/merged, then your changes will be reflected in the handbook website!




<!-- ======================================================= -->
## How to add a page  

1) In the R project, go to the "new_pages" subfolder  
2) Open the file `_template.Rmd`, save it under a different, *concise* name *using underscores* for spaces  
3) Read the template and edit/add content  


<!-- ======================================================= -->
## General page structure

We have elected to utilize sections/tabs in each page for organization.

Have several sections/tabs in your Handbook page, generally structured as follows (*There are very few hard rules - the structure below can be disregarded if a good argument can be made otherwise*):  

**Overview tab** - Must be called "Overview". Can just contain a bit of intro text describing the objectives of the page. You can also include a graphic to demonstrate graphics or skills what the page will explain. This is so when a user is scrolling down the offline version, it will catch their eye. If you include a graphic here, please be considerate and shrink it to a reasonably small size. Think of it as a thumbnail.  

**Preparation tabs** - If your page involves loading special packages, data import, cleaning, or other set-up steps, please put them in a "Preparation" tab. Feel free to add sub-tabs if necessary to break up the steps - use your judgment. We don't want sections/tabs to get too long that they require lots of vertical scrolling. Particularly in these steps, **explicity show data transformations to the user** - when melting, spreading, or otherwise making major changes to data in your page. These points are where beginners often get lost. Use the command below as often as necessary to show your dataset and its transformations:  

```{r, eval=F}
DT::datatable(linelist, rownames = FALSE, filter="top", options = list(pageLength = 5, scrollX=T))
```

**Different approaches** - Please aim to offer two tabs showing two approaches to completing the task/plot.  

1) The first approach should be simple and fast. For example, using a specialized package such as **apyramid** to make an age pyramid.  
2) The second approach should offer more complexity using packages that are more customizable. Alternatively, this can be a more basic approach using **base** R or ggplot, for example.  

Consider that we want to emphasize packages/approaches that are **tidyverse-oriented, stable, documented, and have fewer dependencies**.  

**Resources tab** - Here you can link to online or other resources on the subject. Be sure to properly cite and attribute any tutorials or vignettes you leveraged in writing your page. Do not plagarize!  



### An example  

A possible tab and sub-tab structure for page on age pyramids:  

* Overview  
  * How to read an age pyramid  
  * Teaser image of an age pyramid  
* Preparation  
  * Load Packages  
  * Load linelist data  
  * Set parameters  
  * Clean age and gender variables  
  * make age groups
* Using the apyramid package  
  * Simple version, argument 
  * With aesthetic themes  
  * Dealing with missing values
* Using ggplot()  
  * Set-up 
  * With aesthetic themes
  * Flipping axes
* Using aggregated data  
  * Preparation  
  * Make plot with ggplot()
* Other uses for age-pyramid style visualizations  
  * Comparison of variables other than age and gender  
* Resources  
* Source  `page_closeout.Rmd` to return datasets to their default state


<!-- ======================================================= -->
## Making tabs

Here is an example of how a cascade of headers/tabs looks in the handbook:  
A **Level 1 header** (`# R Basics`) with a **Level 2 header** tab (`## Operators`), and below that several **Level 3 header** tabs (`### Relational and Logical Operators` and `### Missing Values`). Note how the first level of tabs looks slightly different (not "pilled") than the second level of tabs ("pilled").  


```{r basics_objects_structures, echo=F, out.width = "80%", out.height="80%", fig.align = "center"}
knitr::include_graphics(here::here("images", "template_example_tabs.png"))
```  


Below is the code structure of these tabs (code for all the tabs not shown for simplicity). A few things to note:  

* The **3 dashed lines** are used for **Level 1 headers** only and signify start of a new handbook page. They are not necessary, but assist us writers visually when we quickly skim the Rmarkdown handbook.  
* Inside the curly brackets after the header name is an *optional* single-word tag `{#rbasics}` (hash with no following space). It can be used to create internal links within the handbook. **Do not put a tag in the first-level header at the top of the page - it will stop the bookdown rendering**.  

* Also in the brackets `{ }` are arguments that create the tabs that appear in the offline version: ` .tabset .tabset-fade`, which create tabs that are not "pilled" in appearance.  
* The level 2 and 3 headers have only one dashed line, to distinguish from the 3 lines of a new handbook page  



```{r, eval=F}

<!-- ======================================================= -->
<!-- ======================================================= -->
<!-- ======================================================= -->
# R Basics { .tabset .tabset-fade}

(Other handbook pages can have internal links to this page using the tag #rbasics)




<!-- ======================================================= -->
## Operators {#operators .tabset .tabset-fade}

(This is a section/tab of R basics)
(this tab has a tag so that other handbook pages can have internal links to it using the tag #objects)
     
This section details operators in R, such as ...  
     




<!-- ======================================================= -->
### Relational and logical operators  

(This is a sub-tab of Operators)
 
**Relational operators compare values** and are often used when defining new variables and subsets of datasets. Here are the common relational operators in R ...





<!-- ======================================================= -->
### Missing Values
(This is also a sub-tab of Operators)

**In R, missing values are represented by the special value `NA`** ...
```




<!-- ======================================================= -->
## Packages

The `load_core_packages.R` in the root folder loads the few packages that are used throughout most pages. This is sourced by the `intro.Rmd` page(for the entire handbook) and by `page_setup.Rmd` (for when pages are knitted individually).  

Within your page:  

* Have a chunk visible to the user in which you load any packages, and explain the use of any packages in the text. Depending on the circumstances, it may make sense to put this is the *preparation* tab, or in the subsequent tabs detailing the steps.  
* On each page, make sure it would be clear to a beginning which functions come from which packages. Do not be afraid to use double-colons such as `dplyr::n()` or describe the package using **bold face** in the accompanying text.  


When choosing a package to use, please use the following list:  
* Prioritize **stringr** over `paste0()` (use `str_glue()`, `str_detect()`, etc.)  
* Prioritize **lubridate** over **aweek**  
* See the style and editorial decisions page of the handbook for more guidelines  




<!-- ======================================================= -->
## Notes/Tips/Cautions/Warnings

Use notes, tips, caution, and danger warnings - the code to produce these is below:  

```
FOR EXAMPLE: This is a boxed example, 
created by three tickmarks above and below

```

<span style="color: black;">**_NOTE:_** This is a note</span>

<span style="color: darkgreen;">**_TIP:_** This is a tip.</span>

<span style="color: orange;">**_CAUTION:_** This is a cautionary note.</span>

<span style="color: red;">**_DANGER:_** This is a dire warning.</span>

Here is the code to produce these:  

```{r, eval=F}
#```
FOR EXAMPLE: This is a boxed example,
created by three tickmarks above and below (without the hashes before the tickmarks shown here)

#```

<span style="color: black;">**_NOTE:_** This is a note</span>


<span style="color: darkgreen;">**_TIP:_** This is a tip.</span>


<span style="color: orange;">**_CAUTION:_** This is a cautionary note.</span>


<span style="color: red;">**_DANGER:_** This is a dire warning.</span>

```




<!-- ======================================================= -->
## Datasets

Most pages should use the `linelist_cleaned.rds` file available in the "data" folder. Import it using `rio::import()`. YOu may have two lines of import - one visible to the reader (`rio::import("linelist_cleaned.rds")`) set to `eval=F` and one which actually runs that uses **here** (`rio::import(here::here("data", "linelist_cleaned.rds")`).  

The cleaning on `linelist_cleaned.rds` is done in the cleaning handbook page. Also note that the raw dataset can be edited from the `make_evd_dataset.R` script in the data folder.  

```{r, eval=F}
# import aggregated case counts of disease X
district_count_data <- rio::import(here::here("data", "linelist_cleaned.rds"))  
```

(here() is a very useful tool to implement file paths relative to a designated root folder in an R project)




<!-- ======================================================= -->
## Add images and external links

Use code like this to add a static image or a GIF. The image must be saved in the R project's "images" folder.  
```
Use the code chunk below to add a graphic (which is saved to the "images" folder)
Obviously, delete the hash symbols - those are just to allow me to show this here in the tutorial

# ```{r eval=F, out.width = "80%", out.height="80%", fig.align = "center"}
# knitr::include_graphics(here::here("images", "template_example_tabs.png"))
# ```  
```

To add a link to a website, use this code:  

```{r, eval=F}
This is the text in my Rmarkdown, and I want the viewer to go to [this website](full.website.address.com)
```




<!-- ======================================================= -->
## Links between handbook pages

You have several options:  

* (preferred) Put the full correct name of the page in `[exact page name]` brackets. This will link to the page.  
* Put an alternate name in brackets, followed by the real name also in brackets `[text][exact page name]`
* Link to a specific section, assign the section a tag in the curly brackets `### Heading {#tag .unnumbered}`  and then link to it with `[text](#tag)` (note: no space after the hash symbol.  



```{r, eval=F}
**The Environment RStudio Pane**  
This pane, by default the upper-right, is most often used to see brief summaries of objects in the R Environment in the current session. These [objects](#objects) could include imported, modified, or created datasets, parameters you have defined (e.g. a specific epi week for the analysis), or vectors or lists you have defined during analysis (e.g. names of regions). Click on the arrow next to a dataframe name to see its variables. 
```




## Render the book or a chapter

See the bookdown_runfile.R in the root folder. There are commands to run to produce bs4 bookdown (the whole book or just the pages in _small_bookdown.yml). Also a command to produce the offline version (html_document2). If doing offline, it will output as _main.html in the root folder. Once complete, manually copy and paste this file into the "offline_long" folder and save with the same exact file name as the older version there. Also remember that the page order and inclusion for the offline is defined in a separate yml so check that it is up-to-date with the online version yml.  

To run just one or a few pages , edit the contents of _small_bookdown.yml and then run the appropriate bs4 command in bookdown_runfile.R. At least in Neale's experience, something the first time you run the "small" command to render in an R session, it will begin to run the entire book. So be prepared to watch it, hit the stop button, and run the command again (which will work).  



<!-- ======================================================= -->
<!-- ======================================================= -->
<!-- ======================================================= -->
# Project Management {#projectmgmt .tabset .tabset-fade}

Ask a member of the core editorial team if you have questions.