1 Markdown and RMarkdown

This document is written in Markdown, which is a “lightweight” markup language (like HTML), that uses a relatively simple syntax, and facilitates the transformation of human-readible text files into .html or .pdf documents. RMarkdown is a an R package, and a set of tools that are deeply embedded in RStudio that facilitates the construction of documents that combine text, R code and the output from the execution of that code, and that range in complexity from a single .html or .pdf file, to multi-page web sites, to books.

RMarkdown thereby facilitates the concepts of “literate programming” link, and “reproducible research” link, which, in addition to explaining or documenting itself, also allows others (including an original investigator after some time has passed) to reproduce a data analysis or other research result.

1.1 Markdown

Here is a simple Markdown (.md) file:

# Introduction #

Some text, and little discussion, including a bulleted list
- first list item
- second list time

## Some code ##

Here is a little code (and note the different font):

```
plot(orstationc$elev, orstationc$tann)
```
and some more text, possibly *decorated* or **otherwise formatted**.
And here is what the file looks like when rendered:

Introduction

Some text, and little discussion, including a bulleted list

  • first list item
  • second list time

Some code

Here is a little code (and note the different font):

plot(orstationc$elev, orstationc$tann)

and some more text, possibly decorated or otherwise formatted.

Although the syntax of Markdown is relatively simple, quite complex documents can be generated using conversion tools like Pandoc (see the Resources section below).

1.2 RStudio/RMarkdown

RStudio allows the use of Markdown formatting styles within RMarkdown .Rmd files, allowing the resulting combinations of text, code and output to be nicely formatted. RNotebook and RMarkdown files in RStudio can be viewed as elements in a hierarchy of increasingly well-documented and reproducible code, with ordinary R script files *.R as the lowest level, and complicated RMarkdown web sites or even books at the highest level.

RMarkdown is implemented by two packages (and their dependencies), rmarkdown and knitr. The packages can be installed as follows

install.packages("rmarkdown')
install.packages("knitr")

The following examples can be reproduced using this data set: cru10min30_bio.nc, and the following shapefile components:

  • ne_110m_admin_0_countries.cpg
  • ne_110m_admin_0_countries.dbf
  • ne_110m_admin_0_countries.prj
  • ne_110m_admin_0_countries.shp
  • ne_110m_admin_0_countries.shx

(Transfer the files to a convenient working folder(s), and modify the paths in the scripts below.)

[https://pjbartlein.github.io/REarthSysSci/plot_alpha_Scripts_and_Rmd_files]

  • *.R Scripts: input is a plain script, and output appears in the Console or Plots pane: [plot_alpha_RScript.R]
  • *.Rmd RNotebook files: input is an RMarkdown file (with a special header), output appears “inline” in RStudio and code, comments and output are saved in a *.nb.html file that is portable: [plot_alpha_RMarkdown_Notebook.Rmd]
  • *.Rmd RMarkdown files: input is an RMarkdown file (with a special header), output appears as an .html file, viewable in a browser or internally in RStudio: [plot_alpha_RMarkdown_1Page.Rmd]
  • *.Rmd RMarkdown files: input is an RMarkdown file (with a different special header) and a *.css file, output appears as an .html file, viewable in a browser or internally in RStudio: [plot_alpha_RMarkdown_Site.Rmd]
  • multiple *.Rmd and .md files, along with a “site YAML” file, as input, a multipage website or book with internal navigation as output. (This is how the course web pages are constructed.) [https://github.com/pjbartlein/REarthSysSci]

1.3 Markdown resources

1.3.2 Markdown editors

The easiest way to learn Markdown is to use a dual pane (editing and previewing) Markdown editor, where it’s easy to instantly see the consequences of applying Markdown formatting.

To get the formatting style used in this document (and the course web page), download: html-d-01.css
(https://pjbartlein.github.io/REarthSysSci/html-md-01.css):

  • MarkdownPad: Download the file and open it in a text editor. Then in the MarkdownPad Tools > Options > Stylesheets dialog, click on add, and copy and paste the contents of html-md-01.css, and then save and close with that name.
  • Macdown:
  • Download the file to e.g. /Users/bartlein/Library/Application Support/MacDown/Styles/. (Note that the Library folder is usually hidden from Finder, and you may have to use a file manager that can reveal hidden files.)
  • Restart Macdown, and use the Preferences > Rendering tab to set html-md-01.css in the CSS field.

1.3.3 Pandoc

Pandoc is the rendering engine that RMarkdown uses, and it can also be used by itself to convert a large array of document types.