Step 1: Lets create an R Markdown HTML document

Step 2: Choose HTML (we can change this to PDF or Word later)

Please delete everything below the header…

---
title: "Introduction to RMarkdown"
author: "Dylan Z Childs"
date: "12 March, 2018"
output: html_document
---

…and then fill in the header!

(The header is an example 'YAML' by the way)

So what is 'Markdown'. Markdown is a lightweight, readable mark up language to format documents. It can be converted into HTML, Microsoft Word, PDF, ODT, RTF…

Here are a few examples of basic markdown mark up:

• specify headers with the # symbols
  • e.g. # My great header
• italicize text single * or _
  • e.g. *word* or _word_
• bold text with double * or _
  • e.g. **word** or __word__

So, you've added some Markdown, but how do you turn it into output? If you look up into the top of the script, you will see Knit HTML:

Click it and see what happens…

It is easy to get help. Remember that RStudio provides cheatsheets and other resources:

https://www.rstudio.com/resources/cheatsheets/

Here is the code to embed that link in the HTML document.

[Cheat sheets](https://www.rstudio.com/resources/cheatsheets/)

(Note the use of square brackets… and then curved parentheses)

This makes a link that looks like this: Cheat sheets

Add this link (or any link you like) to your Rmd document.

In R Markdown, using `some words` (e.g. in back ticks) places a grey box around the text and uses a slightly different font. This is very handy.

Can you add a sentence that looks like this?

• This is how you make a sequence of numbers: x <- 1:50.

Make sure it doesn't look like this:

• This is how you make a sequence of numbers: x <- 1:50.

Making lists involves using either - or __*__ or 1. to mark each element of the list. There must also be a blank line between the preceding paragraph and the start of the list.

Can you figure out how to do this?

• I Love R
• I Hate R
• I Love R

And This?

1. I Love R
2. I Hate R
3. I Love R

Tables start with pipes: |

They have the column names in between pipes. Here is an example with two columns

|R Code|Unix Code|

Then, we can make a bold(ish) line

|:---:|:---:|

and follow this with detail that goes into the table.

|getwd()|pwd|

|setwd()|cd|

See if you can produce this…

|R Code |Unix Code|
|:-----:|:-------:|
|getwd()|pwd      |
|setwd()|cd       |
|ls()   |ls       |
|head() |head     |
|tail() |tail     |
|grep() |grep     |

This method is used to define a table manually. We can also display data frames as tables. We'll see how to do that later. First we have to know how to insert R code into a document.

We can include bits of R code in an R Markdown document. These 'chunks' are run in the order they appear, allowing us to make figures, report statistical results, etc.

```{r}
x <- rnorm(12)
x
```

This will produce the following in a document:

x <- rnorm(12)
x

##  [1] -1.4639487 -1.1643933 -0.5263443 -1.0349474 -0.6429377 -0.6903048
##  [7] -0.7678070 -0.8970685  1.1736446 -0.1425114 -0.1311938 -1.9121733

To embed R code, we have to place it between a special sequence of characters.

These involve sets of three of 'back ticks' (that start and finish the code 'chunk') and some curly braces…

```{r}

```

TIP: Don't type the chunk syntax manually! Use 'Ctrl + Alt + I' to (I)nsert a code chunk.

Add this detail to your document:

```{r}
x <- 1:10
y <- x^2
x + y
```

This should produce the following when you knit your document:

x <- 1:10
y <- x^2
x + y

##  [1]   2   6  12  20  30  42  56  72  90 110

1. The knitr package first evaluates all the R code in the R Markdown file ('Rmd') and embeds the resulting code and output in a standard Markdown file ('md').

2. The pandoc file converter then takes the resulting markdown file and converts it to HTML (or some other file format if you chose to use).

You don't really need to know this…

There are times when we may want to display code but not the output — for example, to provide guidance, but not the answer in teaching. Sometimes we just want the answers but not the code — for example, to embed graphs or results of calculations.

• An R chunk can be made to either show or not show the code
• An R chunk can be made to either evaluate or not evaluate the code

These behaviours are are controlled by echo (show) and eval (evaluate), respectively.

We can use the kable function from the knitr package to insert a table made from a data frame:

tb <- head(iris, 4) 
knitr::kable(tb)

We control the size/position of figures using the various out.XX and fig.XX chunk arguments, e.g. using out.width='10%' and fig.align='center':

```{r, out.width='50%', fig.align='left', echo=FALSE}
ggplot(iris, aes(x = Sepal.Length, y = Sepal.Width, colour = Species)) +
  geom_point(alpha = 0.8)
```

Use the include_graphics function from knitr inside an R code chunk:

```{r, out.width='10%', fig.align='center', echo=FALSE}
knitr::include_graphics('./assets/dylanSheep.jpg')
```

Again, control the appearance using the various out.XX and fig.XX chunk arguments.

```{r, out.width='10%', fig.align='center', echo=FALSE}
knitr::include_graphics('./assets/dylanSheep.jpg')
```

The R Markdown framework has been used extended to various ways. In addition to building a boring, HTML, PDF, or Word doc, you can…

• Prepare presentations: http://rpubs.com/dzchilds/rmd-overview

• Write a book / thesis (bookdown package)

• Build a website or blog (blogdown package)

If you're interested, take a look at these links:

https://rmarkdown.rstudio.com https://bookdown.org/yihui/bookdown/ https://bookdown.org/yihui/blogdown/