contribution_guide.Rmd

---
title: "Template for contributions and style guide"
author: "Neale Batra, version 1.0.0"
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, **if you chose to named chunks, ensure that each one is unique! If there are duplicates it will prevent knitting!**. If you use chunk names, use three-part names with underscores, as in the example above. The three parts should be shorthand for the page, the tab, and the chunk topic respectively. So `basics_functions_arguments` is a chunk in the R Basics page, in the tab about functions, and the chunk is teaching about use of arguments.  








<!-- ======================================================= -->
## 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}

**Each page is stored within its own Rmarkdown file in the "pages" folder of the R project.** You can make a new page using the file `_template.Rmd`. The outputs html outputs will save into the "_outputs_knitted" folder.  

Each page can be knitted on its own, as in this case the page will source the `_page_setup.Rmd` file to load the datasets and default settings.  

To produce the whole handbook, the file `handbook_combined.Rmd` contains many chunks which each source/run one of the page scripts in the "pages" folder, combining them all into one Rmarkdown html document.  

* If you want to work on your page: open it, run the script `_page_setup.R` and edit your page, then knit your page individually and examine your work, and make sure it is included as a chunk within `handbook_combined.Rmd`.  
* If you want to knit the entire handbook, knit `handbook_combined.Rmd`.  

Test your page routinely by knitting it. Then test knitting the entire handbook on your local cloned repo. If your page is breaking the handbook (the knitting of `handbook_combined.Rmd`) and you can't resolve it, alert the core team and temporarily put `eval=F` next to your page's chunk, so it does not stop the knitting of the entire handbook.


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

1) In the R project, go to the "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 tabs in each page, in order to make the handbook easier to scroll through, and so that sub-pages are more visible when the user glances at the contents of a page.  

Have several 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*):  

**`_page_setup`** - This chunk only runs if the page is being knitted independently from other pages. If run, it sources the `_page_setup.R` script which loads the datasets.  


**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, 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 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, 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.  

**`_page_cleanup`** - Lastly, there is a chunk that sources the `_page_cleanup.Rmd` script, which sets the datasets back to their default values.  


### 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.  
* Also in the brackets `{ }` are arguments that create the tabs:  
     * **Level 1 Headers** use two: ` .tabset .tabset-fade`, which create tabs that are not "pilled" in appearance.  
     * **Level 2 Headers** *that contain sub-tabs* use three: `{.tabset .tabset-fade .tabset-pills}`, the last of which makes the tabs "pilled" in appearance (to distinguish more visually the types of tabs)  
* The level 2 and 3 headers have only one dashed line, to distinguish from the 3 lines of a new handbook page  
* The level 2 headers, in order to appear in the Table of Contents, have an extra line like this `<h2> Operators </h2>` just above the header. A bug caused by using tabs means that level 2 headers that are a tab do not appear in the ToC. This line fixes that. We don't include level 3 headers in the ToC.  


```{r, eval=F}

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

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




<!-- ======================================================= -->
<h2> Operators </h2>   (having this line ensures that a Level2 header in a tab appears in the Table of Contents)
## Operators {#operators .tabset .tabset-fade .tabset-pills}

(This is a tab of R basics, with the tab appearance not "pilled")
(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, with "pilled" tab appearance because `.tabset-pills` is included in the `{}` of its parent tab)
 
**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 a sub-tab of Operators, also with "pilled" tab appearance because `.tabset-pills` is included in the `{}` of its parent tab)

**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 subsequne 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.)  
*  
*  



<!-- ======================================================= -->
## 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 can 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

This is experimental and not really working yet, we think partly because of the tabs... if you have a better solution please let us know...  

To link between handbook pages, use the "tag" of the section (note: no space after the hash symbol. For example, this sentence uses the tag `#objects` to link a section about RStudio to the section on Objects. The tags are set in brackets after the header e.g. `## Objects {#objects}`

```{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. 
```




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

Each handbook page should have its own **Github project**. You may need to create this by going to the Projects Github page, clicking "New Project", fill in the details with the primary author and co-authors working on the page, and use the template called "Automated Kanban with reviews".  

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