Author: Andrie de Vries
Date: 2017-06-26

# Using checkpoint in a markdown document

#### Andrie de Vries

#### 2017-06-26

# 1 Introduction

Sometimes you want to use create a report using `markdown`, and you want to `checkpoint` the code in this document.

However, running this as part of a `R Markdown` process is problematic, since the knitting process runs inside a temporary folder that is different from the current working directory.

To resolve this, I propose a hacky solution: create a “manifest” file in the same folder that contains all of the `library()` calls.

# 2 Example

Imagine you have a small script that you want to put in an R Markdown document with a checkpoint.

    # demo script
    # Example from ?darts
    library(darts)
    x = c(12,16,19,3,17,1,25,19,17,50,18,1,3,17,2,2,13,18,16,2,25,5,5,
          1,5,4,17,25,25,50,3,7,17,17,3,3,3,7,11,10,25,1,19,15,4,1,5,12,17,16,
          50,20,20,20,25,50,2,17,3,20,20,20,5,1,18,15,2,3,25,12,9,3,3,19,16,20,
          5,5,1,4,15,16,5,20,16,2,25,6,12,25,11,25,7,2,5,19,17,17,2,12)
    mod = simpleEM(x, niter=100)
    e = simpleExpScores(mod$s.final)
    oldpar <- par(mfrow=c(1, 2))
    drawHeatmap(e)
    drawBoard(new=TRUE)
    drawAimSpot(e, cex = 5)
    par(oldpar)

# 3 The checkpoint solution

The only way I’ve found to get `checkpoint()` to work inside an R Markdown document, is really a bit of a hack. The workaround is to create a manifest of required packages, and write this to an R file in the working directory.

For example, imagine your R script uses the `darts` package, then create a manifest file like this:

    ```{r, include=FALSE}
    # write a manifest to local folder
    cat("
    library(darts)
    ",
    file = "manifest.R")
    ```

This is hacky, since it requires you to construct the list of `library()` calls by hand and put these into the manifest file.

(Note that you can use `include=FALSE` in the code block, so that this code doesn’t show up in your rendered document.)

Once this is done, the checkpoint process from here is straight-forward

    ```{r, include=FALSE}
    # Create .checkpoint folder (in tempdir for this example)
    td <- tempdir()
    dir.create(file.path(td, ".checkpoint"), recursive = TRUE, showWarnings = FALSE)

    # Create the checkpoint
    library(checkpoint)
    checkpoint("2017-03-28", checkpointLocation = td)
    ```

# 4 Check that this works

Now you are ready to put these instructions in an actual code block to see what happens.

    # write a manifest to local folder
    cat('
    library(darts)
    ',
    file = "manifest.R")

    # Create .checkpoint folder (in tempdir for this example)
    dir.create(file.path(tempdir(), ".checkpoint"), recursive = TRUE, showWarnings = FALSE)
    options(install.packages.compile.from.source = "no")

    # Create the checkpoint
    library(checkpoint)
    checkpoint("2017-03-28", checkpointLocation = tempdir())

    ## Scanning for packages used in this project

    ## No file at path 'C:\Users\adevries\AppData\Local\Temp\Rtmpu0jy9G\file4be02afe6dc6.Rmd'.

    ## No file at path 'C:\Users\adevries\AppData\Local\Temp\Rtmpu0jy9G\file4be035735eb1.Rmd'.

    ## No file at path 'C:\Users\adevries\AppData\Local\Temp\Rtmpu0jy9G\file4be08557fcc.Rmd'.

    ## - Discovered 3 packages

    ## Unable to parse 3 files:

    ## - archive/managing-checkpoint-archives.Rmd

    ## - checkpoint.Rmd

    ## - using-checkpoint-with-knitr.Rmd

    ## Installing packages used in this project

    ##  - Installing 'darts'

    ## darts

    ##  - Installing 'knitr'

    ## knitr

    ## also installing the dependencies 'mime', 'stringi', 'magrittr', 'evaluate', 'digest', 'highr', 'markdown', 'stringr', 'yaml'

    ## checkpoint process complete

    ## ---

If this worked, you should see that the library path now points to `tempdir()` and that `darts` is one of only a few package installed:

    .libPaths()
    ## [1] ".../Temp/RtmpIVB6bI/.checkpoint/2017-03-28/lib/x86_64-w64-mingw32/3.3.2"
    ## [2] ".../Temp/RtmpIVB6bI/.checkpoint/R-3.3.2"

    installed.packages()[, "Package"]

    ##          darts         digest       evaluate          highr          knitr
    ##        "darts"       "digest"     "evaluate"        "highr"        "knitr"
    ##       magrittr       markdown           mime        stringi        stringr
    ##     "magrittr"     "markdown"         "mime"      "stringi"      "stringr"
    ##           yaml       compiler           base           boot          class
    ##         "yaml"     "compiler"         "base"         "boot"        "class"
    ##        cluster      codetools       compiler       datasets        foreign
    ##      "cluster"    "codetools"     "compiler"     "datasets"      "foreign"
    ##       graphics      grDevices           grid     KernSmooth        lattice
    ##     "graphics"    "grDevices"         "grid"   "KernSmooth"      "lattice"
    ##           MASS         Matrix        methods           mgcv           nlme
    ##         "MASS"       "Matrix"      "methods"         "mgcv"         "nlme"
    ##           nnet       parallel          rpart        spatial        splines
    ##         "nnet"     "parallel"        "rpart"      "spatial"      "splines"
    ##          stats         stats4       survival          tcltk          tools
    ##        "stats"       "stats4"     "survival"        "tcltk"        "tools"
    ##   translations          utils
    ## "translations"        "utils"

# 5 Your real R code:

Now your real R code follows, and it creates the plot, as expected:

    # Example from ?darts
    library(darts)
    x = c(12,16,19,3,17,1,25,19,17,50,18,1,3,17,2,2,13,18,16,2,25,5,5,
          1,5,4,17,25,25,50,3,7,17,17,3,3,3,7,11,10,25,1,19,15,4,1,5,12,17,16,
          50,20,20,20,25,50,2,17,3,20,20,20,5,1,18,15,2,3,25,12,9,3,3,19,16,20,
          5,5,1,4,15,16,5,20,16,2,25,6,12,25,11,25,7,2,5,19,17,17,2,12)
    mod = simpleEM(x, niter=100)
    e = simpleExpScores(mod$s.final)
    oldpar <- par(mfrow=c(1, 2))
    drawHeatmap(e)
    drawBoard(new=TRUE)
    drawAimSpot(e, cex = 5)

    par(oldpar)

# 6 Conclusion

This is a bit of a hack, but points in a direction for getting your R Markdown script to be checkpointed.

    # clean up

    detach("package:darts", unload = TRUE)
    unlink("manifest.R")
    unlink(file.path(tempdir(), ".checkpoint"), recursive = TRUE)
    unCheckpoint(oldLibPaths)
    .libPaths()

    ## [1] "C:/Users/adevries/Documents/R/win-library/3.4"
    ## [2] "C:/R/R-3.4.0/library"