<!-- Generated by pkgdown: do not edit by hand -->
<!DOCTYPE html>
<html lang="en">
  <head>
  <meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1.0">

<title>Statement of Need • containerit</title>

<!-- jquery -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/jquery/3.3.1/jquery.min.js" integrity="sha256-FgpCb/KJQlLNfOu91ta32o/NMZxltwRo8QtmkMRdAu8=" crossorigin="anonymous"></script>
<!-- Bootstrap -->

<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.7/css/bootstrap.min.css" integrity="sha256-916EbMg70RQy9LHiGkXzG8hSg9EdNy97GazNG/aiY1w=" crossorigin="anonymous" />
<script src="https://cdnjs.cloudflare.com/ajax/libs/twitter-bootstrap/3.3.7/js/bootstrap.min.js" integrity="sha256-U5ZEeKfGNOja007MMD3YBI0A3OSZOQbeG6z2f2Y0hu8=" crossorigin="anonymous"></script>

<!-- Font Awesome icons -->
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/4.7.0/css/font-awesome.min.css" integrity="sha256-eZrrJcwDc/3uDhsdt61sL2oOBY362qM3lon1gyExkL0=" crossorigin="anonymous" />

<!-- clipboard.js -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/clipboard.js/2.0.4/clipboard.min.js" integrity="sha256-FiZwavyI2V6+EXO1U+xzLG3IKldpiTFf3153ea9zikQ=" crossorigin="anonymous"></script>

<!-- sticky kit -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/sticky-kit/1.1.3/sticky-kit.min.js" integrity="sha256-c4Rlo1ZozqTPE2RLuvbusY3+SU1pQaJC0TjuhygMipw=" crossorigin="anonymous"></script>

<!-- pkgdown -->
<link href="pkgdown.css" rel="stylesheet">
<script src="pkgdown.js"></script>



<meta property="og:title" content="Statement of Need" />

<meta property="og:image" content="/logo.png" />
<meta name="twitter:card" content="summary" />



<!-- mathjax -->
<script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/MathJax.js" integrity="sha256-nvJJv9wWKEm88qvoQl9ekL2J+k/RWIsaSScxxlsrv8k=" crossorigin="anonymous"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.5/config/TeX-AMS-MML_HTMLorMML.js" integrity="sha256-84DKXVJXs0/F8OTMzX4UR909+jtl4G7SPypPavF+GfA=" crossorigin="anonymous"></script>

<!--[if lt IE 9]>
<script src="https://oss.maxcdn.com/html5shiv/3.7.3/html5shiv.min.js"></script>
<script src="https://oss.maxcdn.com/respond/1.4.2/respond.min.js"></script>
<![endif]-->


  </head>

  <body>
    <div class="container template-title-body">
      <header>
      <div class="navbar navbar-default navbar-fixed-top" role="navigation">
  <div class="container">
    <div class="navbar-header">
      <button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#navbar" aria-expanded="false">
        <span class="sr-only">Toggle navigation</span>
        <span class="icon-bar"></span>
        <span class="icon-bar"></span>
        <span class="icon-bar"></span>
      </button>
      <span class="navbar-brand">
        <a class="navbar-link" href="index.html">containerit</a>
        <span class="version label label-default" data-toggle="tooltip" data-placement="bottom" title="Released version">0.6.0</span>
      </span>
    </div>

    <div id="navbar" class="navbar-collapse collapse">
      <ul class="nav navbar-nav">
        <li>
  <a href="index.html">
    <span class="fa fa-home fa-lg"></span>
     
  </a>
</li>
<li>
  <a href="articles/containerit.html">Get started</a>
</li>
<li>
  <a href="reference/index.html">Reference</a>
</li>
<li class="dropdown">
  <a href="#" class="dropdown-toggle" data-toggle="dropdown" role="button" aria-expanded="false">
    Articles
     
    <span class="caret"></span>
  </a>
  <ul class="dropdown-menu" role="menu">
    <li>
      <a href="articles/basic.html">Basic introduction to package containerit</a>
    </li>
    <li>
      <a href="articles/bioconductor.html">Using Bioconductor with containerit</a>
    </li>
    <li>
      <a href="articles/container.html">Using the containerit Docker image</a>
    </li>
  </ul>
