R - Command Line Interface (CLI) and RStudio - template

README.md

R - Interactive Sessions and Command Line Interface

This is a template for R projects that should work both on the command line as well as in an interactive session.

Template Files

The template is made up of three files:

1. foo.r

   Contains all of the actual code of the application.

2. cli.r

   Contains the command line interface to the application. It is to be executed via:

   Rscript cli.r --help
   

   Use command line arguments to configure the application.

3. session.r

   Contains the interactive session interface to the application. Just open the file in RStudio and click the source button or use its keyboard shortcut CTRL + SHIFT + S.

   Modify the variables in the configuration section to configure the application.

Start a new Project

To start a new R project using this template, use git:

# get a copy of the template
user@host ~/projects $ git clone https://gist.github.com/wookietreiber/0ff145270c75f11e956284412b3847b8.git project
Cloning into 'project'...
remote: Counting objects: 6, done.
remote: Compressing objects: 100% (6/6), done.
remote: Total 6 (delta 0), reused 6 (delta 0), pack-reused 0
Unpacking objects: 100% (6/6), done.

# initialize new git repository
user@host ~/projects $ cd project/
user@host ~/projects/project $ rm -fr .git
user@host ~/projects/project $ git init
Initialized empty Git repository in /home/user/projects/project/.git/

# hack away - may the source be with you!

cli.r

library(optparse)

source("foo.r")

# ------------------------------------------------------------------------------
# defaults
# ------------------------------------------------------------------------------

default.nthreads <- 1
default.verbose <- FALSE

# ------------------------------------------------------------------------------
# parsing arguments
# ------------------------------------------------------------------------------

options <- list (

  make_option(
    opt_str = c("-t", "--threads"),
    dest    = "nthreads",
    type    = "integer",
    default = default.nthreads,
    help    = paste0("number of threads to use, defaults to ", default.nthreads),
    metavar = "4"),

  make_option(
    opt_str = c("-v", "--verbose"),
    action  = "store_true",
    default = default.verbose,
    help    = "print more output on what's happening")

)

parser <- OptionParser(
  usage       = "Rscript %prog [options] input output",
  option_list = options,
  description = "\nan awesome R script",
  epilogue    = "use with caution, the awesomeness might slap you in the face!"
)

cli <- parse_args(parser, positional_arguments = 2)

# ------------------------------------------------------------------------------
# assign a few shortcuts
# ------------------------------------------------------------------------------

input    <- cli$args[1]
output   <- cli$args[2]
nthreads <- cli$options$nthreads
verbose  <- cli$options$verbose

# ------------------------------------------------------------------------------
# actual program
# ------------------------------------------------------------------------------

foo(input, output, nthreads, verbose)

foo.r

#' Awesome function that heals the world.
#'
#' @param input path to input file
#' @param output path to output file
#' @param nthreads number of threads to use
#' @param verbose print more output on what's happening
#'
#' @return a better world
#'
#' @examples
#' foo("/path/to/input", "/path/to/output", 42, true)
#'
foo <- function(input, output, nthreads, verbose) {

  if (verbose) {
    cat("[info] heal the world ...\n")
  }

  cat(paste0("number of threads: ", nthreads, "\n"))
  cat(paste0("input: ", input, "\n"))
  cat(paste0("output: ", output, "\n"))

  if (verbose) {
    cat("[info] end of script\n")
  }

}

session.r

source("foo.r")

# ------------------------------------------------------------------------------
# configuration
# ------------------------------------------------------------------------------

input    <- "/path/to/input"
output   <- "/path/to/output"

nthreads <- 42
verbose  <- TRUE

# ------------------------------------------------------------------------------
# actual program
# ------------------------------------------------------------------------------

foo(input, output, nthreads, verbose)