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.
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:
Some text, and little discussion, including a bulleted list
Here is a little code (and note the different font):
plot(orstationc$elev, orstationc$tann)
Although the syntax of Markdown is relatively simple, quite complex documents can be generated using conversion tools like Pandoc (see the Resources section below).
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]*.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]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):
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./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.)html-md-01.css
in the CSS field.Pandoc is the rendering engine that RMarkdown uses, and it can also be used by itself to convert a large array of document types.