3 R-Markdown

3.1 What is markdown

Remind yourself of what Rmarkdown is here https://rmarkdown.rstudio.com via this short video

3.1.1 What are R-SCripts?

Read more here: https://rmarkdown.rstudio.com

Typing in console is like a having phone call with the computer, you’re talking but you’re not keeping records of what you say. When you close R-studio you lose your analysis.

What we need instead is a way to save the commands for future use - we can do this using scripts. There are several types of document, or script that you can create and save in R-Studio.

A basic script (the filetype is .r). This is simply just a blank notepad where you can save code commands. When you “run” the commands in the script, R simply copy/pastes the commands over to the console. This is probably how you have done previous labs.
An R-Notebook or R-Markdown document (the filetype is .Rmd). These are much more interesting - and are how I wrote this lab book. This is what we will be using in our labs.

In this course we are going to focus on the R-Markdown format and you are going to submit your labs as websites/html files along with your code.

3.1.2 What is R-Markdown?

What is an R-Markdown Document? imagine a normal Microsoft Word document, but halfway through you can press a button and a mini R console appears…. You type your code inside the mini console, and click run. The computer runs the code and puts the plots/output directly into your report - then you leave the console and write about the results below the plot.

As described in the video, Rmd files are also flexible. You can turn them into reports, websites, blogs, presentations or applications with a few short commands.

3.2 Creating a markdown document

Go to the File menu on the top left, then click New File - R-Markdown. If this is your first time ever doing this, it might ask to download some packages to be able to do this (look for a little yellow bar at the top of the screen and say yes)

Eventually a window will open up:

