rmarkdown.qmd

# R markdown document 

```{r echo=FALSE}
source("libs/Common.R")
```

<style>
.output_example {
    border: 1px solid #bbbbbb ;
    padding: 10px;
    background: #EEEEEE;
    box-shadow: 2px 3px 5px #bbbbbb;
    margin-block-end: 25px;
}

.output_out {
    border: 1px solid #bbbbbb ;
    padding: 10px;
    background: #F5EFD5;
    box-shadow: 2px 3px 5px #bbbbbb;
    margin-left: 25px;
    margin-block-end: 25px;
}

.table{
max-width: 50% ;
}

.ignore-css{table-layout : auto;}

</style>


```{r echo = FALSE}
pkg_ver(c("knitr", "rmarkdown"))
```


## Introduction

An R markdown document is a text file usually ending with an `.Rmd` extension. It allows one to embed R code chunks and their output into a comprehensive report thus eliminating the possibility of loading the wrong figure into the document, or forgetting to update a statistical summary in the text when the original data file was revised.

Creating an R markdown output from an Rmd file requires **knitting** the file as opposed to *running* the code as you would an R script. The RStudio interface provides you with a *knit* button at the top of its interface. The knit button also allows you to choose the output format (HMTL, Word or PDF). You can also knit an Rmd file in R using the `render` function from the `rmarkdown` package. For example,

```{r eval=FALSE}
rmarkdown::render("HW16.Rmd")
```

## The YAML header


The YAML header controls the look and feel of your document. At the very least, your R markdown document should contain the following YAML header sandwiched between two sets of `---`:

<pre class="output_example">
 ---
 title: "Your document title"
 author: "ES 218"
 output:
   html_document: default
 ---
</pre>

Make sure that the `html_document: default` line is indented at least two spaces. If you intend on creating a Word document, substitute `html_document` with `word_document`.

<pre class="output_example">
 ---
 title: "Your document title"
 author: "ES 218"
 output:
   word_document: default
 ---
</pre>

The YAML header can take on several parameters. For example, to add the current date, add:

<pre class="output_example">
date: '`r knitr::inline_expr('format(Sys.time(), "%d %B, %Y")') `'
</pre>

