---
title: "Authoring R Markdown vignettes"
author:
- name: Andrzej Oleś
  affiliation: European Molecular Biology Laboratory, Heidelberg, Germany
- name: Wolfgang Huber
  affiliation: European Molecular Biology Laboratory, Heidelberg, Germany
- name: Martin Morgan
  affiliation: Roswell Park Cancer Institute, Buffalo, NY
output:
  BiocStyle::html_document:
    toc_float: true
  BiocStyle::pdf_document: default
package: BiocStyle
abstract: |
  Instructions on enabling _Bioconductor_ style in R Markdown vignettes.
vignette: |
  %\VignetteIndexEntry{Authoring R Markdown vignettes}
  %\VignetteEngine{knitr::rmarkdown}
  %\VignetteEncoding{UTF-8}
---


# 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](http://johnmacfarlane.net/pandoc/) to compile the final output
document. Therefore, unless you are using RStudio, you will need a recent
version of [pandoc](http://johnmacfarlane.net/pandoc/) (>= 1.17.2). See the
[pandoc installation
instructions](https://github.com/rstudio/rmarkdown/blob/master/PANDOC.md) for
details on installing pandoc for your platform.


# Getting started

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

- Edit the `DESCRIPTION` file by adding

        VignetteBuilder: knitr
        Suggests: BiocStyle, knitr, rmarkdown

- Specify `BiocStyle::html_document` or `BiocStyle::pdf_document` as 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.^[`\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:

- Edit the `DESCRIPTION` file to include

        VignetteBuilder: knitr
        Suggests: BiocStyle, knitr
        
- Specify the vignette engine in the `.Rmd` files (inside HTML comments)

        <!--
        %% \VignetteEngine{knitr::knitr}
        -->

- Add the following code chunk at the beginning of your `.Rmd` vignettes

        ```{r style, echo = FALSE, results = 'asis'}`r ''`
        BiocStyle::markdown()
        ```

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 style, echo = FALSE, results = 'asis'}`r ''`
    BiocStyle::markdown(css.files = c('custom.css'))
    ```


# Document header

## Author affiliations

The `author` field allows for specifying 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

```{r macro, echo=FALSE}
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:

* `r macro("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,")`.

* `r macro("CRANpkg", "data.table", "for _R_ packages available on CRAN,
including a link to the FHCRC CRAN mirror landing page,")`.

* `r macro("Githubpkg", "rstudio/rmarkdown", "for _R_ packages available on
GitHub, including a link to the package repository,")`.

* `r macro("Rpackage", "MyPkg", "for _R_ packages that are _not_ available on
_Bioconductor_, CRAN or GitHub;")`.

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

## Simple 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.

```{r no-cap, fig.alt="A default sized example figure without a caption."}
plot(cars)
```

## Figure captions

Figures which have no captions, like the one above, 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 plot, fig.cap = "Regular figure. The first sentence...", echo = FALSE}`r ''`
    plot(cars)
    ```

```{r plot, fig.cap="Regular figure. The first sentence of the figure caption is automatically emphasized to serve as figure title.", echo=FALSE}
plot(cars)
```

## Alternative figure sizes

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

```{r wide, fig.cap="Wide figure. A plot produced by a code chunk with option `fig.wide = TRUE`.", fig.wide=TRUE, echo=FALSE}
plot(cars)
```

```{r small, fig.cap="Small figure. A plot produced by a code chunk with option `fig.small = TRUE`.", fig.small=TRUE, echo=FALSE}
plot(cars)
```

## Accessibility considerations

Alt (alternative) text is used by screen readers to provide a description of an
image to visually impaired readers.  If you provide a figure caption with
`fig.cap` the same text will automatically be used as the alt text for the
image.  However, if you want to include an image without a caption, or you wish
to provide different information in the alt text to the caption, this can be
done via the `fig.alt` code chunk option.  As an example, the code chunk below
was used to include the first image shown in this section, so that its intention
could be conveyed to someone using a screen reader.

    ```{r no-cap, fig.alt="A default sized example figure without a caption."}`r ''`
    plot(cars)
    ```
    
You may also want to consider the color palette used in your figures, to ensure
they are accessible to color impaired readers.  _BiocStyle_ doesn't provide a
specific color palette, but many options are available in packages from CRAN.
There have also been [significant
efforts](https://developer.r-project.org/Blog/public/2019/11/21/a-new-palette-for-r/)
made to improve the default colors provided by `palette()` in R-4.0.0.
Bioconductor contains some domain specific packages that focus on color blind
friendly visualizations e.g. `r Biocpkg("dittoSeq")` for single-cell and bulk
RNA-sequencing data.

# 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.

```markdown
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).

```{r 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.,

```latex
\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()`:

```{r sessionInfo, echo=FALSE}
sessionInfo()
```
