Welcome to ChampagnR framework

“Rush your project faster and get your Champagne earlier”

ChampagnR is a highly productive, lightweight, and easy-to-use framework for R developers.

It provides great features: packages management, logging, debugging, server mode, etc…

Inspired by

• Ruby On Rails for their philosophy of Convention Over Configuration, etc…

• ProjectTemplate for the job they had already done by trying to make a template for all R projects.

• r-server-template for their way to maintain a R server and gracefully handle all signal that an Unix process can have.

Getting started

From the root of your project, install the required packages by running:

R -f script/install.R

And then launch your console (with the options you want but don’t forget to source “config/application.R”):

R --no-save --no-restore
source("config/application.R")

And here you go! You’re ready to develop!

Packages

Add your needed packages into “config/packages.yml” and then run:

R -f script/install.R

Production environement

There is some specific behaviors when production environement is enabled. To launch R in production, execute the following command:

R --args production

In your code, you can test production mode like in the following example:

if (config.production) {
  ...
}

Server mode

The server mode require a running instance of redis (an in-memory key-value persistent storage). Redis will act as a queue for incoming jobs. Using a redis client (like redis-cli) push a command into the list “public_jobs” and your server will execute it.

In developement, the server mode will connect to your local redis instance.

In production environement, it will connect using some environement variable. Here how to configure it:

export REDIS_HOST="..."
export REDIS_PORT="..."
export REDIS_PASS="..."

To simply run your server:

R -f script/server.R

Logging

As discribed below, all your log files are stored in the log folder. But there is a default log file that is named “application.log”.

You can easily write into this files with these R functions:

log_debug('A Debugging Message') # Won't print anything in production mode
log_info('An Info Message')
log_warn('A Warning Message')
log_error('An Error Message')
log_fatal('A Fatal Error Message')

Debugging

Thanks to our logging system and the way we handle errors. All bugs can be handled post-mortem by looking at “application.log”.

Log contains a backtrace to know where bugs come from.

You can customize the error handler here at “config/initializers/backtrace.R”.

Directory

To know more on how the framework works.

app

This is the main folder where all your R files are automatically sourced. There are already some folders representing each step of data analysis but feel free to add yours.

config

Here you will find config stuff that normarly don’t change except at the setup of your application.

config/packages.yml

This simple file contains all your needed packages. These listed packages will automatically be installed and loaded.

config/initializers

This a sweet way to initialize something at startup. Just create a file per behavior and it will be automatically loaded.

config/application.R

This is the main R file of your application. You can configure here the ChampagnR behaviors.

config/boot.R

This is our way to boot an application. You don’t have edit this file.

data

Simply all your raw data.

lib

All the “external” librairies and more that is not part of your R code.

lib/batch

All the batch task that you need to be executed by a CRON for example.

log

All your log files.

script

It contains the different ways to start your R envrionement.

test

This is damn important: unit testing!

tmp

Temporary files are stored here. Feel free to create your folders.

tmp/cache

This folder should contains cache files that R can access for a faster processing (Rdata, etc…). This folder should only contain files that can be regenerated, not important files. When your project will be mature, this folder can be mounted and shared among your slave computers (aka workers).

License

ChampagnR is release under the GNU LESSER GENERAL PUBLIC LICENSE, version 3 or later.

TODOs

• Packages managment should check collision between namespaces