Communication: Reproducible report writing
Preamble
Rmarkdown
R Markdown is a powerful tool that allows you to create high-quality documents, reports, presentations, and dashboards by weaving together narrative text and code. It supports multiple languages including R, Python, and SQL, and can produce output in a variety of formats including HTML, PDF, and MS Word.
Why use Rmarkdown?
Reproducibility :R Markdown documents are fully reproducible. This means that the code and data used to generate the output are included in the document itself, making it easy to share your work with others and for them to reproduce your results.
Multiple languages :R Markdown supports multiple languages including R, Python, and SQL. This means that you can include code from different languages in the same document.
Multiple output formats: R Markdown can produce output in a variety of formats.
This guide introduces
- Creating a Rmarkdown file
- Parts of Rmarkdown document
- Basic syntax
- Inline code
Recommended reading and reference: R markdown: The Definitive Guide
Creating a Rmarkdown file (.rmd)
After creating your project file and folders the following steps can be used to create you rmarkdown file.
- File -> New file -> R markdown…
- Type in title of file, name of author and select “use current date when rendering document”
- Default Output Format: select HTML
- Press “OK”
Parts of Rmarkdown document
YAML header
The YAML (yah-mul) header contains guidelines and information on formatting of document. There are many options that you can specify in the YAML header of an R Markdown document.
Some common options include:
title: The title of the document.
author: The author of the document.
date: The date of the document.
output: The output format of the document, such as html_document, pdf_document, or word_document.
toc: Whether to include a table of contents in the output document.
number_sections: Whether to number sections in the output document.
The following code can be copied, altered and used as a guide.
---
: "Communication: Reproducible report writing"
title: "Kurt Hilton"
author: "`r format(Sys.Date(), '%d %B %Y')`"
date:
output:
html_document: yes
toc: paged
df_print: rmarkdown::render(here::here("04_reports"))
output_dir:
word_document: yes
toc:
df_print---
YAML headings that are not formatted correctly will prevent code from knitting. Look out for possible errors such as;
Error in yaml::yaml.load(…, eval.expr = TRUE) : Scanner error: mapping values are not allowed in this context at line 6, column 8 Calls: <Anonymous> … parse_yaml_front_matter -> yaml_load -> <Anonymous> Execution halted
Code chunks
Code chunks are basic units of code in R Markdown that look like ```{r} #Code here ```
, that allow you to include R code straight into your document.
Quickly insert chunks into your file with the keyboard shortcut
Ctrl + Alt + I (windows) or (Cmd + Option + I) (Mac)
When you render your .Rmd file, R Markdown will run each code chunk and embed the results beneath the code chunk in your final report.
Chunk options can be added after the name of the chunk and a comma, like {r name, option = value
}. They control the display of the output, such as hiding or showing the code, or running or not running the code.
Some common code chunk options are
include = FALSE
: prevents code and results from appearing in the finished file. R Markdown still runs the code in the chunk, and the results can be used by other chunks.
echo = FALSE
: prevents code, but not the results from appearing in the finished file. This is a useful way to embed figures.
message = FALSE
: prevents messages that are generated by code from appearing in the finished file.
warning = FALSE
: prevents warnings that are generated by code from appearing in the finished file.
fig.cap = "..."
: adds a caption to graphical results
Any text added outside of a code chunk will show up as document text in your report.
Basic Syntax
Headers:
# Header 1
,## Header 2
,### Header 3
Emphasis:
*italic*
,**bold**
,_italic_
,__bold__
Lists:
Unordered List:
* Item 1
,* Item 2
Ordered List:
1. Item 1
,2. Item 2
Links:
[linked phrase](http://example.com)
Images:

Block quotes:
> Quote
Inline Code:
add
Horizontal Rule / Page Break:
***
or---
Tables:
First Header | Second Header
-------------|--------------
Content Cell | Content Cell
Content Cell | Content Cell
Inline code
Inline code is used to embed small pieces of R code within the text of your document. It is written by enclosing the R code in back ticks and prefixing it with r
, like this:
`r 2+2`
When the document is rendered, the R code is executed and the result is inserted into the text. For example, if you write "The result of 2 + 2 is 4
", it will appear as "The result of 2 + 2 is 4" in the rendered document.
Examples of more advanced inline code includes:
# In these examples the assumption is that your dataset contains the following column names Year, weight, species, cost.
# df represents my dataset name.
# The code below can be used to inlcude min value of weight for dataset.
`r round(min(df$weight, na.rm=TRUE),0)`
# min can be replaced with max and mean.
`r round(max(df$weight,na.rm=TRUE),0)`
#replacing weight with any other column name will also produce results in your text.
`r round(max(df$cost,na.rm=TRUE),0)`
# running this code would list out all species present in your dataset
`r paste(unique(df$species), collapse = ", ")`
Conclusion
The possibilities are endless in Rmarkdown, taking a look at the recommended text surely will add some more context and make your reporting easier.
A few recommendations in closing would be to:
- Add a comments code chunk to your file and add comments that will help future you to understand your code.
- Keep things organized. Utilize code chunks for specific tasks. eg. Libraries, Loading data, cleaning your data if needed, creating plots, conducting analysis. This will save you the headache of wondering what’s going on in the future.
- If you already have a word document of a report you’re practically halfway done. Next task would be to paste in the text between code chunks and start adding in inline codes for values.
- Experiment break stuff, repair and learn through building projects and reports.