Syberia



Download

First, make sure you have installed R. If you're on OSX and have Homebrew, you can run 

# Run this from your command line terminal.
brew tap homebrew/science && brew install Caskroom/cask/xquartz && brew install r

Downloading Syberia into a sandbox that does not interfere with your usual R package library can be done by running the minimal example project: 


# Run this from your command line terminal.
git clone git@github.com:syberia/example.sy.git && cd example.sy && R

If you are having trouble, scroll down to the troubleshooting section.

After the packages have downloaded and your R session opens type 
    
run("example"); model$predict(iris[1:5, ])

If everything worked correctly, you should see some model predictions.

Let's walk through what happened during this process.

  1. The command 
    git clone git@github.com:syberia/example.sy.git
    pulled the example project GitHub repository down and then we moved to the directory using 
    cd example.sy
    .
  2. We started R, upon which it immediately began processing the project's Rprofile, the file all R sessions execute during startup.
  3. The Rprofile in the example project installed the devtools, purrr, and R6 packages from CRAN as well as testthatsomemore and lockbox. The former is an extension of the testthat R unit testing package, whereas the latter is an equivalent of Bundler for R: it will keep a separate directory for all of the packages we download so they do not clash with your global R package versions.
  4. The Rprofile finally called 
    lockbox::lockbox("lockfile.yml")
    . This file is parsed by lockbox to understand which packages we need for this project. If you ever want to load more packages, place them in the lockfile instead of adding 
    library
    or 
    install.packages
    calls. This ensures pushing and pulling the project to and from version control loads an R session with the same packages across your whole team's computers.
  5. Lockbox installed some packages, the most important ones being syberia, director, mungebits2, tundra, and stagerunner. These form the core of the current Syberia modeling engine. As with the Unix philosophy, Syberia aims to create small, reusable tools that do one job well.
  6. The Syberia project was initialized using 
    syberia::syberia_project()
    . This bootstrapping procedure builds an R object called a 
    syberia_engine
    that is built off a 
    director
    and will manage all the files and directories in your project.
  7. During project bootstrapping, the project's engines file was read to understand what "kind" of Syberia project you will be working on. In our case, we wish to make some production-ready machine learning models, so Syberia downloaded and loaded the modeling engine. Similar to Rails engines, Syberia itself is a skeleton and offers no functionality: all of the real meat is in the engines you mount and use in your projects, and creating new ones is trivial.
  8. The modeling engine's engines file specified a dependency on the base engine. For now, most Syberia projects will be built off the base engine, but this may change once Syberia starts replacing outdated R project structures like packages.
  9. If all went well, the 
    syberia_engine
    loaded and mounted both engines in the appropriate hierarchy of dependencies. Syberia takes care of downloading, mounting, and maintaining your engines. The modeling engine's boot file was executed to attach a new namespace called 
    syberia:modeling
    to your R search path. This is used to provide global helper functions like 
    run
    so that they do not clash with your global namespace.
  10. You have a freshly printed Syberia session up and running! We'll cover what happened when you executed 
    run("example")
    in a little bit.

If you ran into any problems during the above process, continue reading for the troubleshooting guide (or use ctrl+F to jump straight to your error message). Otherwise, you can file a new issue on GitHub explaining your problem and the Syberia core team will jump to the rescue.

Note the above process installed Syberia into a custom library managed by lockbox. To install it globally, run:

    
devtools::install_github("syberia/syberia")

Recommended Next Steps

Troubleshooting

Cannot open file '~/.R/lockbox/.staging/magrittr/R/magrittr.rdb': No such file or directory

This is an issue with lockbox on certain system configurations. Restarting R should fix the issue. Otherwise, try executing the following command from the terminal and then restarting R. (Make sure you are starting R from the root of the example project so that you load the necessary Rprofile.)


rm -rf ~/.R/lockbox/.staging