3 R-Markdown

3.1 What is markdown?

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

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)

3.2 Important things to know

3.2.1 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.

3.2.2 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..

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

Note, because of visual mode, you can click a button instead of learning the syntax.

3.2.3 Code chunks

Code chunks are mini consoles where you can run R commands. We will talk more about them in the next tutorial.

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.2.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.

Yours will not knit if you haven’t yet installed the rmdformats package

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

3.3 YAML Code and templates

For Lab 1-3, you will be using a custom template that I made using the package rmdformats.[^in_04-tutorial3_markdown-1] This outputs a html file in a special html format called ‘downcute’. From lab 4 onwards, you will be making your own markdown documents. Here’s how

Make sure that you have installed the rmdformats package. If you’re on posit cloud, you will need to install it every time.
MAKE SURE YOU ARE RUNNING YOUR PROJECT
Go to File/New File/R-Markdown (it’s the 5th menu option down)
Don’t be tempted to fill in the title. Instead IMMEDIATELY click on the template button on the left.
This will bring up a list of templates. Choose one you like. If you’re not sure, have a look here: https://github.com/juba/rmdformats?tab=readme-ov-file#readme

Now there are two things you might see (I’m not sure why - Mac vs PC?)

OPTION A: If you see something like this, where the bottom bit is blank.

Choose your template, press OK and it will make a file called untitled.RmD. Click either knit or save and save it as your labnumber_emailID.RmD.

OPTION B: On some computers (including mine), it says that these files need to be put into a new directory.

In that case, name the file here as your labnumber_emailID.Rm and click OK.
It will make a new file named correctly. BUT there’s a (mini) issue. It puts the file in a subfolder inside your lab folder. Close the file.
You can either close Rstudio and on your computer, move the RmD up a level to the main lab folder and delete the subfolder. OR.. you can do it inside R studio.
- And now, go to the files quadrant. If you are running your project, you should see a new subfolder named whatever you named your RmD file. Click on its name to open.
- Then click on the tickbox by your lab report file, click on the cogwheel on the right (this gets hidden if your R-Studio isn’t full screen) and click move. Move it up one-level to your main lab folder.
- Then move up a level to your main lab 4, click the tickbox by the sub-folder and press delete.

Now reopen the RmD file and carry on with your lab.

3.4 Writing Maths equations in R-Markdown

3.4.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.4.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.4.3 Using Equatiomatic

There’s also a package called equatiomatic that we can use to directly make equations from our linear models. Full tutorial here: https://github.com/datalorax/equatiomatic

3.4.3.1 Installing it

It’s no longer in the official app-store, so to install it, FIRST, install a package called ‘remotes’.

Then run this code to install from github:

remotes::install_github("datalorax/equatiomatic")

Then add the library command in the library code chunk. Note, as discussed here, this might not work for some people and to be honest, I think this package might be more effort than it’s worth.

3.4.3.2 Using it

Equatiomatic allows us to extract an equation from any linear model using extract_eq(). For example, let’s create a linear model:

data(starwars)
mymodel <- lm(mass~height,data=starwars)

Then extract_eq allows you to see the LateX version of the equation.

extract_eq(mymodel)

If you run it in the console, the command returns the LaTeX code you need to add it into the text yourself. If you want to use the actual numbers, simply turn on use_coefs=TRUE.

extract_eq(mymodel, use_coefs = TRUE)

Let’s say our data is a sample, not the population, then we want to use lower case names for our sample statistics (b0 & b1).

There is no easy way to do this in the command, so I run the command in the console, then copy the command over to the TEXT part of the report as an equation and change the betas to ’b’s.

More examples here:

From the equatiomatic website: https://github.com/datalorax/equatiomatic

3.5 Code Chunk options

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

3.5.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.5.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.5.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.5.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.6 Inline Code

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

3.6.0.1 Code chunks

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.6.0.2 .. vs 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.6.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:

You don’t actually need echo AND include. I can simply never remember which one is which and use them both :).

2 Libraries/Packages

4 Reading in data