</li>
<li>
  <a href="news/index.html">Changelog</a>
</li>
      </ul>
      
      <ul class="nav navbar-nav navbar-right">
        <li>
  <a href="https://github.com/o2r-project/containerit">
    <span class="fa fa-github fa-lg"></span>
     
  </a>
</li>
      </ul>
      
    </div><!--/.nav-collapse -->
  </div><!--/.container -->
</div><!--/.navbar -->

      
      </header>

<div class="row">
  <div class="contents col-md-9">
    <div class="page-header">
      <h1>Statement of Need</h1>
    </div>


<hr>
<p>title: ‘containerit: Generating Dockerfiles for reproducible research with R’ tags:</p>
<ul>
<li>containerisation</li>
<li>Docker</li>
<li>sandbox</li>
<li>reproducibility</li>
<li>reproducible research authors:</li>
<li>name: Daniel Nüst orcid: 0000-0002-0024-5046 affiliation: 1</li>
<li>name: Matthias Hinz orcid: 0000-0001-6837-9406 affiliation: 2 affiliations:</li>
<li>name: Institute for Geoinformatics, University of Münster, Germany index: 1</li>
<li>name: Professorship for Geoinformatics and Geodesy, Faculty of Agricultural and Environmental Sciences, University of Rostock, Germany index: 2 date: 22 July 2019 bibliography: paper.bib —</li>
</ul>
<div id="statement-of-need" class="section level1">

