hungerzs
/
liftr


			
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264
							<!DOCTYPE html>
<!-- Generated by pkgdown: do not edit by hand --><html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<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>A Quick Introduction to liftr • liftr</title>
<!-- jquery --><script src="https://code.jquery.com/jquery-3.1.0.min.js" integrity="sha384-nrOSfDHtoPMzJHjVTdCopGqIqeYETSXhZDFyniQ8ZHcVy08QesyHcnOUpMpqnmWq" crossorigin="anonymous"></script><!-- Bootstrap --><link href="https://maxcdn.bootstrapcdn.com/bootswatch/3.3.7/flatly/bootstrap.min.css" rel="stylesheet" crossorigin="anonymous">
<script src="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/js/bootstrap.min.js" integrity="sha384-Tc5IQib027qvyjSMfHjOMaLkfuWVxZxUPnCJA7l2mCWNIpG9mGCD8wGNIcPD7Txa" crossorigin="anonymous"></script><!-- Font Awesome icons --><link href="https://maxcdn.bootstrapcdn.com/font-awesome/4.6.3/css/font-awesome.min.css" rel="stylesheet" integrity="sha384-T8Gy5hrqNKT+hzMclPo118YTQO6cYprQmhrYwIiQ/3axmI1hQomh7Ud2hPOy8SP1" crossorigin="anonymous">
<!-- pkgdown --><link href="../pkgdown.css" rel="stylesheet">
<script src="../jquery.sticky-kit.min.js"></script><script src="../pkgdown.js"></script><!-- mathjax --><script src="https://mathjax.rstudio.com/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></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]--><!-- Google analytics --><script>
  (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
  (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
  m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
  })(window,document,'script','https://www.google-analytics.com/analytics.js','ga');

  ga('create', 'UA-65001771-1', 'auto');
  ga('send', 'pageview');

</script>
</head>
<body>
    <div class="container template-vignette">
      <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">
        <span class="icon-bar"></span>
        <span class="icon-bar"></span>
        <span class="icon-bar"></span>
      </button>
      <a class="navbar-brand" href="../index.html">liftr</a>
    </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="../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/liftr-addins.html">RStudio Addins for liftr</a>
    </li>
    <li>
      <a href="../articles/liftr-intro.html">A Quick Introduction to liftr</a>
    </li>
    <li>
      <a href="../articles/liftr-tidyverse.html">Explore tidyverse with liftr</a>
    </li>
  </ul>
</li>
<li>
  <a href="../news/index.html">News</a>
</li>
      </ul>
<ul class="nav navbar-nav navbar-right">
<li>
  <a href="https://github.com/road2stat/liftr">
    <span class="fa fa-github fa-lg"></span>
     
  </a>
</li>
      </ul>
</div>
<!--/.nav-collapse -->
  </div>
<!--/.container -->
</div>
<!--/.navbar -->

      
      </header><div class="row">
  <div class="col-md-9">
    <div class="page-header toc-ignore">
      <h1>A Quick Introduction to liftr</h1>
                        <h4 class="author">Nan Xiao &lt;<a href="https://nanx.me" class="uri">https://nanx.me</a>&gt;</h4>
            
            <h4 class="date">2017-12-13</h4>
          </div>

    
<div class="contents">
<div id="introduction" class="section level1">
<h1 class="hasAnchor">
<a href="#introduction" class="anchor"></a>Introduction</h1>
<p>In essence, liftr aims to solve the problem of <em>persistent reproducible reporting</em>. To achieve this goal, it extends the <a href="http://rmarkdown.rstudio.com">R Markdown</a> metadata format, and uses Docker to containerize and render R Markdown documents.</p>
</div>
<div id="metadata-for-containerization" class="section level1">
<h1 class="hasAnchor">
<a href="#metadata-for-containerization" class="anchor"></a>Metadata for containerization</h1>
<p>To containerize your R Markdown document, the first step is adding <code>liftr</code> fields to the YAML metadata section of the document. For example:</p>
<div class="sourceCode"><pre class="sourceCode yaml"><code class="sourceCode yaml"><span class="ot">---</span>
<span class="fu">title:</span><span class="at"> </span><span class="st">"The Missing Example of liftr"</span>
<span class="fu">author:</span><span class="at"> </span><span class="st">"Author Name"</span>
<span class="fu">date:</span><span class="at"> </span><span class="st">"2017-12-13"</span>
<span class="fu">output:</span><span class="at"> rmarkdown::html_document</span>
<span class="fu">liftr:</span>
  <span class="fu">maintainer:</span><span class="at"> </span><span class="st">"Maintainer Name"</span>
  <span class="fu">email:</span><span class="at"> </span><span class="st">"[email protected]"</span>
  <span class="fu">from:</span><span class="at"> </span><span class="st">"rocker/r-base:latest"</span>
  <span class="fu">pandoc:</span><span class="at"> true</span>
  <span class="fu">texlive:</span><span class="at"> false</span>
  <span class="fu">sysdeps:</span>
    <span class="kw">-</span> gfortran
  <span class="fu">cran:</span>
    <span class="kw">-</span> glmnet
  <span class="fu">bioc:</span>
    <span class="kw">-</span> Gviz
  <span class="fu">remotes:</span>
    <span class="kw">-</span> <span class="st">"road2stat/liftr"</span>
  <span class="fu">include:</span><span class="at"> </span><span class="st">"DockerfileSnippet"</span>
