A Quick Introduction to liftr
Nan Xiao <https://nanx.me>Source:
In essence, liftr aims to solve the problem of persistent reproducible reporting. To achieve this goal, it extends the R Markdown metadata format, and uses Docker to containerize and render R Markdown documents.
To containerize your R Markdown document, the first step is adding
liftr fields to the YAML metadata section of the document. For example:
--- title: "The Missing Example of liftr" author: "Author Name" date: "2021-12-19" output: rmarkdown::html_document liftr: maintainer: "Maintainer Name" email: "firstname.lastname@example.org" from: "rocker/r-base:latest" pandoc: true texlive: false sysdeps: - gfortran cran: - glmnet bioc: - Gviz/3.9 remotes: - "nanxstats/liftr" include: "DockerfileSnippet" ---
All available metadata fields are expained below.
Maintainer’s name for the Dockerfile.
Maintainer’s email address for the Dockerfile.
Should we install pandoc in the container? Default is
If pandoc was already installed in the base image, this should be set to
falseto avoid potential errors. For example, for
bioconductor/...images, this option will be automatically set to
falsesince they already have pandoc installed.
Is TeX environment needed when rendering the document? Default is
false. Should be
trueparticularly when the output format is PDF.
Debian/Ubuntu system software packages depended in the document.
Please also include software packages depended by the R packages below. For example, here
gfortranis required for compiling
CRAN packages depended in the document.
liftrwill install the latest version of the package on CRAN. To improve reproducibility, we recommend to use the package name with a specified version number:
ggplot2/1.0.0), even if the version is the current latest version. Note:
pkgversionmust be provided to install the archived versions of packages.
Bioconductor packages depended in the document. If used, the first package’s name must be followed by the desired Bioconductor version (e.g.
Gviz/3.9). All the packages used must be installed from the same Bioconductor version.
Remote R packages that are not available from CRAN or Bioconductor.
The remote package naming specification from devtools is adopted here. Packages can be installed from GitHub, Bitbucket, Git/SVN servers, URLs, etc.
The path to a text file that contains custom Dockerfile snippet. The snippet will be included in the generated Dockerfile. This can be used to install additional software packages or further configure the system environment.
Note that this file should be in the same directory as the input R Markdown file.
After adding proper
liftr metadata to the document YAML data block, we can use
lift() to parse the document and generate a Dockerfile.
We will use a minimal example included in the liftr package. First, we create a new directory and copy the R Markdown document into the directory:
path = "~/liftr-minimal/" dir.create(path) file.copy(system.file("examples/liftr-minimal.Rmd", package = "liftr"), path)
Then, we use
lift() to parse the document and generate the Dockerfile:
After successfully running
lift(), the Dockerfile will be in the
Now we can use
render_docker() to render the document into an HTML file, under a Docker container:
render_docker() will parse the Dockerfile, build a new Docker image, and run a Docker container to render the input document. If successfully rendered, the output
liftr-minimal.html will be in the
~/liftr-minimal/ directory. You can also pass additional arguments in
rmarkdown::render to this function.
Normally, the argument
prune is set to
render_docker(). This means any dangling containers or images due to unsuccessful builds will be automatically cleaned.
The above input YAML file contains the basic information of the Docker container, image, and commands to render the document. It is generated by setting
purge_info = TRUE (default) in
Docker is an essential system requirement when using liftr to render the R Markdown documents.
install_docker() will help you find the proper guide to install and set up Docker in your system. To check if Docker is correctly installed, use
check_docker_install(); to check if the Docker daemon is running, use
check_docker_running(). In particular, Linux users should configure Docker to run without sudo.