1 Add liftr Metadata

To dockerize your R Markdown document, the first step is adding liftr options in the YAML front-matter of a document. For example:

---
title: "The Missing Example of liftr"
author: "Author Name"
date: "2016-08-05"
output:
html_document:
liftr:
maintainer: "Author Name"
maintainer_email: "name@example.com"
from: "rocker/r-base:latest"
latex: false
pandoc: true
syslib:
- gfortran
- samtools
cranpkg:
- randomForest
biocpkg:
- Gviz
- ggbio
ghpkg:
rabix: true
rabix_json: "https://s3.amazonaws.com/rabix/rabix-test/bwa-mem.json"
rabix_d: "~/liftr_rabix/bwa/"
rabix_args:
- reference: "https://s3.amazonaws.com/rabix/rabix-test/chr20.fa"
---

All available options are expained below.

1.1 Required options

• maintainer - Maintainer name for the Dockerfile.
• maintainer_email - Maintainer email address for the Dockerfile.

1.2 Optional options

• from - Base image for building the docker image. Default is "rocker/r-base:latest".
• latex - Is TeX environment needed when rendering the document? Default is false.
• pandoc - Should we install pandoc in the container? Default is true. If pandoc was already installed in the base image, this should be set to false to avoid potential errors. For example, for rocker/rstudio and bioconductor/... images, this option will be automatically set to false since they already have pandoc installed.
• syslib - Debian/Ubuntu system software packages depended in the document. Please also include software packages depended by the R packages included below, such as gfortran here required for compiling randomForest.
• cranpkg - CRAN packages depended in the document. If only pkgname is provided, liftr will install the latest version of the package on CRAN. To improve reproducibility, we recommend to use the package name with a specified version number: pkgname/pkgversion (e.g. ggplot2/1.0.0), even if the version is the current latest version. Note: pkgversion must be provided to install the archived versions of packages.
• biocpkg - Bioconductor packages depended in the document.
• ghpkg - GitHub R packages depended in the document. We accept the same format as the repo argument in devtools::install_github. Normally, "username/repo" would be sufficient.

1.3 Rabix options

The Rabix options are optional. Just make sure rabix: true when you need to enable Rabix support.

• rabix - Logical. Should Rabix support be enabled for this document?
• rabix_json - The URI (local file path or HTTP/HTTPS URL) to a JSON document that describes the Rabix app.
• rabix_d - Working directory for the task. Required when rabix: true. We recommend to set this as the same directory (or a subdirectory) as the directory of the input R Markdown document, for better reproducibility and easier access of the output.
• rabix_args - Additional arguments for Rabix and the Rabix app, usually the inputs and parameters. Run rabix -h or read this page for more details.

2 Use lift() and drender()

After adding proper liftr metadata to the document YAML data block, we can use lift() to parse the document and generate a Dockerfile (it will also generate a Rabixfile if necessary).

We will use docker.Rmd included in the package as an example. First, we create a new directory and copy the example document to the directory:

dir_docker = "~/liftr_docker/"
dir.create(dir_docker)
file.copy(system.file("docker.Rmd", package = "liftr"), dir_docker)

Then, we use lift() to parse the document and generate Dockerfile:

library("liftr")
docker_input = paste0(dir_docker, "docker.Rmd")
lift(docker_input)

After successfully running lift() on docker.Rmd, the Dockerfile will be in the ~/liftr_docker/ directory.

Now we can use drender() on docker.Rmd to render the document to a html file, under a Docker container:

drender(docker_input)

The drender() function will parse the Dockerfile, build a new Docker image, and run a container to render the input document. If successfully rendered, the output docker.html will be in the ~/liftr_docker/ directory. You can also passed additional arguments in rmarkdown::render to this function.

In order to share the dockerized R Markdown document, simply share the .Rmd file. Other users can use the lift() and drender() functions to render the document as above.

3 Rabix Support

Rabix is an open source implementation of the Common Workflow Language specification for building portable bioinformatics pipelines. Users can write JSON-based tools/workflows and run them with Rabix.

We will use rabix.Rmd included in the package as an example. As before, we create a new directory and copy the example document to the directory:

dir_rabix  = "~/liftr_rabix/"
dir.create(dir_rabix)
file.copy(system.file("rabix.Rmd", package = "liftr"), dir_rabix)

Use lift() and drender() as before:

library("liftr")
rabix_input = paste0(dir_rabix, "rabix.Rmd")
lift(rabix_input)
drender(rabix_input)

Rabix tools/workflows will run first, the document will be rendered after. In this way, we can use the output of the bioinformatics pipelines for further analysis in our R Markdown document. See rabix.Rmd for details.

If successfully rendered, the output rabix.html will be in the ~/liftr_rabix/ directory.

4 System Requirements

As the host platform, Linux is currently preferred over the other platforms due to certain limitations of running Docker and performance issues.

4.1 Docker

We need Docker installed to render the documents.

To install Docker in Ubuntu:

sudo apt-get install docker.io

We should configure Docker to run without sudo. To avoid sudo when using the docker command, simply create a group named docker and add yourself to it:

sudo usermod -aG docker your-username

Here is a detailed guide for installing Docker on most platforms. Anyhow, just make sure you can run docker under shell.

4.2 Rabix

Rabix needs to be installed if you want to run Rabix tools/workflows before rendering the documents. Make sure you can run rabix under shell after installation.

To install Rabix in Ubuntu:

sudo apt-get install python-dev python-pip docker.io phantomjs libyaml-dev
sudo pip install rabix

Here is a more detailed guide for installing Rabix on other platforms.

Project website: liftr.me