Prerequisites

Bioconductor R Markdown format is build on top of R package r CRANpkg("bookdown"), which in turn relies on r CRANpkg("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.

Getting started

To enable the Bioconductor style in your R Markdown vignette you need to:

The vignette section is required in order to instruct R how to build the vignette.^[\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.

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 r CRANpkg('markdown') vignette builder engine:

The way of attaching CSS files when using r CRANpkg('markdown') differs from how this is done with r CRANpkg('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`r ''`
BiocStyle::markdown(css.files = c('custom.css'))
```

Document header

Author affiliations

The author field allows for specifing author names along with affiliation and email information.

In the basic case, when no additional information apart from author names is provided, these can be entered as a single character string

author: "Single Author"

or a list

author:
- First Author
- Second Author
- Last Author

which will print as "First Author, Second Author and Last Author".

Author affiliations and emails can be entered in named sublists of the author list. Multiple affiliations per author can be specified this way.

author:
- name: First Author
  affiliation: 
  - Shared affiliation
  - Additional affiliation
- name: Second Author
  affiliation: Shared affiliation
  email: corresponding@author.com

A list of unique affiliations will be displayed below the authors, similar as in this document.

For clarity, compactness, and to avoid errors, repeated nodes in YAML header can be initially denoted by an anchor entered with an ampersand &, and later referenced with an asterisk *. For example, the above affiliation metadata is equivalent to the shorthand notation

author:
- name: First Author
  affiliation: 
  - &id Shared affiliation
  - Additional affiliation
- name: Second Author
  affiliation: *id
  email: corresponding@author.com

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.^[only relevant to PDF output]

Style macros

macro <- function(name, pkg, description)
    sprintf('`%s("%s")` %s %s', name, pkg,
            description, do.call(name, list(pkg)))
inline <- function(cmd) sprintf('`` `r %s` ``', cmd)

r Biocpkg("BiocStyle") introduces the following macros useful when referring to R packages:

These are meant to be called inline, e.g., r inline('Biocpkg("IRanges")').

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").

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 numbered^[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 \@ref(cross-references). The figure label is generated from the code chunk label^[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)^[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 \@ref(fig:plot).

```r`r ''`
plot(cars)
```
plot(cars)

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 \@ref(fig:wide). Small figures are meant for possibly rectangular plots which are centered with respect to the text column, see Figure \@ref(fig:small).

plot(cars)
plot(cars)

Tables

Like figures, tables with captions will also be numbered and can be referenced. The caption is entered as a paragraph starting with Table:^[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 \@ref(tab:table) 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

: (#tab:table) A simple table. With caption.

The function knitr::kable() will automatically generate a label for a table environment, which is the chunk label prefixed by tab:, see Table \@ref(tab:mtcars).

knitr::kable(
  head(mtcars[, 1:8], 10), caption = 'A table of the first 10 rows of `mtcars`.'
)

Equations

To number and reference equations, put them in equation environments and append labels to them following the syntax (\#eq:label)^[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} (#eq:binom) \end{equation}

You may then refer to Equation \@ref(eq:binom) by \@ref(eq:binom). Note that in HTML output only labeled equations will appear numbered.

Cross-references

Apart from referencing figures (Section \@ref(figures)), tables (Section \@ref(tables)), and equations (Section \@ref(equations)), 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 \@ref(non-existing-label), as well as a warning message in the R console when rendering the document.

Margin notes

Footnotes are displayed as side notes on the right margin^[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 {.unnumbered}

Here is the output of sessionInfo() on the system on which this document was compiled running pandoc r rmarkdown::pandoc_version():

sessionInfo()


aoles/BiocStyle documentation built on Oct. 15, 2021, 4:50 a.m.