R Model On-Boarding guide

Note

R Client v0.2-8 was tested with the Acumos Boreas platform release

Prerequisites

Before you begin:

  1. You must have the following packages installed in your system : protobuf-compiler,protobuf-c-compiler, libprotobuf-c-dev, libprotobuf-dev,libprotoc-dev

  2. You must have an Acumos account

  3. You must have protobuf 3 installed on your system (version 2 will not work).

    git clone https://github.com/google/protobuf.git protobuf
    cd protobuf
    ./autogen.sh
    ./configure --prefix=`pwd`/../`uname -m`-linux-gnu
    make
    make install
    
  4. You must have R installed on you system (R>3.4.4). Please have a look at cran.r-project.org

Installing the Acumos R Client

Within R you need to install and load all dependent packages from CRAN first.

install.packages(c("Rcpp","RCurl","RUnit","rmarkdown","knitr","pinp","xml2"))
library(Rcpp,Rcurl,RUnit,rmarkdown,knitr,pinp)

Then Install the Acumos R Client package and RProtobuf package thanks to the following command:

install.packages("RProtoBuf")
install.packages("acumos",,c("http://r.research.att.com","http://rforge.net"))

Alternatively, to install from sources:

git clone git@github.com:s-u/acumos.git or git clone https://github.com/s-u/acumos.git
R CMD build acumos
R CMD INSTALL acumos_*.tar.gz

Using the Acumos R Client

Model bundle

To on-board a model in Acumos you need to create a model bundle, use acumos::compose() with the functions to expose to create it. Below is an example of how create a model bundle based on the IRIS model.

acumos::compose(predict=function(..., inputs=lapply(iris[-5], class)) print(as.character(predict(rf, as.data.frame(list(...))))),
aux = list(rf = randomForest(Species ~ ., data=iris)),name="IRIS_model", file="path/to/store/the/model/bundle/IRIS_model.zip")

This model bundle contains :

  1. meta.json defining the component and their metadata,
  2. component.bin the binary payload,
  3. and component.proto with the protobuf specs.

Please consult R documentation page for details, i.e., use ?compose in R or see the Compose page at RForge.

If you used R under windows you could meet an issue using the acumos::compose() function due to some problems between R under windows and zip. If RTools is not installed on your windows environment, the model bundle will not be created. So please follows the installation procedure of Rtools then set your environmental variables properly, add the bin folder of Rtools to the system path.

Authentication and upload

  • CLI on-boarding

Once the model bundle is created, you can use the push() API to upload it in Acumos. This CLI (Command Line Interface) on-boarding.

acumos::push("https://url","file","username:token","create","license")

url can be found in the ON-BOARDING MODEL page of your Acumos portal and looks like : “hotsname:port/onboarding-app/v2/models”

file : component.zip

username : your Acumos username

token : Authentication token available in the Acumos portal in your profile section

create : logical parameter (Boolean) to trigger the creation of microservice at the end of on-boarding process. By default create=TRUE, if you don’t want to create the microservice modify the value to FALSE (create =FALSE)

license : path to the license file : “license.json”. After onboarding the model with license, the artifacts will show license file with name “license.json” even if user has uploaded the license file with different name.

You can also authenticate yourself by using the auth() API:

acumos::auth("url","username","password")

url can be found in the ON-BOARDING MODEL page of your Acumos portal and lokks like “hostname:port/onboarding-app/v2/auth”

username : your Acumos username

password : your Acumos password

In the Response, you will receive an authentication token to be used in the acumos::push() function like that : acumos::push(“https://url”,”file”,”token”,”create”,”license”)

  • Web on-boarding

You can also drag & drop your model bundle on the “ON-BORADING BY WEB” page in your Acumos instance, or browse you model bundle from this page. This is Web on-boarding.