R Markdown reports

Introduction

R Markdown is a document format that combines R code with narrative text. It allows you to create reports, presentations, and other documents that include both your data analysis, results, and explanations. You write your content in plain text, interspersed with code chunks that can be executed. When you render an R Markdown document, it generates a final output (e.g., PDF, HTML, or Word) that includes the code results and formatted text.

RMD file structure

The R Markdown file is a plain text file with an .rmd extension. The file is made up out of three different types of content 1) YAML header; 2) text; 3) code chunks. The functions of these are described below.

YAML header

The YAML header is found at the top of an .rmd file. The YAML identifies the final document format and provides you with opportunities to personalize the look and feel of your document. Nothing will ever be placed ahead of the YAML.

The YAML header is always enclosed in three dashes (—). Within the YAML you can have different settings. Some of the more commonly used settings are title, author, date, and output. The example below shows an example of a YAML header.

---
title: "Rmarkdown practical"
author: "Janssen"
date: "20/06/2024"
output: 
  word_document
---

In the example above we have given our report a title, included the author and report date as well as indicating we would like the output to be a word document.

Create formatting template

You will have seen when we knitted our sample markdown document using the YAML above, a word document was created. However, looking at this document it may not be formatted in a way you like. We can deal with this by creating a reference formatting document and including this in our YAML.

---
title: "Practical R Markdown"
author: "XJ"
date: "2024-06-20"
output: 
  word_document:
    reference_docx: WordTemplate.docx
---

Text

Once we have structured our YAML and developed our formatting document we can start thinking about creating the actual report. A good analytical report will include the analysis and results but also text to explain the main findings or perhaps even provide an introduction or outline of the methods. As discussed earlier R Markdown lets you combine this text with the analysis and results in a super easy way.

Headers

Section headers can be added using #. In this document our top headers (e.g. Introduction, RMD file structure, etc) are created using ##, the levels below (e.g. YAML header, Text) use ### and so fort.

Special text formats

Text can be added by typing as normal but you can format it too. There are several ways in which to do this, first up we can format the overall layout and headers/ text via the formatting document we just created. However, you may want to highlight certain sections in bold, italic, or even underline it. You can do this in the following ways:

  • Italic - *TEXT* will put the text in italics.
  • Bold - **TEXT** will bold the text.
  • Underline - [TEXT]{.underline} will underline the text.
  • Superscripta - ^a^ at the end of a word or letter will put the text as superscript.
  • Subscripta - one ~a~ at the end of a word or letter will put the text as subscript.

Creating lists

R Markdown’s lists options are a bit limited but you can create ordered lists (e.g. 1, 2, 3) or unordered lists (e.g. using symbols). To create ordered lists you will use the numbers with a . behind them:

  1. First item
  2. Second item
    • sub-item 1
    • sub-item 2

To create unordered lists you will do the same but with symbols:

  • First item
  • Second item
    • First sub item
    • Second sub item

Page breaks

You may want to structure your document so new sections start on a new page. To do this in R Markdown you can just type \newpage.

Code

As data analysts your code is hugely important and to ensure reproducibility we often share our code together with the results. In R Markdown code can be included either as code chunks or inline code.

Code chunks

Code chunks can be included by adding the following ``` {r SETTINGS} CODE ```. En example code chunk has been provided below:

# Load relevant libraries (normally at start of your document)
library(tidyverse)

# Load data
NBADataDF <- as.tibble(read.csv("https://strath-my.sharepoint.com/:x:/g/personal/xanne_janssen_strath_ac_uk/ESqxkOF7xgtAtAxpNuWfVZAB1x-wJcNDO8yuuAnsv3PSow?download=1"))

# Display first 10 rows
NBADataDF[1:5,2:10] %>%
  head(10)
# A tibble: 5 × 9
  Pos     Age Team      G    GS    MP    FG   FGA FG_Per
  <chr> <int> <chr> <int> <int> <dbl> <dbl> <dbl>  <dbl>
1 PF       26 DEN      75    75  31.7   5.8  11.1  0.52 
2 SF       22 PHI       6     0   2.8   0.2   0.8  0.2  
3 PG       25 TOT      63    15  16.2   2.4   5.4  0.447
4 PG       25 WAS      41    14  16.2   2.4   5.2  0.467
5 PG       25 PHO      22     1  16.3   2.3   5.6  0.411

You could also include code which I may not want in my report. You can do that by setting the echo=FALSE. For reproducibility reasons you may not do this very often but the following section may highlight some cases in which you want to use this.

Inline code

You can also include short code within the text. For example I could choose to pull out some data from the table above by saying Aaron Gordon plays for DEN and is 26 years of age. Now these are occasions where you may not want to show the code that let’s you show thise in text results.

Exercises

Exercise 1: Create a new RMarkdown document in RStudio and save it as MyFirstReport.rmd. Note you may need to install the RMarkdown package first.

Exercise 2: In MyFirstReport.rmd modify the YAML header to include your name, today’s date, and change the title to “My First Data Report”.

Exercise 3: Add two level 1 headings called “Introduction” and “Methods” write a short paragraph of text for both. Then add a level 2 heading called “Study design” under the Methods” section header.

Exercise 4: Knit your document. Try to change the formatting of the title, header 1, header 2, and general text in word and then save this document as “Word_Template” (it is important to save it with a name different to your .rmd file). This is now our formatting template.

Exercise 5: In your MyFirstReport.rmd update your YAML to include the “Word_Template.docx”. Add a level 1 heading called “Results” and type a short section, followed by a level 2 heading called “Descriptives”. Knit your work again and check the formatting has been updated.