Useful YAML options for generating HTML reports in R

I think most people start using R with scripts initially. Scripts are great for modular computational tasks, but for generating informative reports, Rmarkdown is a must. Rmd makes it possible to use a YAML header to specify certain parameters right at the beginning of the document. Built-in YAML parameters make it easier to create more organized and informative reports. In this post, I will share with you few of the YAML options I commonly use for generating HTML outputs in my data analysis projects. You can check out the following resources for details about tons of other options:

• rmarkdown guide
• ?rmarkdown::html_document() help file
• Yihui Xie’s Talk at 2017 RStudio Conference
• Variables section of the Pandoc user guide

YAML header in an Rmd file looks like this:

---
title: My analysis file
author: Atakan Ekiz
date: August 6, 2020     # can execute R code here (see below)
output: html_document
---

Below you can find some general and HTML output-specific YAML options. However, Rmarkdown can also be used to generate other types of reports (such as PDF, Word, Powerpoint, etc.) (see more here)

General YAML metadata options

• title: A descriptive main title (no need for quotes)
• author: Name of the author(s)
  • You can use lists for multiple authors and for adding other metadata:

author:
 - Name_1   # can be indented or not
 - Name_2   # but be consistent among different entries

 author:
   - name: Name_1                              # can list separate items
     affiliation: University of Someplace      # same amt of indentation needed
   - name: Name_2
     affiliaion: University of SomeOtherPlace

• date: You can hard-code this or execute R code to automate it. The language needs to be specified as and the code needs to be wrapped with backticks and quotes ("`r function_call()`").

date: "`r format(Sys.time(), '%d %B, %Y')`"   # nicely formatted
date: "`r lubridate::today()`"                # can use functions from pkgs

• abstract: Useful for summarizing the analysis. Centered text will be displayed before the content of the document. Multiple paragraphs can be specified but they must be indendented and preceded by the OR sign:

abstract: |
 First paragraph of what may be the best abstract ever written. It is a
 beautiful abstract because nobody writes abstracts better than I do.

 Second paragraph of the abstract continues to be just magnificent. It is 
 simply because I'm a very stable genius. OK, SERIOUS NOW: HTML code can be
 also added to leave some breating space after abstract such as <br><br><br>

html_document specific YAML options

These variables need to be indented under the html_document option. Some of my favorites are:

• toc: true/false to show table of contents. It creates links to headings throughout the html_document
• toc_depth: A number (default 3) determining how many subheadings will be visible in the TOC
• toc_float: true/false determining whether the TOC stays visible when you scroll down.
• number_sections: true/false to organize the document with numeric headings
• code_folding: true/false to display code in collapsible sections (especially useful when sharing the analysis with others who don’t care about the code itself). It can be one of “none”, “hide”, “show”.
• theme: Change the overall look of the report. It can be one of “default”, “cerulean”, “journal”, “flatly”, “darkly”, “readable”, “spacelab”, “united”, “cosmo”, “lumen”, “paper”, “sandstone”, “simplex”, “yeti”.
• includes: I don’t usually use this really, but I can see how powerful it can be. Indented underneath this variable, you can specify HTML contents to display in the page header or before/after the page body. This can be useful for including logos, details of the analytical approach, interpretations of the results, contact us sections, Google Analytics tracking code snippet etc:

includes:
  in_header: header.html       
  before_body: doc_prefix.html 
  after_body: doc_suffix.html  

Finally, a complete YAML example:

---
title: Our groundbreaking analysis that will lead to world peace
author:
   - name: John, the Problem Solver
     affiliation: Get Shiz Done University
   - name: Jack, the Supposed Contributor
     affiliation: Living Room Couch
date: "`r lubridate::today()`"
abstract: |
 Our analysis shows that the main reason of global conflicts can be attributed 
 to the insufficient amounts of Nutella consumption in situation rooms. 

 It turns out that the government officials across the globe are a bit grumpy
 when they get hungry leading to bad decision-making. You are welcome...
 <br><br><br>
output:
  html_document:
    toc: true
    toc_float: true
    toc_depth: 2
    number_sections: true
    code_folding: hide
    theme: readable
---

Rmarkdown is just awesome! I would say almost as good as Nutella! I feel like I keep learning hidden (?) features of R and Rmarkdown every day. For instance, I just realized that subheaders in the HTML report can be shown under different tabs on the same page. The result is a gorgeous and neatly organized HTML report! I’m sure the awesomeness doesn’t end there. Let me know if you have other favorite features in Rmarkdown/YAML to streamline your analyses and increase your productivity.