---
subtitle: "TMA4268 Statistical Learning V2019"
title: "Introduction to R Markdown"
author: "Mette Langaas, Department of Mathematical Sciences, NTNU"
date: "week 6 2019"
output: #3rd letter intentation hierarchy
   html_document:
     toc: true
     toc_float: true
     toc_depth: 2
   pdf_document:
     toc: true
     toc_depth: 2
     keep_tex: yes
     df_print: kable
   beamer_presentation:
     keep_tex: yes
     fig_caption: false
     latex_engine: xelatex
always_allow_html: yes
---

```{r setup, include=FALSE}
knitr::opts_chunk$set(echo = TRUE,tidy=TRUE,message=FALSE,warning=FALSE,results="hold")
showsol<-FALSE
```

<!-- rmarkdown::render("/Users/mettela/Box Sync/NTNUgitcourses/NRkurs/NRkursC.Rmd","html_document") -->
<!-- rmarkdown::render("/Users/mettela/Box Sync/NTNUgitcourses/NRkurs/NRkursC.Rmd","beamer_presentation") -->
<!-- rmarkdown::render("/Users/mettela/Box Sync/NTNUgitcourses/NRkurs/NRkursC.Rmd","pdf_document") -->

# R Markdown

##Aim

We will use R Markdown for our compulsory exercises in this course - you therefore need to know

* what is R Markdown?
* what is an YAML header?
* what happens when I press `knit`?
* how to write text and maths
* how to include R commands
* what if I get an error message when I `knit`?
* how do I hand in compulsory exercise 1?
* what if I want to learn more?

---

## What is R Markdown? 

[1 minute introduction video](https://rmarkdown.rstudio.com/lesson-1.html)

---

# R Markdown structure

## YAML Header 

* Where: at start of file, between lines of - - -
* Optional section of render options written as key:value pairs.
* Warning: indentation important here.

---

**Hands-on**: We look at the template for Compulsory exercise 1 at <https://www.math.ntnu.no/emner/TMA4268/2019v/CompEx1mal.Rmd>

* Download and open in RStudio, save with a different file name.
* Change the name of the group and the name of the group members
* Press the `knit` button and observe that happens. 

In the future: If you want to make a new document in RStudio: "File New R Markdown"

Remember: for Compulsory exercise 1 we have list all packages you need to install on the top of the assignment: <https://www.math.ntnu.no/emner/TMA4268/2019v/Compulsory1.html#r_packages>
Smart of you to start by installing all of these!

---

## YAML output options

```{r, results="asis",echo=FALSE}
library(kableExtra)
df=data.frame(matrix(c("html_document","html","pdf_document", "pdf requires Tex", 
"word_document","Microsoft Word (.docx)",
"odt_document","OpenDocument Text","rtf_document","Rich Text Format",
"md_document","Markdown","github_document","Github compatible markdown",
"ioslides_presentation","ioslides HTML slides","slidy_presentation","slidy HTML slides",
"beamer_presentation","Beamer pdf slides (requires Tex)"),ncol=2,byrow=TRUE))
names(df)=c("output value","creates")
#print(xtable::xtable(df,caption="Output options"),type="html",html.table.attributes="border=0")
# df %>%
#   kable() %>%
#   kable_styling()
#knitr::kable(df)
kable(df) %>%
  kable_styling(bootstrap_options = c("striped", "hover"))
```

See also list of sub-options in cheat sheet. <https://github.com/rstudio/cheatsheets/raw/master/rmarkdown-2.0.pdf>

---

## What happens when you press `knit`? (rendering)

Knitting is also done by: Ctrl+Shift+K (Windows) or Cmd+Shift+K (MacOS).

1) Creating documents with R Markdown starts with an .Rmd file that contains a combination of markdown (content with simple text formatting) and R code chunks. 

2) The .Rmd file is fed to `knitr` which executes all of the R code chunks and creates a new markdown (.md) document which includes the R code and it’s output.

3) The markdown file generated by `knitr` is then processed by `pandoc` which is responsible for creating a finished web page, PDF, MS Word document, slide show, handout, book, dashboard, package vignette or other format.

