03 - R Markdown.Rmd

---
title: 'Lesson 3: Getting cozy with R Markdown'
output:
  html_document:
    df_print: paged
  pdf_document: default
---

```{r setup_2, include=FALSE}
knitr::opts_chunk$set(echo = TRUE)
```

## Why integrate your analysis and documentation in one place?

The short answer is that it will be easier for you to understand what you did and easier for anyone else to understand what you did when you analyzed your data. This aligns nicely with the principles of reproducible research and is arguably just as important for any analysis that occurs in a clinical laboratory for operational or test validation purposes. The analysis and the explanation of the analysis live in one place so if you or someone else signs off on the work, what was done is very clear.

The more philosophical answer to this question lies in the principles of [literate programming](https://en.wikipedia.org/wiki/Literate_programming), where code is written to align with the programmer's flow of thinking. This is expected to produce better code because the program is considering and writing out logic while they are writing the code. So the advantages lie in both communication of code to others, and that communication is expected to produce better programming (analysis of data in our case).

There is another advantage of using this framework with the tools we discuss below: the output that you generate from your analysis can be very flexible. You can choose to show others the code you ran for the analysis or you can show them only text, figures, and tables. You can produce a webpage, a pdf, a Word document, or even a set of slides from the same analysis or chunks of code.

## Basics of knitr and rmarkdown

The theme of the course so far is "there's a package for that!" and this of course is no exception. The [knitr package](https://yihui.name/knitr/) and closely related [rmarkdown package](https://cran.rstudio.com/web/packages/rmarkdown/index.html) were built to make it easier for users to generate reports with integrated R code. The package documentation is very detailed but the good news is that RStudio inherently utilizes [knitr and rmarkdown](http://rmarkdown.rstudio.com/authoring_quick_tour.html) to "knit" documents and allows for a simple, streamlined workflow to create these documents.

There are 3 components of a typical R Markdown document:

- header
- text
- code chunks

### Header

The header includes metadata about the document that can help populate useful information such as title and author. This information is included in a YAML (originally *Yet Another Markup Language*, now *YAML Ain't Markup Language*) format that is pretty easy to read. For example, the header for this document is:
```{r, eval = FALSE}
---
title: 'Lesson 3: Getting cozy with R Markdown'
output: html_notebook
---
```

The output field dictates the output once the document is knit, and users can add other data such as the date or even [parameters](http://rmarkdown.rstudio.com/lesson-6.html) for a report.

### Text

Text is written in whitespace sections using [R Markdown syntax](http://rmarkdown.rstudio.com/authoring_basics.html), which is a variant of a simple formatting language called markdown that makes it easy to format text using a plain text syntax. For example, asterisks can be used to *italicize* (`*italicize*`) or **bold** (`**bold**`) text and hyphens can be used to create bullet points:
```{r, eval = FALSE}
- point 1
- point 2
- point 3
```

- point 1
- point 2
- point 3

The text sections of your notebook can be organized into sections like a document you would create in software like Microsoft Word. There are multiple levels of headers available and syntax is simple: `# Header 1` on it's own line will create a section of the document. Under that header multiple subsections can be built with a similar syntax - just add more `#` signs to create the next level header: `## Header 2`. For the header to work, it should be on its own line.

Let's practice making modifications to the document in the header and the text.

**Exercise 1**

Let's use the built-in functionality in RStudio to create an R Notebook and make some modifications.

1. Add a file by selecting the add file button on the top left of your screen
1. Select R Notebook as the file type
1. Find the header. Change the title of the notebook to "My First R Notebook"
1. Add your name as the author by adding another line to the header: `author: "Your Name"`
1. Add a second level heading (##) at the end of the notebook called “My Calculation”

**End Exercise**

### Code chunks

Interspersed within your text you can integrate "chunks" of R code, and each code chunk can be named. You can supply certain parameters to instruct R what to do with each code chunk. The formatting used to separate a code chunk from text uses a rarely utilized character called the backtick ` that typically can be found on the very top left of your keyboard. The formatting for a code chunk includes 3 backticks to open or close a chunk and curly brackets with the opening backticks to supply information about the chunk. Here is the general formatting, including the backticks and the curly braces that indicate the code should be evaluated in R:  
  
  
    ```{r, eval = FALSE}
    mean(c(10,20,30))
    ```
  
And this is how the code chunk looks within a document by default:
```{r, eval = FALSE}
mean(c(10,20,30))
```

There are shortcuts for adding chunks rather than typing out backticks: the Insert Code Chunk button near the top right of your script window (green button  with a plus C) or the `Ctrl+Alt+i`/`Command+Option+i`(Windows/Mac) shortcut. As with inserting a chunk, there are multiple options for running a chunk: the `Run` button near the top right of your script window or the `Ctrl+Shift+Enter`/`Command+Shift+Enter` (Windows/Mac) shortcut. Within a code chunk, if you just want to run an individual line of code, the `Ctrl+Enter`/`Command+Enter` (Windows/Mac) shortcut while run only the line your cursor is currently on.

In addition code can be integrated within text by using a single backtick to open and close the integrated code, and listing "r" at the beginning of the code (to indicate the language to be evaluated). Including "r mean(c(10,20,30))" surrounded by backticks will produce the following output: `r mean(c(10,20,30))`.

**Exercise 2**

Let's practice working with code chunks with an R Notebook.

1. Within the notebook you created in Exercise 1, find the grey code chunk. Press the green play button on the top right of the chunk. What happened? Alternately, if you cursor is within a code chunk, you can hit `Ctrl+Shift+Enter`/`Command+Shift+Enter` and the code inside the chunk will execute.
1. Insert a code chunk under the cars code chunk by using the `Ctrl+Alt+i`/`Command+Option+i`(Windows/Mac) shortcut. Another option for adding a code chunk is to use the Add Code Chunk button on the top right of the Editor window (green button with a plus sign and a C).
1. Using the new code chunk you created, display the first lines of the cars data frame with the `head(cars)` command and execute the code chunk

**End Exercise**

A helpful tip: use your first code chunk as a setup chunk to set output options and load packages you will use in the rest of the document. The `knitr::opts_chunk$set(echo = TRUE)` command in the setup chunk tells R to display (or echo) the source code you write in your output document. A detailed list of various options can be found under the R Markdown cheatsheet here: https://www.rstudio.com/resources/cheatsheets/.

## Flexibility in reporting: types of knitr output

Under the hood, the knitting functionality in RStudio takes advantage of a universal document coverter called [Pandoc](http://pandoc.org/) that has considerable flexibility in producing different types of output. The 3 most common output formats are .html, .pdf, and Microsoft Word .docx, but there is additional flexibility in the document formatting. For example, rather than creating a pdf or html file in a typical text report format, you can create slides for a presentation.

Now let's knit this file and create some output.

**Exercise 3**

1. Click the **Knit** button
1. You are being prompted to save the .Rmd file. Choose the "src" folder of your project and name the file sample_markdown_document
1. RStudio should produce output in .html format and display
1. Click the Open in Browser window and the same output should open in your default internet browser
1. If you find the folder you saved the .Rmd file there should also be a .html file you can open as well
1. Now, instead of hitting the **Knit** button, select the down arrow adjacent to it and click Knit to Word

**End Exercise**

Documents can be knitted to a pdf format as well, but this requires the installation of a package called [tinytex](https://yihui.org/tinytex/) if you don't already have LaTeX (a document preparation language).

The add file options also allow you to create a presentation in R Markdown. This can be a handy alternative to Powerpoint, especially if you want to share code and/or many figures within a presentation. You can find more information about these presentations and the syntax used to set up slides at the RStudio site on [Authoring R Presentations](https://support.rstudio.com/hc/en-us/articles/200486468-Authoring-R-Presentations).

**Exercise 4**

The course repository that your forked and opened as an RStudio project has multiple R Markdown files that contain the course content. If not already open, open up the lesson 3 file: "03 - R Markdown.Rmd".

In addition to the lesson text documents, there are a few folders that each of these documents refer to. 

The "assets" folder contains images and other files that can be pulled into your R Markdown document. Let's practice embedding an image into your document. The syntax for incorporating an image is `![text for image caption](folder_name/image_file.ext)`. Practice embedding the "git_basic_workflow.png" diagram from the assets folder in the space below:

Now knit the lesson 3 document to whatever format you'd like and open it.

<!---
Note: updated repo to include all course data
The "data" folder contains some of the data needed to complete future exercises but is incomplete due to file size limitations on GitHub. Prior to class, we requested that your download data for some exercises from a separate site. To continue with the future exercises seamlessly, please place those files (just the files, not the folder) into the "data" folder.

With that step, the subsequent exercises should contain the data and appropriate links to run without a great deal of additional work.
--->

**End Exercise**

These steps have set up your directory structure for future lessons. We have pre-made lesson files for future lessons, but it is also may be helpful to create an independent R Markdown file for any additional code you might want to write outside of the lesson.

## A word of warning on notebooks

Running chunks in an R Markdown document can be really helpful. Similarly to working in the Console, you can write some code, execute it, and get quick feedback, all while having documentation wrapped around your code. However, there is a problem to running code chunks in notebook mode. The environment can change dynamically if you run different chunks at different times, which means that the same code chunk can produce different answers depending on the sequence you run chunks, or if you do additional work in the Console.

How do you avoid getting the wrong answer? One suggestion is to build a step in to periodically knit the whole document and review the output. Running the entire document should produce consistent results every time. Be aware of this issue and try to knit the document at least before the end of every session with an R Markdown document.

There was a [JupyterCon presentation](https://docs.google.com/presentation/d/1n2RlMdmv1p25Xy5thJUhkKGvjtV-dkAIsUXP-AL4ffI/edit#slide=id.g3d168d2fd3_0_142) on this topic that captured this issue plus others very nicely. (Jupyter is the Python equivalent of notebooks.) There are some differences between R Markdown (plus RStudio) and Jupyter notebooks, but many of the same issues do apply.

## Further reading and resources for R Markdown

Yihui Xie, who developed R Markdown and the knitr package, has written a book dedicated to R Markdown with J.J. Alaire (Founder and CEO of RStudio) and Garrett Grolemund (co-author of R For Data Science): https://bookdown.org/yihui/rmarkdown/. The book is a great resource that covers a variety of topics in addition to traditional R Markdown documents, including notebooks, slide presentations, and dashboards.

## Summary

- Integrating code and documentation in one place produces clearer, more reproducible code
- RStudio provides useful built-in functionality for "knitting" documents into a variety of output formats
- R Markdown documents can be integrated within a recommended project structure to create a reproducible analysis