It will ask you to name and save your file. Give it a relevant name.
A new file should appear on your screen.
At the top of that window (by the knit button, there is a save button. Save it as something relevant INSIDE YOUR PROJECT FOLDER!

Figure 3.1: Yours will say STAT462 rather than GEOG364

The new file on your screen is your first markdown script.

3.3 Important things to know

3.3.1 All markdown documents have three components. {#T32A_whatisit?}

All markdown documents have three components.

There is a space at the top of the file where we can add information about themes/styles etc called “YAML”. This determines what type/style of document your work will become
There is space to add text (white),
And you can add code in ‘mini consoles’ called ‘code chunks’. (Grey)

Figure 3.2: Markdown Components

3.3.2 Visual mode

It is MUCH easier to edit markdown documents in the new visual mode. Essentially instead of having to remember text short cuts like * for bold, you can edit the text part as though you were using a word processor. NOTE HEADERS where it says “Normal”, this allows you to make auto tables of contents.

Figure 3.3: Look at the circled button near the top of the two reports

3.3.3 Editing YAML Code

Your YAML code is the code at the top of your file in between the — lines. (see 3.2)). Let’s zoom in

Your YAML code controls how your final output looks and which type of output it becomes. For example, your document could become a website, a pdf, a presentation or app..

The basic version is very simple with a title, an author and a self entered date. Let’s add in more options.

YAML code is annnoying to edit, because here, spaces really do matter. Everything has to be perfect or it won’t knit.

Select everything in my code chunk here and replace your YAML with this (remember the — on line 1 and at the end).

---
title: "GEOG-364 - Lab 2"
author: "hlg5155"
date: "`r Sys.Date()`"
output:
  html_document:
    toc: true
    toc_float: yes
    number_sections: yes
    theme: lumen
    df_print: paged
---

Replace the author ID with your user name, change the title if appropriate.

The elements we just added are:

The title
The author (note,use your ID not your name)
Automatically created today’s date
A floating table of contents
Numbered sections (this won’t appear until you start typing section headings)
The document is now in the lumen theme.

3.3.4 Troubleshooting

Note, if you copy/paste this and it doesn’t work, sometimes the quote marks copy weirdly from the internet - try deleting and retyping the quotes.
If it still doesn’t work.. this might be because a space is missing (especially if you typed it out).
- Editing YAML code can be a pain. It is very case and space sensitive.
  For example, the spaces at the start of some lines are important and are created using the TAB KEY, not the space bar. There is one TAB key before html_notebook (which is now on a new line). There are two TAB KEYS before toc, toc_float, number_sections and theme.

Don’t continue until you can make and view your html when you press knit. If it doesn’t work, ask for help before moving on

3.3.5 Changing the theme

You don’t need to choose the lumen theme. There are many other ways you can edit your markdown documents here: https://www.datadreaming.org/post/r-markdown-theme-gallery/

To edit, replace the word lumen with the name of your chosen theme (THIS IS CASE SENSITIVE). Now click knit and see if it works.Some themes are buggy. Try a different one if it doesn’t work.

The themes in “Even More Themes” on the website, requre you to install/load some new packages, so they need some extra work. You’re welcome to try if you have one you fell in love with!

3.3.6 Adding other YAML options

There are many more details about different options on these websites:

If you want to get really fancy, there is an interesting package to help you design YAML code here: https://education.rstudio.com/blog/2019/10/tools-for-teaching-yaml-with-ymlthis/

3.4 Knitting

The file on your screen isn’t the finished article. To see how it will look as a final version, we need to “knit” it. Go to the top of the .Rmd file, find the knit button. Press it (you might have to first save your script if you haven’t already, then press it again)

You should see that the Markdown tab “builds” your document and you get an output as a website. The html should also be saved into your project folder.

For example, here is a file with markdown and knitted output.

3.5 Editing the report text

You can type anywhere inside the white report area. R will ignore it.

3.5.1 Inserting images/tables and formatting

In visual mode, look at the menu at the top. It’s very easy to insert images, tables and other formatting. Pay special attention to the Normal/Heading 1/Heading 2 buttons..

You can also do this in source mode, but you have to learn the keyboard shortcuts. For example to make something bold you put stars around it e.g. *bold* . You can see more examples in the pic above and here

For more, see this link: https://zsmith27.github.io/rmarkdown_crash-course/lesson-3-basic-syntax.html

3.5.2 Code chunks

Code chunks are mini consoles where you can run R commands.

3.5.2.1 Adding a code chunk

On the top right there are a suite of buttons for adding a new code chunk, running code etc. The green one adds a new code chunk. To run an individual code chunk you will press the green arrow on its top right e.g.

3.5.2.2 Editing and running code chunks

You should see that a new area has appeared in your report that is a different color to the background. Inside its essentially a “mini console”. It’s where you add your code and you need to ‘speak R’ inside it.

When you press enter, the code won’t run. INSTEAD, click the little green arrow

3.6 Writing Maths equations in R-Markdown

3.6.1 Double dollar signs

It is relatively easy to write equations in R markdown. They use the “Latex” format and you put them between double dollar signs.

For example, try typing $$x=2$$ on a new line of the white text area in your repprt ( NOT INTO A CODE CHUNK), then pressing knit. You should see:

\[x=2\]

But how do you write all the fancy equation stuff? We cheat.

Create the equation you want in one of these generators, then copy the code into your script and put it between double dollar signs:

For example

$$\widehat{y} = b_{0}+b_{1}x$$

Shows up as \[\widehat{y} = b_{0}+b_{1}x\]

3.6.2 Single dollar signs

Essentially this is the same, but the equation is part of the text and you only see the output when you press knit. For example including $x=2$ in this sentence shows $x=2$ as an output.

3.7 Code Chunk options

What are they? Essentially, instructions that you tell the computer when you press knit.

3.7.1 Creating them in Source mode

Click source mode and have a look at a code chunk. You will see it starts with three little back-ticks and the {r} sign. For code chunk options, we will be focusing on the top line with the {r}

At the moment, the code chunk tells us that the code inside is written in R.

We can also add other options, separated using commas.

In fact, you have often seen me add message=FALSE and warning=FALSE to prevent any spurious messages appearing when you press knit. Keep reading to see the many other things you can add.

3.7.2 Creating them in View mode

You can also edit code chunk options in view mode. Create a new code chunk, then click on the little (almost invisible) cogwheel near the run triangle

This will open a menu where you can choose many of the common options

3.7.3 Setting the default for the whole document

Many templates already include this for you to edit.

If not, you can put a code chunk at the top of your document (below the YAML code) containing knitr::opts_chunk$set(echo=TRUE) to change the default values of chunk options in a document.

For example, you may put this in the first code chunk of your document to stop it showing messages on knit.

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

3.7.4 Common options

Here are the common options we typically need:

message = TRUE/FALSE. Don’t show friendly R messages on knitting. I use this so often that I put it in that knitr code chunk at the top of my scripts.
warning = TRUE/FALSE . Don’t show R warnings on knitting. It will still show errors, so this is another good one to use.
include = TRUE/FALSE. Show or Hide the code AND output in the final document. Really useful with inline code (next section)
echo = TRUE/FALSE. Show or Hide the code chunk code in the final document. The output will still be shown.
eval = TRUE/FALSE. This option determines whether the code is evaluated or executed. If eval = TRUE, the code is executed. If eval = FALSE, the code is not executed, but the code chunk is still displayed. This can be useful for showing example code without actually running it.
Or for example, if you can’t knit because of an error, you can add eval=FALSE to the problem code chunk so I can see what you did but you can still knit.

3.8 Inline Code

There are two types of code you can write in your reports: code chunks and inline R code.

3.8.0.1 Code chunks….. (as discussed above)

Click source mode and have a look at a code chunk. You will see it starts with three little back-ticks and the {r} sign.

3.8.0.2 ….. and Inline Code

Inline R code is embedded in the TEXT/NARRATIVE of your document using single back-ticks. For example, writing

My value of y is `r y` and x-squared is `r x^2`

Will output:

My value of y is 10 and x-squared is 49.

If this doesn’t make sense, follow these tutorial to see how to add inline code.

3.8.1 Tips for adding inline code

Inline code is GREAT. Imagine writing your 100 page thesis, but then you realise that your dataset was wrong. If all the numbers in your report are added using inline code, then it will automatically update your entire report.

The easiest way to do this is to run your commands in a “silent” code chunk with the echo=FALSE and include=FALSE options. Then in the text, I just put the variable name I want to print, sometimes rounding to a better number of decimal places¹.

For example here’s how I typed that the mean height of the starwars data is 174.6 cm:

2 Libraries/Packages

4 Coding