More: [About pandoc - the swiss army knife](https://pandoc.org/)
NB: even if you write tex this is first translated to md and then via pandoc to pdf, so subtile tex stuff may be missed on the way.

Do you get a separate window popping up, or is your output shown in the Viewer tab of one of the window panes? Go to RStudio-preferences-RMarkdown and check what is your value of "show output preview in".

---

## What output type do you want to produce?

* Just keep track of your own work: html_document
* For TMA4268 Compulsory exercise 1: we also ask for a pdf-file (because that is easy to read and grade when you upload that to Blackboard)
* Module pages in TMA4268: `html_document`, `pdf_document` and `beamer_presentation`.

To produce a `pdf_document` RStudio (using pandoc) will call a latex-installation, so you need to have latex installed on your laptop to be able to produce a pdf-file.

Toggle comment/uncomment with hashtag in YAML header `output` to make different options active, then press `knit`. Alterntively this can be done by calling the function `rmarkdown::render()` from your Console window.

Optional: check that uncommenting `pdf_document` and commenting out `html_document` and pressing `knit` will give you a pdf-file.

During rendering we use the location of the .Rmd file as the working directory, and the rendering is done in a _new session_.

Optional: can instead run `rmarkdown::render("file.Rmd","pdf_document")` from command line, or`rmarkdown::render("file.Rmd","html_document")`. Then you can have several options in the YAML together!

---

# Formatting your R Markdown file

## Text, mathematics

* formatted with markdown
* mathematics (in latex) with formulas staring and ending with one `$` and equation with `$$`
* boldface with two stars and italic with one, new line with two spaces,
* sections, bulleted or numbered lists, tables, footnotes, rulers, 

---

**Hands-on**: go the the Compulsory exercise 1 template, look at Q1 and Q2, and and just write and press `knitr` to see! Try for example to answer Q1 (incorrectly) by writing $Y_i=\beta_0+\beta_1 x_{i1} +\varepsilon_i$ (the correct answer will use the correct model).

---

## Links

```{r,echo=TRUE,eval=FALSE}
First option: then the link is displayed with the address:
<link> 
as we have done with 
<https://github.com/rstudio/cheatsheets/raw/master/rmarkdown-2.0.pdf>
  
Second option: if you do not want to display the address but some other text
[name of link](link) 
as with
[R Markdown cheat sheet](https://github.com/rstudio/cheatsheets/raw/master/rmarkdown-2.0.pdf)
```


## Code Chunks

* Chunks of embedded code. Each chunk:
* Begins with \`\`\`{r} and ends with \`\`\`
* Set of code chunk options - but I have mainly used these two:
    + `echo`: display the code in the chunk, TRUE or FALSE or selected lines, or maybe with an R-object (later)
    + `eval`: run code in the chunk, TRUE or FALSE
* Remember to include packages to be used within the chunk.
* Chunks can have (unique) names, may help when debugging (but I have been lazy in the template).

---

**Hands-on**: go the the Compulsory exercise 1 template and insert `coef(modelA)` in the end of the first code chunk. Press `knit` to see the effect. 
Then change the chunk options to `eval=FALSE` and `knit`. What happens. Finally, change the chunk options to `echo=FALSE` and `knit` and observe the result.

---

## Set-up chunk

Smart things to add to the setup-chunk:

```{r, eval=FALSE,echo=TRUE}
library(knitr)
opts_chunk$set(tidy.opts=list(width.cutoff=68),
               results="hold",tidy=TRUE,
               warning=FALSE,error=FALSE,
               message=FALSE)
knitr::opts_chunk$set(echo = TRUE)
```

---

## Calling R outside of the code chunks

Use the \` r before and \` after an R command to integrate into the text.

```{r, echo=TRUE,eval=FALSE}
Hi, 2+2 is equal to `r 2+2`.
```

This is what we have done in the YAML-header to include todays date on your submission:

```{r,echo=TRUE,eval=FALSE}
`r format(Sys.time(), '%d %B, %Y')`
```
---

# Problems

## When I `knit` with output: pdf_document no pdf-file is produced. Why?

* html_document is more forgiving than pdf_document wrt tex-errors
* a tex-error is not easy to spot - log is terrible
* many students have problems here, and some just end up handing in html or Rmd for the projects 

My solution

* first I render html_document and look for tex-errors and fix them
* then I render pdf_document, and include `keep_tex: yes` yaml option
* then I compile the tex in my favorite `texshop` and look for sensible log for errors, 
* and then go back to the Rmd and fix the error.


# References

* Cheat sheet: <https://github.com/rstudio/cheatsheets/raw/master/rmarkdown-2.0.pdf>
* <https://rmarkdown.rstudio.com/lesson-1.html>
* <https://bookdown.org/yihui/rmarkdown/>
* It is also possible to include parameters in the YAML header, and use them in the text/chunks. The parameters can be set in the rendering. More about this in Chapter 15 of the R Markdown book:  <https://bookdown.org/yihui/rmarkdown/>