The above chunk makes use of an inline code chunk that will be discussed later in this tutorial. Note the mix of single quotes and back ticks that wrap the inline code. The `%d`, `%B` and `%y` parameters specify the date format. You can read more on date formats [here](https://mgimond.github.io/ES218/date_objects.html#formatting-date-objects).

To have the document automatically generate a table of contents add `toc: true` to the `html_document` or `word_document` header. Make sure that the `toc` parameter is indented at least two spaces from the `xxx_document` header:

<pre class="output_example">
...
output:
  html_document: 
    toc: true
</pre>

The above generates a static TOC. If you want to generate a floating TOC, add  `toc_float: true`.

<pre class="output_example">
...
output:
  html_document: 
    toc: true
    toc_float: true
</pre>

## Code folding

Rmarkdown offers the option to interactively collapse the code chunks in a knitted document. This may not be an option to have in a final report, but it may prove useful for a technical document where both code and output are to be shared. Code folding option is set with `code_folding: ...`. The options are `hide` to collapse the code chunks by default and `show` to reveal the code chunks by default.

<pre class="output_example">
...
output:
  html_document: 
    toc: true
    toc_float: true
    code_folding: hide
</pre>

## Section headers

You can add section headers to your document by preceding the header with one or more hashtags. Each hashtag represents one heading level. For example, the top heading level is `#` and the third heading level is `###`. 

The top header hashtag is usually avoided because its default font size tends to be too big. It's not uncommon to see R markdown files assign the top level to `##`. 

<pre class="output_example">
## Use this as a top section level 

Some text

### Use this as the second section level 

Some text

#### Use this as the third section level 

etc...
</pre>

<div class="output_out">
## Use this as a top section level {.unnumbered}

Some text

### Use this as the second section level {.unnumbered}

Some text

#### Use this as the third section level {.unnumbered}

etc...
</div>

## Text formats

The markdown language has several built-in text formatting options. A brief summary of some their syntax follows:

* *Italic*: To italicize text, wrap it in asterisks as in *`*this is italicized*`*. Note that you do not want spaces between the asterisks and the text.
* **Bold**: To bold text, wrap it with a *pair* of asterisks **`**this is bold**`**.
* Web links: To create web links wrap the text with `[ ]` followed by the web link wrapped with `( )` as in `[ES 218 website](https://mgimond.github.io/ES218)`. Make sure that there are no spaces between `[]` and `()`.
* Lists: To create lists in your document, precede  each list item with an asterisk followed by a space. For example:

<pre class="output_example">
* First list element
* Second list element
* Third list element
</pre>

<div class="output_out">
* First list element
* Second list element
* Third list element
</div>

* Block equations: You can embed [Latex](https://www.sharelatex.com/learn/Mathematical_expressions) block equations using double dollar signs,

<pre class="output_example">
$$
y_{edu} = \frac{1 + x}{x} + \varepsilon
$$
</pre>

which generates,

<div class="output_out"> 
$$
y_{edu} = \frac{1 + x}{x} + \varepsilon
$$
</div>

* Inline equations: You can also add inline Latex equations using single dollar signs,

<pre class="output_example">
The equation $x(1 + x)$ can be re-written as $x + x^2$. 
</pre>

which generates,

<div class="output_out"> 
The equation $x(1 + x)$ can be re-written as $x + x^2$. 
</div>

## Code chunks

To embed a code chunk, simply wrap the code between ` ```{r} ` and ` ``` `.

<pre class="output_example">```{r} 
plot(hp ~ mpg, mtcars)
```</pre>

Code chunks can take on many options. Examples of a few common options follow:

* `echo`: If you don't want the code chunks to appear in the ouput, set `echo=FALSE`.
* `include`: If you want neither the code chunk nor its ouput displayed in the output, set `include=FALSE`.
* `fig.width` and `fig.height`: These parameters control a figure's height and width (in inches).
* `warning` and `message`: Some functions will output warnings or messages, most of which you probably do not want in your output document. To hide these, set `warning` and `message` to `FALSE`.


An example of a code chunk with a few of the aformentioned parameter follows:

<pre class="output_example">```{r message=FALSE, warning=FALSE, echo=TRUE, fig.width=3, fig.height=2} 
plot(hp ~ mpg, mtcars)
```</pre>

Here's the output (note that `echo` was set to `TRUE` in this example):

<div class="output_out">

```{r message=FALSE, warning=FALSE, echo=2, fig.width=3, fig.height=2} 
OP <- par(mar=c(3,3,0,0), bg=NA)
plot(hp ~ mpg, mtcars)
par(OP)
```
</div>

## Document wide code chunk options

You can apply document wide code chunk options. For example, to avoid adding `message=FALSE` and `warning=FALSE` to each chunk of code, you can add this single chunk of code to the beginning of your Rmd file.

<pre class="output_example">```{r include=FALSE}
knitr::opts_chunk$set(message=FALSE, warning=FALSE)
```</pre>

## Inline code chunks

If statistical summaries or data derived vectors are to populate text in your document, it's best to do so as inline code chunks. For example, you might want to embed the mean `mpg` value from the `mtcars` dataset in your text. The traditional approach is to compute the mean in an R console as follows,

```{r}
mean(mtcars$mpg)
```

then transcribe this value into your document as follows:

<p class="output_out">
The mean miles per gallon is 20.1 mpg.
</p>

An automated way to do this is to embed the code chunk directly into your text by wrapping it between `r sprintf("\x60r")` (backtic followed by the letter r) and another backtick.

<pre class="output_example">
The mean miles per gallon is `r knitr::inline_expr('mean(mtcars$mpg)')` mpg.
</pre>

which generates:

<p class="output_out">
The mean miles per gallon is `r mean(mtcars$mpg)` mpg.
</p>

To control the precision, you can wrap the output with `round`,

<pre class="output_example">
The mean miles per gallon is `r knitr::inline_expr('round(mean(mtcars$mpg), 1)')` mpg.
</pre>

<p class="output_out">
The mean miles per gallon is `r round(mean(mtcars$mpg), 1)` mpg.
</p>

If the code chunk becomes too long and unwieldy to embed in your text, you can create an object from that code in a separate chunk of code, then reference that object inline. For example:


<pre class="output_example">```{r include=FALSE}
M <- lm(mpg ~ hp, mtcars)
r.sq <- round(summary(M)$r.square, 3)
```

The modeled r-square between miles-per-gallon and engine horsepower is `r knitr::inline_expr('r.sq')`.
</pre>


The code chunk is hidden from the output, but the object `r.sq` is created nonetheless and converted to its value in the inline code chunk. The output thus looks like:

```{r include=FALSE}
M <- lm(mpg ~ hp, mtcars)
r.sq <- round(summary(M)$r.square, 3)
```

<p class="output_out">
The modeled r-square between miles-per-gallon and engine horsepower is `r r.sq`.
</p>

## Tables

You can create two types of tables: **static tables** where you manually populate the cell values, and **dynamic tables** which are populated with R data tables.


### Static tables

Here's an example of a static table syntax:

<pre class="output_example">
column 1        Column 2    column3 
-----------  -----------  ------------
val1                 2.3  apple
val2                   5  orange
val3                0.34  kiwi
</pre>

<div class="output_out">

column 1        Column 2  column3 
-----------  -----------  ------------
val1                 2.3  apple
val2                 5.0  orange
val3                0.34  kiwi

</div>

Note how the left and right adjusted columns in the output reflect the left and right adjusted columns in the above syntax. It's important that the column elements not extend beyond the dashed line extents.

### Dynamic tables

There are many R packages that specialize in table output formats such as `xtable` and `stargazer`. However, decent tables can be created with `knitr`'s `kable` function in conjunction with `kableExtra`. Note that this requires the `magrittr` package (if the pipe `%>% ` is used). However, if `dplyr` is used elsewhere in the Rmd document, the `magrittr` package can be omitted.  Here's an example:

<pre class="output_example">
library(magrittr)
knitr::kable( head(mtcars), format="html" ) %>% 
  kableExtra::kable_styling(bootstrap_options = "striped", 
                            full_width = FALSE, position = "left")
</pre>

<div class="output_out">
  <div class="ignore-css">
```{r echo=FALSE, class.source='base'}
library(magrittr)
knitr::kable( head(mtcars[ , 1:4 ]), format="html" ) %>% 
  kableExtra::kable_styling(bootstrap_options = "striped", 
                            full_width = FALSE, position = "left")
```
</div>
</div>

If the output file format is a Word document, substitute `format = "html"` with `format = "pandoc"`.

For more `kableExtra` options, visit its [website](https://haozhu233.github.io/kableExtra/awesome_table_in_html.html).

## A complete example

Here's what a complete Rmd file might look like:

<pre class="output_example">
 ---
 title: "A simple example"
 author: "ES 218"
 output:
   html_document: 
     toc: true
 editor_options: 
   chunk_output_type: console
 ---


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

## A basic plot

```{r fig.width = 3, fig.height = 2.5}`r ''` 
library(ggplot2)

ggplot(mtcars, aes(mpg, hp)) + geom_point() + 
  geom_smooth(method = lm, se = FALSE)
```

## Here's a glimpse of the data table

```{r echo = FALSE}`r ''`
knitr::kable(head((mtcars), format = "html"))
```

## A basic analysis

```{r include = FALSE}`r ''`
M <- lm(mpg ~ hp, mtcars)
r.sq <- round(summary(M)$r.square, 2)
```

The modeled r-square between miles-per-gallon and engine horsepower is `r knitr::inline_expr('r.sq')`.

</pre>

## Additional resources

 * [Here's a sample Buoy data report Rmd file](./Data/Sample_markdown_file.Rmd)
 * [Rstudio's website](https://rmarkdown.rstudio.com/lesson-1.html) has additional R markdown configuration options.