<span class="ot">---</span></code></pre></div>
<p>All available metadata fields are expained below.</p>
<div id="required-metadata" class="section level2">
<h2 class="hasAnchor">
<a href="#required-metadata" class="anchor"></a>Required metadata</h2>
<ul>
<li>
<p><code>maintainer</code></p>
<p>Maintainer’s name for the Dockerfile.</p>
</li>
<li>
<p><code>email</code></p>
<p>Maintainer’s email address for the Dockerfile.</p>
</li>
</ul>
</div>
<div id="optional-metadata" class="section level2">
<h2 class="hasAnchor">
<a href="#optional-metadata" class="anchor"></a>Optional metadata</h2>
<ul>
<li>
<p><code>from</code></p>
<p>Base image for building the docker image. Default is <code>"rocker/r-base:latest"</code>. For R users, the images offered by the <a href="https://github.com/rocker-org">rocker project</a> and <a href="https://bioconductor.org/help/docker/">Bioconductor</a> can be considered first.</p>
</li>
<li>
<p><code>pandoc</code></p>
<p>Should we install pandoc in the container? Default is <code>true</code>.</p>
<p>If pandoc was already installed in the base image, this should be set to <code>false</code> to avoid potential errors. For example, for <a href="https://registry.hub.docker.com/u/rocker/rstudio/"><code>rocker/rstudio</code> images</a> and <a href="https://www.bioconductor.org/help/docker/"><code>bioconductor/...</code> images</a>, this option will be automatically set to <code>false</code> since they already have pandoc installed.</p>
</li>
<li>
<p><code>texlive</code></p>
<p>Is TeX environment needed when rendering the document? Default is <code>false</code>. Should be <code>true</code> particularly when the output format is PDF.</p>
</li>
<li>
<p><code>sysdeps</code></p>
<p>Debian/Ubuntu system software packages depended in the document.</p>
<p>Please also include software packages depended by the R packages below. For example, here <code>gfortran</code> is required for compiling <code>glmnet</code>.</p>
</li>
<li>
<p><code>cran</code></p>
<p>CRAN packages depended in the document.</p>
<p>If only <code>pkgname</code> is provided, <code>liftr</code> will install the <em>latest</em> version of the package on CRAN. To improve reproducibility, we recommend to use the package name with a specified version number: <code>pkgname/pkgversion</code> (e.g. <code>ggplot2/1.0.0</code>), even if the version is the current latest version. Note: <code>pkgversion</code> must be provided to install the archived versions of packages.</p>
</li>
<li>
<p><code>bioc</code></p>
<p>Bioconductor packages depended in the document.</p>
</li>
<li>
<p><code>remotes</code></p>
<p>Remote R packages that are not available from CRAN or Bioconductor.</p>
<p>The <a href="https://github.com/hadley/devtools/blob/master/vignettes/dependencies.Rmd">remote package naming specification</a> from devtools is adopted here. Packages can be installed from GitHub, Bitbucket, Git/SVN servers, URLs, etc.</p>
</li>
<li>
<p><code>include</code></p>
<p>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.</p>
<p>Note that this file should be in the same directory as the input R Markdown file.</p>
</li>
</ul>
</div>
</div>
<div id="containerize-the-document" class="section level1">
<h1 class="hasAnchor">
<a href="#containerize-the-document" class="anchor"></a>Containerize the document</h1>
<p>After adding proper <code>liftr</code> metadata to the document YAML data block, we can use <code><a href="../reference/lift.html">lift()</a></code> to parse the document and generate a Dockerfile.</p>
<p>We will use <a href="https://github.com/road2stat/liftr/blob/master/inst/examples/liftr-minimal.Rmd">a minimal example</a> included in the liftr package. First, we create a new directory and copy the R Markdown document into the directory:</p>
<div class="sourceCode"><pre class="sourceCode r"><code class="sourceCode r">path =<span class="st"> "~/liftr-minimal/"</span>
<span class="kw">dir.create</span>(path)
<span class="kw">file.copy</span>(<span class="kw">system.file</span>(<span class="st">"examples/liftr-minimal.Rmd"</span>, <span class="dt">package =</span> <span class="st">"liftr"</span>), path)</code></pre></div>
<p>Then, we use <code><a href="../reference/lift.html">lift()</a></code> to parse the document and generate the Dockerfile:</p>
<div class="sourceCode"><pre class="sourceCode r"><code class="sourceCode r"><span class="kw">library</span>(<span class="st">"liftr"</span>)

