R Markdown Syntax

 



This article will help you to format text in your mind map using markdown. It includes the following steps: About markdown Supported. Metaculus: mapping the future.

Basic Formatting

  • Bold: **Bold**
  • Emphasized: *Emphasized*
  • Strikethrough : ~~Strikethrough~~
  • Horizontal rules: --- (three hyphens), *** (three asterisks), or ___ (three underscores).

Headings

All heading levels (e.g. H1, H2, etc), are marked by # at the beginning of a line. For example, an H1 is # Heading 1 and an H2 is ## Heading 2. This continues to ###### Heading 6.

Links

Links can be created using several methods:

  • Links can be [inline](https://markdowntohtml.com)
  • Inline links can [have a title](https://markdowntohtml.com 'Awesome Markdown Converter')
  • Also, there can be reference links that allow the URL to be placed later in the document:
    • Here is a [reference link][markdowntohtml] that links to this site.
    • References are case-insensitive (for example [this link][MarkDownToHTML] works).
    • References can also [use numbers][1].
    • Or leave it empty and use the [link text itself].
  • Also, you can use relative links [like this](../blob/master/LICENSE.txt).
  • URLs and URLs in angle brackets will automatically get turned into links: https://markdowntohtml.com or <https://markdowntohtml.com>.
URLs for reference links are somewhere later in the document like this:

Images

Images can also be inline or use a reference style, similar to links. Simply prepend an exclamation point to turn the link into an image. For example:

Overview

R Markdown combines markdown (an easy to write plain text format) with embeddedR code chunks. When compiling R Markdown documents, the code components can beevaluated so that both the code and its output can be included in the finaldocument. This makes analysis reports highly reproducible by allowing to automaticallyregenerate them when the underlying R code or data changes. R Markdowndocuments (.Rmd files) can be rendered to various formats including HTML andPDF. The R code in an .Rmd document is processed by knitr, while theresulting .md file is rendered by pandoc to the final output formats(e.g. HTML or PDF). Historically, R Markdown is an extension of the olderSweave/Latex environment. Rendering of mathematical expressions and referencemanagement is also supported by R Markdown using embedded Latex syntax andBibtex, respectively.

Quick Start

Install R Markdown

Initialize a new R Markdown (Rmd) script

To minimize typing, it can be helful to start with an R Markdown template andthen modify it as needed. Note the file name of an R Markdown scirpt needs tohave the extension .Rmd. Template files for the following examples are available here:

  • R Markdown sample script: sample.Rmd
  • Bibtex file for handling citations and reference section: bibtex.bib

Users want to download these files, open the sample.Rmd file with their preferred R IDE (e.g. RStudio, vim or emacs), initilize an R session and then direct their R session to the location of these two files.

Metadata section

The metadata section (YAML header) in an R Markdown script defines how it will be processed and rendered. The metadata section also includes both title, author, and date information as well as options for customizing the output format. For instance, PDF and HTML output can be defined with pdf_document and html_document, respectively. The BiocStyle:: prefix will use theformatting style of the BiocStyle package from Bioconductor.

Render Rmd script

An R Markdown script can be evaluated and rendered with the following render command or by pressing the knit button in RStudio.The output_format argument defines the format of the output (e.g.html_document). The setting output_format='all' will generate all supported output formats. Alternatively, one can specify several output formats in the metadata section as shown in the above example.

The following shows two options how to run the rendering from the command-line.

Alternatively, one can use a Makefile to evaluate and render an R Markdownscript. A sample Makefile for rendering the above sample.Rmd can bedownloaded here.To apply it to a custom Rmd file, one needs open the Makefile in a texteditor and change the value assigned to MAIN (line 13) to the base name ofthe corresponding .Rmd file (e.g. assign systemPipeRNAseq if the filename is systemPipeRNAseq.Rmd). To execute the Makefile, run the followingcommand from the command-line.

R code chunks

R Code Chunks can be embedded in an R Markdown script by using three backticksat the beginning of a new line along with arguments enclosed in curly bracescontrolling the behavior of the code. The following lines contain theplain R code. A code chunk is terminated by a new line starting with three backticks.The following shows an example of such a code chunk. Note the backslashes arenot part of it. They have been added to print the code chunk syntax in this document.

R Markdown Syntax

The following lists the most important arguments to control the behavior of R code chunks:

  • r: specifies language for code chunk, here R
  • chode_chunk_name: name of code chunk; this name needs to be unique
  • eval: if assigned TRUE the code will be evaluated
  • warning: if assigned FALSE warnings will not be shown
  • message: if assigned FALSE messages will not be shown
  • cache: if assigned TRUE results will be cached to reuse in future rendering instances
  • fig.height: allows to specify height of figures in inches
  • fig.width: allows to specify width of figures in inches

For more details on code chunk options see here.

Learning Markdown

The basic syntax of Markdown and derivatives like kramdown is extremely easy to learn. Ratherthan providing another introduction on this topic, here are some useful sites for learning Markdown:

Tables

There are several ways to render tables. First, they can be printed within the R code chunks. Second, much nicer formatted tables can be generated with the functions kable, pander or xtable. The followingexample uses kable from the knitr package.

Sepal.Length Sepal.Width Petal.Length Petal.Width Species

Figures

Plots generated by the R code chunks in an R Markdown document can be automatically inserted in the output file. The size of the figure can be controlled with the fig.heightand fig.width arguments.

Sometimes it can be useful to explicitly write an image to a file and then insert that image into the final document by referencing its file name in the R Markdown source. For instance, this can be useful for time consuming analyses. The following code will generate a file named myplot.png. To insert the file in the final document, one can use standard Markdown or HTML syntax, e.g.: <img src='../Rbasics_files/myplot.png'/>.

Inline R code

To evaluate R code inline, one can enclose an R expression with a single back-tickfollowed by r and then the actual expression. For instance, the back-ticked version of ‘r 1 + 1’ evaluates to 2 and ‘r pi’ evaluates to 3.1415927.

R Markdown Table Syntax

Mathematical equations

To render mathematical equations, one can use standard Latex syntax. When expressions are enclosed with single $ signs then they will be shown inline, while enclosing them with double $$ signs will show them in display mode. For instance, the following Latex syntax d(X,Y) = sqrt[]{ sum_{i=1}^{n}{(x_{i}-y_{i})^2} } renders in display mode as follows:

R Markdown Syntax

Citations and bibliographies

R Markdown Bold Math

Citations and bibliographies can be autogenerated in R Markdown in a similarway as in Latex/Bibtex. Reference collections should be stored in a separatefile in Bibtex or other supported formats. To cite a publication in an R Markdown script, one uses the syntax (@<id1>) where <id1> needs to be replaced with a reference identifier present in the Bibtex database listed in the metadata section of the R Markdown script (e.g.bibtex.bib). For instance, to cite Lawrence et al. (2013), one uses its reference identifier (e.g.Lawrence2013-kt) as <id1> (Lawrence et al., 2013). This will place the citation inline in the text and add the correspondingreference to a reference list at the end of the output document. For the latter a special section called References needs to be specified at the end of the R Markdown script.To fine control the formatting of citations and reference lists, users want to consult this the corresponding R Markdown page.Also, for general reference management and outputting references in Bibtex format Paperpile can be very helpful.