---
title: Lab 5
author: Charlotte Wickham
date: '2017-10-24'
slug: lab-5
draft: false
output:
  blogdown::html_page:
    toc: true
---

<!-- This work is licensed under a Creative Commons Attribution-ShareAlike 4.0 International License. -->

```{r setup, include = FALSE}
knitr::opts_chunk$set(echo = TRUE, results = "hide",
  message = FALSE, fig.keep = "none")
set.seed(1918)
```


## Rmarkdown

Rmarkdown is a way to integrate narrative text with R code and output.  It's ideal for writing your homework since it's easy to integrate code, and output but it's also great for ensuring your analyses are reproducible (I also use it to write the lecture slides, labs, homework and solutions).

The Rmarkdown you'll be working with uses the data from HW#3.  So, make sure you have it first:

```{r, eval = FALSE}
download.file("http://st551.cwick.co.nz/data/brfss.rds", 
  "brfss.rds", mode = "wb")
```

Download the and open the Rmarkdown file [lab-5-rmarkdown.Rmd](lab-5-rmarkdown.Rmd).  For the rest of the lab the content is in the Rmarkdown file, but to help you navigate the essential parts are also listed here.

### "Knitting" the file

Start by knitting the file (the Knit icon on the toolbar, or Cmd/Crtl + Shift + K).  The code chunks in the file are run in a fresh session of R, output and figures are generated, and the whole document is produced as a .pdf.

(You may be asked to install some additional packages before knitting will work).

### Code chunks

Lines of the file that begin with: `` ```{r} `` designate the beginning of a **code chunk**.  Until the closing `` ``` ``, everything inside the chunk is interpreted as R code.  When knit, this code is run, and the output and figures are captured.

Whether the code itself, the results or the figures are displayed in the final document depends in the **chunk options** that follow the `r` in `` ```{r} ``.   For example ``  ```{r, echo = FALSE} ``, prevents the code from displaying in the document,  ``  ```{r, results = "hide"} `` prevents the results from being included in the document.  You can find all the possible options at [the knitr chunk options page](http://yihui.name/knitr/options/).

### Markdown

The text in the document that isn't in a code chunk is interpreted as Markdown, a very simple system for document markup.  You can specify section headings, bold or italic font, bulleted or numbered lists, tables, links and images.  Read more in ]Chapter 27.3 in R4DS](http://r4ds.had.co.nz/r-markdown.html#text-formatting-with-markdown).

### Math

Rmarkdown also has the ability to typeset equations using LaTex syntax.  Put an inline equation between single dollar signs, `$`, e.g. `$\overline{Y} = \sum_{i = 1}^{n}$`, and displayed equations (i.e. centered on a new line) with `$$`, e.g.
```
$$
\overline{Y} = \sum_{i = 1}^{n} \dot \sim N(0, 1)
$$
```

### Inline code

You can also put evaluated R code inline in markdown sections.  This is very useful for including a calculated number in a sentence.  To do so, start with `` `r ``, write your R code then finish with `` ` ``.  For example, $\pi$ to 3 .d.p is `` `r '\x60r round(pi, 3)\x60'` ``   Which displays as : "`r round(pi, 3)`"

### Tables

You can also insert nicely formatted tables in Rmarkdown.  I find the `pander` package quite good, because it results in a markdown table which can then be easily converted to HTML, PDF or Word. You just need to make sure you set the chunk option `results` to `asis`.

For example,

    `r ''````{r, results = "asis"}
    library(pander)
    pander(head(mtcars))
    ```

Results in the table:
```{r, results = "asis", echo = FALSE}
library(pander)
pander(head(mtcars))
```

### Looking ahead

Starting with HW #5 I will expect your submissions to be generated from Rmarkdown, you will submit the compiled .pdf and the source .Rmd document.

Learn more about Rmarkdown at: http://rmarkdown.rstudio.com/lesson-1.html

Also check out the [Rmarkdown cheatsheet](https://www.rstudio.com/wp-content/uploads/2016/03/rmarkdown-cheatsheet-2.0.pdf).

A couple of practical hints:

* Compile errors are often cryptic but often come from R code errors, start by starting a fresh session of R and running all the code in the chunks.  Fix the errors in the code before looking for errors elsewhere.
* Compile early and often.
* Every time you compile, all code is run in a fresh session.  Code that takes a long time to run (i.e. a big simulation) will slow this down. Consider moving the simulation code to a separate file, and saving the output there (with e.g. `write_rds()` from the `readr` package), and reading the output into your Rmarkdown file (with e.g. `read_rds()` from the `readr` package).