input =<span class="st"> </span><span class="kw">paste0</span>(path, <span class="st">"liftr-minimal.Rmd"</span>)
<span class="kw"><a href="../reference/lift.html">lift</a></span>(input)</code></pre></div>
<p>After successfully running <code><a href="../reference/lift.html">lift()</a></code>, the Dockerfile will be in the <code>~/liftr-minimal/</code> directory.</p>
</div>
<div id="render-the-document" class="section level1">
<h1 class="hasAnchor">
<a href="#render-the-document" class="anchor"></a>Render the document</h1>
<p>Now we can use <code><a href="../reference/render_docker.html">render_docker()</a></code> to render the document into an HTML file, under a Docker container:</p>
<div class="sourceCode"><pre class="sourceCode r"><code class="sourceCode r"><span class="kw"><a href="../reference/render_docker.html">render_docker</a></span>(input)</code></pre></div>
<p>The function <code><a href="../reference/render_docker.html">render_docker()</a></code> will parse the Dockerfile, build a new Docker image, and run a Docker container to render the input document. If successfully rendered, the output <code>liftr-minimal.html</code> will be in the <code>~/liftr-minimal/</code> directory. You can also pass additional arguments in <code><a href="http://www.rdocumentation.org/packages/rmarkdown/topics/render">rmarkdown::render</a></code> to this function.</p>
<p>In order to share the dockerized R Markdown document, simply share the <code>.Rmd</code> file. Other users can use the <code><a href="../reference/lift.html">lift()</a></code> and <code><a href="../reference/render_docker.html">render_docker()</a></code> functions to render the document as above.</p>
</div>
<div id="housekeeping" class="section level1">
<h1 class="hasAnchor">
<a href="#housekeeping" class="anchor"></a>Housekeeping</h1>
<p>Normally, the argument <code>prune</code> is set to <code>TRUE</code> in <code><a href="../reference/render_docker.html">render_docker()</a></code>. This means any dangling containers or images due to unsuccessful builds will be automatically cleaned.</p>
<p>To clean up the dangling containers, images, and everything without specifying names, please use <code><a href="../reference/prune_container_auto.html">prune_container_auto()</a></code>, <code><a href="../reference/prune_image_auto.html">prune_image_auto()</a></code>, and <code><a href="../reference/prune_all_auto.html">prune_all_auto()</a></code>.</p>
<p>If you wish to manually remove the Docker container or image (whose information will be stored in an output YAML file) after sucessful rendering, use <code><a href="../reference/prune_container.html">prune_container()</a></code> and <code><a href="../reference/prune_image.html">prune_image()</a></code>:</p>
<div class="sourceCode"><pre class="sourceCode r"><code class="sourceCode r"><span class="kw"><a href="../reference/prune_image.html">purge_image</a></span>(<span class="kw">paste0</span>(path, <span class="st">"liftr-minimal.docker.yml"</span>))</code></pre></div>
<p>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 <code>purge_info = TRUE</code> (default) in <code><a href="../reference/render_docker.html">render_docker()</a></code>.</p>
</div>
<div id="install-docker" class="section level1">
<h1 class="hasAnchor">
<a href="#install-docker" class="anchor"></a>Install Docker</h1>
<p>Docker is an essential system requirement when using liftr to render the R Markdown documents. <code><a href="../reference/install_docker.html">install_docker()</a></code> will help you find the proper guide to install and set up Docker in your system. To check if Docker is correctly installed, use <code><a href="../reference/check_docker_install.html">check_docker_install()</a></code>; to check if the Docker daemon is running, use <code><a href="../reference/check_docker_running.html">check_docker_running()</a></code>. In particular, Linux users should configure Docker to <a href="https://docs.docker.com/engine/installation/linux/linux-postinstall/">run without sudo</a>.</p>
</div>
</div>
  </div>

  <div class="col-md-3 hidden-xs hidden-sm" id="sidebar">
        <div id="tocnav">
      <h2 class="hasAnchor">
<a href="#tocnav" class="anchor"></a>Contents</h2>
      <ul class="nav nav-pills nav-stacked">
<li><a href="#introduction">Introduction</a></li>
      <li>
<a href="#metadata-for-containerization">Metadata for containerization</a><ul class="nav nav-pills nav-stacked">
<li><a href="#required-metadata">Required metadata</a></li>
      <li><a href="#optional-metadata">Optional metadata</a></li>
      </ul>
</li>
      <li><a href="#containerize-the-document">Containerize the document</a></li>
      <li><a href="#render-the-document">Render the document</a></li>
      <li><a href="#housekeeping">Housekeeping</a></li>
      <li><a href="#install-docker">Install Docker</a></li>
      </ul>
</div>
      </div>

</div>


      <footer><div class="copyright">
  <p>Developed by Nan Xiao.</p>
</div>

<div class="pkgdown">
  <p>Site built with <a href="http://hadley.github.io/pkgdown/">pkgdown</a>.</p>
</div>

      </footer>
</div>

  </body>
</html>