Authoring R Markdown vignettes
17 June 2021
Abstract
Instructions on enabling Bioconductor style in R Markdown vignettes.
Package
BiocStyle 2.20.2
1 Prerequisites
Bioconductor R Markdown format is build on top of R package bookdown, which in turn relies on rmarkdown and pandoc to compile the final output document. Therefore, unless you are using RStudio, you will need a recent version of pandoc (>= 1.17.2). See the pandoc installation instructions for details on installing pandoc for your platform.
2 Getting started
To enable the Bioconductor style in your R Markdown vignette you need to:
Edit the
DESCRIPTIONfile by addingVignetteBuilder: knitr Suggests: BiocStyle, knitr, rmarkdownSpecify
BiocStyle::html_documentorBiocStyle::pdf_documentas output format and add vignette metadata in the document header:--- title: "Vignette Title" author: "Vignette Author" package: PackageName output: BiocStyle::html_document vignette: > %\VignetteIndexEntry{Vignette Title} %\VignetteEngine{knitr::rmarkdown} %\VignetteEncoding{UTF-8} ---
The vignette section is required in order to instruct R how to build the
vignette.1 \VignetteIndexEntry should match the title of your vignette The
package field which should contain the package name is used to print the
package version in the output document header. It is not necessary to specify
date as by default the document compilation date will be automatically
included. See the following section for details on specifying author
affiliations and abstract.
BiocStyle’s html_document and pdf_document format functions extend the
corresponding original rmarkdown formats, so they accept the same arguments as
html_document and pdf_document, respectively. For example, use toc_float: true to obtain a floating TOC as in this vignette.
2.1 Use with R markdown v1
Apart from the default markdown engine implemented in the r CRANpkg('rmarkdown') package, it is also possible to compile Bioconductor
documents with the older markdown v1 engine from the package r CRANpkg('markdown'). There are some differences in setup and the resulting
output between these two engines.
To use the markdown vignette builder engine:
Edit the
DESCRIPTIONfile to includeVignetteBuilder: knitr Suggests: BiocStyle, knitrSpecify the vignette engine in the
.Rmdfiles (inside HTML comments)<!-- %% \VignetteEngine{knitr::knitr} -->Add the following code chunk at the beginning of your
.Rmdvignettes```{r style, echo = FALSE, results = 'asis'} BiocStyle::markdown() ```
The way of attaching CSS files when using markdown differs from
how this is done with rmarkdown. In the former case additional
style sheets can be used by providing them to the BiocStyle::markdown
function. To include custom.css file use
```{r style, echo = FALSE, results = 'asis'}
BiocStyle::markdown(css.files = c('custom.css'))
```3 Document header
3.2 Abstract and running headers
Abstract can be entered in the corresponding field of the document front matter, as in the example below.
---
title: "Full title for title page"
shorttitle: "Short title for headers"
author: "Vignette Author"
package: PackageName
abstract: >
Document summary
output:
BiocStyle::pdf_document
---The shorttitle option specifies the title used in running headers instead of
the document title.2 only relevant to PDF output
4 Style macros
BiocStyle introduces the following macros useful when referring to R packages:
Biocpkg("IRanges")for Bioconductor software, annotation and experiment data packages, including a link to the release landing page or if the package is only in devel, to the devel landing page, IRanges.CRANpkg("data.table")for R packages available on CRAN, including a link to the FHCRC CRAN mirror landing page, data.table.Githubpkg("rstudio/rmarkdown")for R packages available on GitHub, including a link to the package repository, rmarkdown.Rpackage("MyPkg")for R packages that are not available on Bioconductor, CRAN or GitHub; MyPkg.
These are meant to be called inline, e.g., `r Biocpkg("IRanges")`.
5 Code chunks
The line length of output code chunks is set to the optimal width of typically
80 characters, so it is not neccessary to adjust it manually through
options("width").
6 Figures
BiocStyle comes with three predefined figure sizes. Regular figures not otherwise specified appear indented with respect to the paragraph text, as in the example below.
plot(cars)
Figures which have no captions are just placed wherever they were generated in
the R code. If you assign a caption to a figure via the code chunk option
fig.cap, the plot will be automatically labeled and numbered3 for PDF output
it will be placed in a floating figure environment, and it will be also
possible to reference it. These features are provided by r CRANpkg("bookdown"), which defines a format-independent syntax for specifying
cross-references, see Section 9. The figure label is
generated from the code chunk label4 for cross-references to work the chunk
label may only contain alphanumeric characters (a-z, A-Z, 0-9), slashes (/), or
dashes (-) by prefixing it with fig:, e.g., the label of a figure originating
from the chunk foo will be fig:foo. To reference a figure, use the syntax
\@ref(label)5 do not forget the leading backslash!, where label is the
figure label, e.g., fig:foo. For example, the following code chunk was used to
produce Figure 1.
```{r plot, fig.cap = "Regular figure. The first sentence...", echo = FALSE}
plot(cars)
```
Figure 1: Regular figure
The first sentence of the figure caption is automatically emphasized to serve as figure title.
In addition to regular figures, BiocStyle provides small and wide figures
which can be specified by fig.small and fig.wide code chunk options. Wide
figures are left-aligned with the paragraph and extend on the right margin, as
Figure 2. Small figures are meant for possibly rectangular plots
which are centered with respect to the text column, see Figure 3.
Figure 2: Wide figure
A plot produced by a code chunk with option fig.wide = TRUE.
Figure 3: Small figure
A plot produced by a code chunk with option fig.small = TRUE.
7 Tables
Like figures, tables with captions will also be numbered and can be referenced.
The caption is entered as a paragraph starting with Table:6 or just :,
which may appear either before or after the table. When adding labels, make sure
that the label appears at the beginning of the table caption in the form
(\#tab:label), and use \@ref(tab:label) to refer to it. For example, Table
1 has been produced with the following code.
Fruit | Price
------- | -----
bananas | 1.2
apples | 1.0
oranges | 2.5
: (\#tab:table) A simple table. With caption.| Fruit | Price |
|---|---|
| bananas | 1.2 |
| apples | 1.0 |
| oranges | 2.5 |
The function knitr::kable() will automatically generate a label for a table
environment, which is the chunk label prefixed by tab:, see Table
2.
knitr::kable(
head(mtcars[, 1:8], 10), caption = 'A table of the first 10 rows of `mtcars`.'
)| mpg | cyl | disp | hp | drat | wt | qsec | vs | |
|---|---|---|---|---|---|---|---|---|
| Mazda RX4 | 21.0 | 6 | 160.0 | 110 | 3.90 | 2.620 | 16.46 | 0 |
| Mazda RX4 Wag | 21.0 | 6 | 160.0 | 110 | 3.90 | 2.875 | 17.02 | 0 |
| Datsun 710 | 22.8 | 4 | 108.0 | 93 | 3.85 | 2.320 | 18.61 | 1 |
| Hornet 4 Drive | 21.4 | 6 | 258.0 | 110 | 3.08 | 3.215 | 19.44 | 1 |
| Hornet Sportabout | 18.7 | 8 | 360.0 | 175 | 3.15 | 3.440 | 17.02 | 0 |
| Valiant | 18.1 | 6 | 225.0 | 105 | 2.76 | 3.460 | 20.22 | 1 |
| Duster 360 | 14.3 | 8 | 360.0 | 245 | 3.21 | 3.570 | 15.84 | 0 |
| Merc 240D | 24.4 | 4 | 146.7 | 62 | 3.69 | 3.190 | 20.00 | 1 |
| Merc 230 | 22.8 | 4 | 140.8 | 95 | 3.92 | 3.150 | 22.90 | 1 |
| Merc 280 | 19.2 | 6 | 167.6 | 123 | 3.92 | 3.440 | 18.30 | 1 |
8 Equations
To number and reference equations, put them in equation environments and append
labels to them following the syntax (\#eq:label)7 due to technical constraints
equation labels must start with eq:, e.g.,
\begin{equation}
f\left(k\right) = \binom{n}{k} p^k\left(1-p\right)^{n-k}
(\#eq:binom)
\end{equation}renders the equation below.
\[\begin{equation} f\left(k\right) = \binom{n}{k} p^k\left(1-p\right)^{n-k} \tag{1} \end{equation}\]
You may then refer to Equation (1) by \@ref(eq:binom). Note that
in HTML output only labeled equations will appear numbered.
9 Cross-references
Apart from referencing figures (Section 6), tables (Section
7), and equations (Section 8), you can also use the
same syntax \@ref(label) to reference sections, where label is the section
ID. By default, Pandoc will generate IDs for all section headers, e.g., # Hello World will have an ID hello-world. In order to avoid forgetting to update the
reference label after you change the section header, you may also manually
assign an ID to a section header by appending {#id} to it.
When a referenced label cannot be found, you will see two question marks like ??, as well as a warning message in the R console when rendering the document.
10 Margin notes
Footnotes are displayed as side notes on the right margin8 this is a side note entered as a footnote, which has the advantage that they appear close to the place where they are defined.
Session info
Here is the output of sessionInfo() on the system on which this document was
compiled running pandoc 2.7.3:
## R version 4.1.0 (2021-05-18)
## Platform: x86_64-w64-mingw32/x64 (64-bit)
## Running under: Windows Server 2012 R2 x64 (build 9600)
##
## Matrix products: default
##
## locale:
## [1] LC_COLLATE=C
## [2] LC_CTYPE=English_United States.1252
## [3] LC_MONETARY=English_United States.1252
## [4] LC_NUMERIC=C
## [5] LC_TIME=English_United States.1252
##
## attached base packages:
## [1] stats graphics grDevices utils datasets methods base
##
## other attached packages:
## [1] BiocStyle_2.20.2
##
## loaded via a namespace (and not attached):
## [1] Rcpp_1.0.6 bookdown_0.22 digest_0.6.27
## [4] R6_2.5.0 jsonlite_1.7.2 magrittr_2.0.1
## [7] evaluate_0.14 highr_0.9 stringi_1.6.2
## [10] rlang_0.4.11 jquerylib_0.1.4 magick_2.7.2
## [13] bslib_0.2.5.1 rmarkdown_2.9 tools_4.1.0
## [16] stringr_1.4.0 xfun_0.24 yaml_2.2.1
## [19] compiler_4.1.0 BiocManager_1.30.16 htmltools_0.5.1.1
## [22] knitr_1.33 sass_0.4.0