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:
- 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 (
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
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...
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.