Section 1.3 Working with R Markdown

Objectives

In this section, we will focus more on one type of R scripts: R Markdown files. The reason is that we are going to use R Markdowns instead of raw R scripts from now on, so we need to know more about how R Markdown files work in addition to their potential

1 What are R Markdown files? How to open one in R?

R Markdown files are another type of script you can use in the Script block. They are a little bit more complex than raw R scripts because they need to be configured, but it is not complicated. In addition, the RStudio interface is very user-friendly, so there is almost no additional coding to do.

But what are they good for? R Markdown files are especially interesting concerning data sharing, as in one same document (and you can choose the format of it, even PDF), you have the structure, the narration, the code and the output of it. Very trustable and very good-looking. I personally also find it useful not only for data sharing with other people, but with the future-myself who will go back to the analyses of a dataset after months of hiatus working on another project. With a raw R file, I often get lost and I might even need to rewrite it. But with an R Markdown document, I can catch up very quickly since everything is documented and ordered!

Now that I wish that I have convinced you on how useful R Markdown documents are, let’s see how to open one. Just try to open a new script as usual, but instead of choosing “R Script”, choose “R Markdown…”.

Afterwards, you will be prompted to provide some information, such as the title of the document, the name of the author(s) as well as its date. We will see in the next section how we can easily modify these pieces of information. You also have to indicate whether you want the output as an HTML, PDF or Word document… Since choosing the HTML option gives us more flexibility, let’s choose this one, and you are set up!

Before getting into the file itself, some words must be said concerning the header. At one place, you can see two buttons, “Source” and “Visual”. Click on “Visual”, and you will see many options unfolding on the right.

We will mainly use three options:

Source / Visual: You have two ways to visualize the script you will be writing. The “Source” option allows you to see and write the codes directly. The advantage is that it gives you full control on what you are doing. The drawback is that you have to know how to code everything, and the interface is not very appealing. The “Visual” option allows you to write the script as if you were in a text editor like Word. It is intuitive and you can see what is happening while you are writing. The drawback is that sometimes it is hard to navigate inside the document because the underlying codes are doing something that is not visually represented… In that case, my strategy is to switch to the “Source” mode, make the changes that I want, and then switch back to the “Visual” mode!
There is an option with the word “Normal” on it. When you click on it, other options (Header 1, Header 2, etc.) will appear. These are important to define the level of navigation of your document: “Normal” is just for the text you are writing, “Header 1” for the main title, “Header 2” for the second main title, etc.
Another button is called “Insert”. Indeed, we have only talked so far about how to add text and titles, but you will have to insert other elements, such as R codes. Of course, you can directly write the codes as normal text, but Markdown files can do much more! Click on “Insert”, and you will see what you can add. There is a suboption called “Code Chunk”: This is how you can insert R codes.

Time to play around!

There are many more options, and there is no point in describing all of them here as we will mainly use only these three ones above. However, I encourage you to try everything and see what is happening. Try to write something, change the size, change the font. Click on the buttons. There will be error messages, but that’s ok. Try to understand these errors if possible. Check any changes that occurred. Again, make these Markdown files your own!

2 The structure of R Markdown files

Now we can turn to the structure of the R Markdown document itself. It has two main components:

The configuration lines,
The content of the document itself.

We will take the codes from Section 1.2 as an example to create our very first R Markdown document.

2.1 Configuring the file: The YAML block

2.1.1 Basic features of the YAML block

Let’s start with configuring the file: This corresponds to the first lines, or the header, of the script that you have just created. This is called the YAML part. It looks like this so far:

You will remark that there are pre-filled information, such as the title of the document, the name(s) of the author(s), the date and the output format. These are what we were prompted to fill when creating the document! Now you can try to change some things, for instance:

Title: Change to “My first R Markdown script”
Author: Change to you name
Date: Change to the date you wish, or even delete this line if you do not wish to add a date

2.1.2 More advanced features of the YAML block

You can also add other pieces of information, for instance:

Date:

You have more options, such as defining the format of the date, and maybe more interestingly, create a variable such that you do not have to change the date anytime you are saving the document. In other words, you may want to have a line specifying something like “This document was last modified on ‘Year-Month-Day’”. Just write as follows:

date: "This document was last modified on `r Sys.Date()`"

The code 2024-11-25 will look at the date of the system of your computer.

Table of contents:

The addition of titles in the document is here to help when navigating it. You can also add a table of contents such that it is even easier to navigate. You can also specify how many layers you want to display in the table of contents.

toc: true
toc-depth: 4 ## Change this value depending on how many layers you wish to display

Format:

For now, the output format is “html”. Just replace with other values according to the output format you want (for example: “pdf_document”).

In the end, the YAML block should look like this:

    ---
    title: "My first R Markdown script"
    author: "Your name"
    date: "This document was last modified on `r Sys.Date()`"
    output: pdf_document
    toc: yes
    toc-depth: 4
    ---

2.2 Navigating the file: Titles and subparts

The titles and subparts are here to give the overall structure of the document. Please note that they are optional: It is possible to write a whole R Markdown document without any title! But as the codes are more and more lengthy, it becomes messy very easily to the point that it is very difficult to understand what we are doing. In other words, the titles and subparts are here to clarify everything!

Adding titles and subparts is very simple. You just need to click on the button where the header options can be found. For example, if you want to write the title of a main part (let’s say, “1. Introduction”), you click on “Header 1”, and you write the name of the title. It is the same process for subtitles. Let’s say you want a subpart called “1.1 Introduction within the introduction”, you just click on “Header 2” and you write what you want for the subtitle.

Tip

I personally prefer when the structure is numbered, this is why I add the number of the sections like “1. Introduction”, or “1.1 Introduction of the introduction”. But this is not obligatory and depends on your style!

The titles and subparts are also very important to set the table of contents!

2.3 Writing the content

2.3.1 Writing the narrative

Nothing more simple: You can write directly inside the document. Just do not forget to check that the style is set as “Normal” and not “Header 1”, “Header 2”, etc. when doing so!

This is a big difference with R Script. Everything you write in an R Script is considered as a code, unless you use the hashtag signs to tell R that this is a comment. In other words, everything that you write in the document is considered as a comment, so do not hesitate to write as much as you want as long as it makes things clearer for you!

2.3.2 Writing the code

If what we write inside the document is not considered as a code, then how to add one?

You Just need to click on “Insert”, then “Code Chunk”, and finally “R”. Normally, a grey code block with appear with {r} at the top line to indicate that this is an R code block. Everything written in this grey block will be considered as R code. You can also add comments inside the block using hashtags as you can do in a typical R Script.
Sometimes, R will display simple messages and/or warnings at the same time as you run the code. It is possible to “hide” them, you just need to add the following lines below {r}, as below.

Your code chunk will look like this:

Finally, you can run the code chunk without running ALL the document. Can you see the green ‘play’ logo on the top right of the code chunk? You just need to click on it!

4 Markdown and PDF documents of Sections 1.2 and 1.3

Maybe you were playing with your own R Markdown document at the same time as you were following this section, and add the codes of the Section 1.2 in it. In that case, congratulations! You have your very first R Markdown document ready! If not, you can just download the template here.

And here is the PDF output of the same document.