<p><a href="https://en.wikipedia.org/wiki/Operating-system-level_virtualization">Linux containers</a> have become a promising tool to increase transparency, portability, and reproducibility of research in several domains and use cases: data science [@boettiger_introduction_2015], software engineering research [@cito_using_2016], multi-step bioinformatics pipelines [@kim_bio-docklets_2017], standardised environments for exchangeable software [@belmann_bioboxes_2015], computational archaeology [@marwick_computational_2017], packaging algorithms [@hosny_algorun_2016], or geographic object-based image analysis [@knoth_reproducibility_2017]. Running an analysis in a container increases reliability of a workflow, as it can execute packaged code independently of the author’s computer and its available configurations and dependencies. However, capturing a computational environment in containers can be complex, making container use difficult for domain scientists with limited programming experience. <code>containerit</code> opens up the advantages of containerisation to a much larger user base by assisting researchers, who are unfamiliar with Linux, command lines or containerisation, in packaging workflows based on R [@r_2018] in container images by using only user-friendly R commands.</p>
<p>Recently containerisation took off as a technology for packaging applications and their dependencies for fast, scalable, and secure <a href="https://en.wikipedia.org/wiki/Sandbox_%28computer_security%29">sandboxed</a> deployments in cloud-based infrastructures [cf. @osnat_brief_2018]. The most widely used containerisation software is <a href="https://en.wikipedia.org/wiki/Docker_%28software%29">Docker</a> with the following core building blocks (cf. <a href="https://docs.docker.com/get-started/">Docker: Get Started</a>): The <em>image</em> is built from the instructions in a recipe called <code>Dockerfile</code>. The image is executed as a <em>container</em> using a <em>container runtime</em>. An image can be moved between systems as a file (image tarball) or based on an <em>image registry</em>. A <code>Dockerfile</code> may use the image created by another <code>Dockerfile</code> as the starting point, a so-called <em>base image</em>. While containers can be manually altered, the common practice is to conduct all configurations with the scripts and instructions originating in the <code>Dockerfile</code>.</p>
<p>An important advantage of containers over <a href="https://en.wikipedia.org/wiki/Virtual_machine">virtual machines</a> is that their duality between recipe and image provides and additional layer of transparency and safeguarding. The <code>Dockerfile</code> and image can be published alongside a scientific paper to support peer review and, to some extent, preserve the original results [@nust_opening_2017]. Even if an image cannot be executed or a <code>Dockerfile</code> can no longer be built, the instructions in the <code>Dockerfile</code> are human-readable, and files in the image can be extracted to recreate an environment that closely resembles the original. Further useful features are (a) portability, thanks to a single runtime dependency, which allows readers to explore an author’s virtual laboratory, including complex dependencies or custom-made code, either on their machines or in cloud-based infrastructures [e.g., by using Binder, see @jupyter_binder_2018], and (b) transparency, because an image’s filesystem can be easily inspected. This way, containers can enable verification of reproducibility and auditing without requiring reviewers to manually download, install, and re-run analyses [@beaulieu-jones_reproducibility_2017].</p>
<p>Container preservation is an active field of research [@rechert_preserving_2017; @emsley_framework_2018]. It is reasonable to assume that key stakeholders interested in workflow preservation, such as universities or scientific publishers, should be able to operate container runtimes on a time scale comparable to data storage requirements by funding agencies, e.g., 10 years in case of the <a href="http://www.dfg.de/en/research_funding/proposal_review_decision/applicants/research_data/index.html">German DFG</a> or <a href="https://epsrc.ukri.org/about/standards/researchdata/expectations/">British EPSRC</a>. To enable and leverage the stakeholders’ infrastructure, container creation must become easier and more widespread.</p>
</div>
<div id="summary" class="section level1">
<h1 class="hasAnchor">
<a href="#summary" class="anchor"></a>Summary</h1>
<p>The package <code>containerit</code> automates the generation of <code>Dockerfile</code>s for workflows in R, based on images by the <a href="https://www.rocker-project.org/">Rocker project</a> [@RJ-2017-065]. The core feature of <code>containerit</code> is that it transforms the local session information into a set of instructions which can be serialised as a <code>Dockerfile</code>, as shown in the code snippet below:</p>
<div class="sourceCode" id="cb1"><pre class="sourceCode r"><code class="sourceCode r"><a class="sourceLine" id="cb1-1" data-line-number="1"><span class="op">&gt;</span><span class="st"> </span><span class="kw"><a href="https://www.rdocumentation.org/packages/base/topics/message">suppressPackageStartupMessages</a></span>(<span class="kw"><a href="https://www.rdocumentation.org/packages/base/topics/library">library</a></span>(<span class="st">"containerit"</span>))</a>
<a class="sourceLine" id="cb1-2" data-line-number="2"><span class="op">&gt;</span><span class="st"> </span>my_dockerfile &lt;-<span class="st"> </span>containerit<span class="op">::</span><span class="kw"><a href="https://www.rdocumentation.org/packages/containerit/topics/dockerfile">dockerfile</a></span>(<span class="dt">from =</span> utils<span class="op">::</span><span class="kw"><a href="https://www.rdocumentation.org/packages/utils/topics/sessionInfo">sessionInfo</a></span>())</a>
<a class="sourceLine" id="cb1-3" data-line-number="3"><span class="op">&gt;</span><span class="st"> </span><span class="kw"><a href="https://www.rdocumentation.org/packages/base/topics/print">print</a></span>(my_dockerfile)</a>
<a class="sourceLine" id="cb1-4" data-line-number="4">FROM rocker<span class="op">/</span>r<span class="op">-</span>ver<span class="op">:</span><span class="dv">3</span>.<span class="fl">5.2</span></a>
<a class="sourceLine" id="cb1-5" data-line-number="5">LABEL maintainer=<span class="st">"daniel"</span></a>
<a class="sourceLine" id="cb1-6" data-line-number="6">RUN export DEBIAN_FRONTEND=noninteractive; apt<span class="op">-</span>get <span class="op">-</span>y update \</a>
<a class="sourceLine" id="cb1-7" data-line-number="7">  <span class="op">&amp;&amp;</span><span class="st"> </span>apt<span class="op">-</span>get install <span class="op">-</span>y git<span class="op">-</span>core \</a>
<a class="sourceLine" id="cb1-8" data-line-number="8">    libcurl4<span class="op">-</span>openssl<span class="op">-</span>dev \</a>
<a class="sourceLine" id="cb1-9" data-line-number="9">    libssl<span class="op">-</span>dev \</a>
<a class="sourceLine" id="cb1-10" data-line-number="10">    pandoc \</a>
<a class="sourceLine" id="cb1-11" data-line-number="11">    pandoc<span class="op">-</span>citeproc</a>
<a class="sourceLine" id="cb1-12" data-line-number="12">RUN [<span class="st">"install2.r"</span>, <span class="st">"curl"</span>, <span class="st">"digest"</span>, <span class="st">"evaluate"</span>, <span class="st">"formatR"</span>, \</a>
<a class="sourceLine" id="cb1-13" data-line-number="13">  <span class="st">"futile.logger"</span>, <span class="st">"futile.options"</span>, <span class="st">"htmltools"</span>, <span class="st">"jsonlite"</span>, \</a>
<a class="sourceLine" id="cb1-14" data-line-number="14">  <span class="st">"knitr"</span>, <span class="st">"lambda.r"</span>, <span class="st">"magrittr"</span>, <span class="st">"Rcpp"</span>, <span class="st">"rjson"</span>, \</a>
<a class="sourceLine" id="cb1-15" data-line-number="15">  <span class="st">"rmarkdown"</span>, <span class="st">"rsconnect"</span>, <span class="st">"semver"</span>, <span class="st">"stevedore"</span>, <span class="st">"stringi"</span>, \</a>
<a class="sourceLine" id="cb1-16" data-line-number="16">  <span class="st">"stringr"</span>, <span class="st">"xfun"</span>, <span class="st">"yaml"</span>]</a>
<a class="sourceLine" id="cb1-17" data-line-number="17">WORKDIR <span class="op">/</span>payload<span class="op">/</span></a>
<a class="sourceLine" id="cb1-18" data-line-number="18">CMD [<span class="st">"R"</span>]</a></code></pre></div>
<p>The created <code>Dockerfile</code> has installation instructions for the loaded packages and their system dependencies. It uses the <code>r-ver</code> stack of Rocker images, matching the R version to the environment encountered locally by <code>containerit</code>. These images use <a href="https://mran.microsoft.com/">MRAN</a> snapshots to control installed R package versions in a reproducible way. The system dependencies required by these packages are identified using the <code>sysreqs</code> package [@csardi_sysreqs_2019] and the corresponding <a href="http://sysreqs.r-hub.io/">database and API</a>.</p>
<p><code><a href="reference/dockerfile.html">dockerfile(..)</a></code> is the package’s main user function and accepts session information objects, session information saved in a file, a set of R commands, an R script file, a <a href="https://cran.r-project.org/doc/manuals/r-release/R-exts.html#The-DESCRIPTION-file"><code>DESCRIPTION</code></a> file, or an R Markdown document [@allaire_rmarkdown_2018]. <a href="https://en.wikipedia.org/wiki/Static_program_analysis">Static program analysis</a> using the package <code>automagic</code> [@brokamp_automagic_2017] is used to increase the chances that the capturing environment has all required packages available, such as when creating Dockerfiles for R Markdown documents as a service [@nust_reproducibility_2018]. To capture the workflow environment, <code>containerit</code> executes the whole workflow in a new R session using the package <code>callr</code> [@csardi_callr_2018], because static program analysis can be broken by using helper functions, such as <code><a href="https://www.rdocumentation.org/packages/xfun/topics/pkg_attach">xfun::pkg_attach()</a></code> [@xie_xfun_2018], by unintended side effects, or by seemingly clever or user-friendly yet customised ways of loeading packages (cf. first lines in R script file <code>tgis_a_1579333_sm7524.r</code> in <a href="https://doi.org/10.6084/m9.figshare.7757069.v1">https://doi.org/10.6084/m9.figshare.7757069.v1</a>). Further parameters for the function comprise, for example, image metadata, base image, versioned installations, and filtering of R packages already installed in the base image.</p>
<p>The package <code>containerit</code>‘s main contribution is that it allows for automated capturing of runtime environments as <code>Dockerfile</code>s based on literate programming workflows [@gentleman_statistical_2007] to support reproducible research. Together with <code>stevedore</code> [@fitzjohn_stevedore_2019], <code>containerit</code> enables a completely R-based creation and manipulation of Docker containers. Using <code>containerit</code> only minimally affects researchers’ workflows because it can be applied after completing a workflow, while at the same time the captured snapshots can enhance the scholarly publication process (in particular review, interaction, and preservation) and may form a basis for more reusable and transparent publications. In the future, <code>containerit</code> may support alternative container software such as Singularity [@kurtzer_singularity_2017], enable parametrisation of container executions and pipelines as demonstrated by Kliko [@molenaar_klikoscientific_2018], or support proper accreditation of software [@codemeta; @katz_software_2018].</p>
<p><strong>Related Work</strong></p>
<p><a href="https://github.com/rstudio/renv/"><code>renv</code></a> is an R package for managing reproducible environments for R providing isolation, portability, and pinned versions of R packages, but it does not handle system dependencies. <a href="https://expfactory.github.io/">The Experiment Factory</a> similarly focuses on ease of use for creating <code>Dockerfile</code>s for behavioural experiments, yet it uses a CLI-based interaction and generates extra shell scripts to be included in the images. <a href="https://www.reprozip.org/">ReproZip</a> [@ChirigatiRSF16] packages files identified by <a href="https://en.wikipedia.org/wiki/Tracing_(software)">tracing</a> in a self-contained bundle, which can be unpacked to a Docker container/<code>Dockerfile</code>. In the R domain, the package <code>dockerfiler</code> [@fay_dockerfiler_2018] provides an object-oriented API for manual Dockerfile creation, and <code>liftr</code> [@xiao_liftr_2018] creates a <code>Dockerfile</code> based on fields added to the metadata header of an R Markdown document. <code>automagic</code> [@brokamp_automagic_2017], <a href="https://github.com/Gueils/whales">Whales</a>, <a href="https://github.com/stencila/dockter/"><code>dockter</code></a>, and <a href="https://github.com/jupyter/repo2docker"><code>repo2docker</code></a> use static program analysis to create environment descriptions from common project configuration files for multiple programming languages. Namely, <code>automagic</code> analyses R code and can store dependencies in a bespoke <a href="https://en.wikipedia.org/wiki/YAML">YAML</a> format. Whales and <code>dockter</code> provide different formats, including <code>Dockerfile</code>. Finally, <code>repo2docker</code> primarily creates containers for interactive notebooks to run as a Binder [@jupyter_binder_2018] but does not actively expose a <code>Dockerfile</code>. None of them apply the strict code execution approach as <code>containerit</code> does.</p>
</div>
<div id="acknowledgements" class="section level1">
<h1 class="hasAnchor">
<a href="#acknowledgements" class="anchor"></a>Acknowledgements</h1>
<p>This work is supported by the project <a href="https://o2r.info">Opening Reproducible Research</a> (<a href="https://www.uni-muenster.de/forschungaz/project/9520">Offene Reproduzierbare Forschung</a>) funded by the German Research Foundation (<a href="http://dfg.de/">DFG</a>) under project numbers <code>PE 1632/10-1</code> and <code>1632/17-1</code>.</p>
</div>
<div id="references" class="section level1">
<h1 class="hasAnchor">
<a href="#references" class="anchor"></a>References</h1>
</div>


  </div>

</div>


      <footer>
      <div class="copyright">
  <p>Developed by Daniel Nuest, Matthias Hinz.</p>
</div>

<div class="pkgdown">
  <p>Site built with <a href="https://pkgdown.r-lib.org/">pkgdown</a> 1.3.0.</p>
</div>
      </footer>
   </div>

  

  </body>
</html>

