Communication: Reproducible report writing

Author

Kurt Hilton (Fisheries Officer), Dominica

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

  1. Creating a Rmarkdown file
  2. Parts of Rmarkdown document
  3. Basic syntax
  4. 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.

Note
  1. File -> New file -> R markdown…
  2. Type in title of file, name of author and select “use current date when rendering document”
  3. Default Output Format: select HTML
  4. 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.

---
title: "Communication: Reproducible report writing" 
author: "Kurt Hilton"
date: "`r format(Sys.Date(), '%d %B %Y')`"
output: 
  html_document:
    toc: yes
    df_print: paged
    output_dir: rmarkdown::render(here::here("04_reports"))
  word_document:
    toc: yes
    df_print: 
---
Important

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.

Save some time

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

Note

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: ![](http://example.com/logo.png)

  • 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:

  1. Add a comments code chunk to your file and add comments that will help future you to understand your code.
  2. 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.
  3. 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.
  4. Experiment break stuff, repair and learn through building projects and reports.