R Client

Version:
2019.3
Last modified: April 02, 2020

To deploy an R model to Promote, you need to include information from the Promote library in your code. The library includes a number of methods you can use in the various stages of deployment.

We recommend that you build R models using version 3.3.2. If you have questions about R versions, contact Support.

Visit our GitHub repository or read our R Project documentation for technical information about how you deploy models with the R client.

Install R Client

Download and install the Promote R client either from CRAN or from GitHub.

Install from CRAN:

R
  1. install.packages("promote")

Install from GitHub:

R
  1. # You need the devtools package to install the Promote R client from GitHub.
  2.  
  3. install.packages("devtools")
  4. require(devtools)
  5.  
  6. # Specify the location of the Promote R client on GitHub.
  7.  
  8. install_github("alteryx/promote-r-client")

Pre-Deployment Methods

promote.library

Use the promote.library method to list the libraries needed to deploy your model.

Usage

R
  1. promote.library <- function(NAME, src="CRAN", version=NULL, user=NULL, install=TRUE)

Arguments

name (required) Name the package you want to install.  
src (optional) Source the package, such as to Github or CRAN. Default: CRAN
version (optional) Specify what version of the package you want to install. Default: NULL
user (optional) Associate a Github username with the package. Default: NULL
install (optional) Indicate if you want to install the package on the Promote server. Default: FALSE

Examples

R
  1. promote.library("MASS")
  2.  
  3. promote.library(c("rjson", "stringr"))
  4.  
  5. promote.library("cats", src="github", version="0.1", user="hilaryparker")
  6.  
  7. promote.library("my_proprietary_package", install=FALSE)

promote.metadata

Use the promote.metadata method to assign related metadata to the model so the Promote platform can view it.

The R client assigns metadata individually, with a maximum of six metadata values per model.

Usage

R
  1. promote.metadata("name", value)

Arguments

name (required) Name the metadata.
value (required) Provide a string or object you want to display in Promote. It must be 50 characters or less.

Example

R
  1. promote.metadata("aic", my.glm$aic)

promote.unload

Use the promote.unload method to remove from the model's dependency list any libraries that are not required for deployment.

Usage

R
  1. promote.unload("name")

Argument

name (required) Name the package you want to exclude from deployment.

Example

R
  1. promote.unload("ggplot2")

model.predict

Use the model.predict method to process requests for predictions. When you use this method, the Promote API endpoint receives the request, executes the prediction code, and then issues a response.

Usage

R
  1. model.predict <- function(df) {
  2.     data.frame("prediction"=predict(fit, df, type="response"))
  3. }

Arguments

input (required) The Promote API reads in a dataframe passed through a model you provide.
output (recommended) The Promote API returns dataframe output based on the model you provide.

Example

R
  1. model.predict <- function(data) {
  2.     # LMModel, a linear regression model trained previously, is executed
  3.     pred <- predict(LMModel, newdata=data.frame(data))
  4.     result <- data.frame(pred)
  5. }

Deployment Methods

promote.config

Use the promote.config method to specify the information needed to deploy your model to Promote.

Usage

R
  1. promote.config <- c(
  2.     username = "USERNAME",
  3.     apikey = "APIKEY"
  4.     env = "YOURURL"
  5. )

Arguments

username (required) Specify your Promote username.
apikey (required) Specify your Promote API key.
env (required) Specify the URL of your Promote instance.

Example

R
  1. promote.config <- c(
  2.     username="kermit",
  3.     apikey="1234556789101112131415",
  4.     env="https://promote.yourcompany.com"
  5. )

promote.deploy

Use the promote.deploy method to deploy your model and its related dependencies to the URL of your Promote instance.

You can call your deployed model using any programming language via the REST API.

Usage

R
  1. promote.deploy(model_name)

Argument

model_name (required) Specify the name of the model you want to deploy.

Example

R
  1. promote.config <- c(
  2.  username = "your username",
  3.  apikey = "your apikey",
  4.  env = "https://promote.yourcompany.com"
  5. )
  6.  
  7. # A simple example model
  8. iris$Sepal.Width_sq <- iris$Sepal.Width^2
  9. fit <- glm(I(Species)=="virginica" ~ ., data=iris)
  10.  
  11. model.require <- function() {
  12.     require("randomForest")
  13. }
  14.  
  15. model.predict <- function(df) {
  16.  data.frame("prediction"=predict(fit, df, type="response"))
  17. }
  18.  
  19. promote.deploy("irisModel")

Post-Deployment Method

promote.predict

Use the promote.predict method to send a request to your model and request a prediction.

Usage

R
  1. promote.predict(model_name = MODELNAME, data = DATA, model_owner = OWNER, raw_input = INPUT, silent = TRUE)

Arguments

model_name (required) Name the model you want to request a prediction from.  
data (required) Provide the data you want to use to make the prediction. It must be in JSON format.  
model_owner (optional) Indicate the name of the model owner. Default: NULL
raw_input (optional) Indicate whether the model returns data it coerced into a dataframe. Default: TRUE
silent (optional) Indicate whether to print the request URL to your console. Default: TRUE

Example

R
  1. data <- rjson::fromJSON('{"name":"Sam"}')
  2. promote.predict("HelloWorld",data)
  3.  
  4. # Output:
  5. # greeting
  6. # 1 Hello Sam!
  7.  
  8. #################### model_owner and silent example #############################
  9.  
  10. # send request to another users model, with silent = FALSE
  11. promote.predict("HelloWorld",data, 'brandon',silent = FALSE)
  12.  
  13. # Output:
  14.  
  15. # https://promote.yourcompany.com/brandon/models/HelloWorld/username=colin&apikey=123455667781238912389
  16. # greeting
  17. # 1 Bye Sam!
  18.  
  19. ############################## raw_input example ################################
  20.  
  21. jsonTest <- '{
  22.     "name": "colin",
  23.     "favorite_nums": [1, 2, 3, 4, 5],
  24.     "favorite_words": ["cat", "dog", "mouse",null]
  25. }'
  26.  
  27. model.require <- function(){
  28.   library("RJSONIO")
  29. }
  30.  
  31. # If we want to manually preprocess the JSON data
  32. model.predict <- function(data){
  33.   data <- list(json=data)
  34.   # Below, parsing our JSON object manually with RJSONIO
  35.   d <-RJSONIO::fromJSON(data$json,nullValue = 'my_na_value')
  36. }
  37.  
  38. promote.deploy('non_tabular_JSON')
  39.  
  40. # this will fail:
  41. promote.predict('non_tabular_JSON', jsonTest)
  42.  
  43. # this will succeed because we are sending non-tabular data:
  44. promote.predict('non_tabular_JSON', jsonTest,raw_input = TRUE)

Connect to a Database with R

Use RPostgreSQL to connect to an external database.

Nested JSON and R

R parses JSON data with the package jsonlite.

You have to parse JSON data and transform it into an R object before you can call the model.predict method. This means that you pass R objects to model.predict. For that reason, Promote expects your R script to process data in this sequence:

  1. API request
  2. data.frame(jsonlite::fromJSON(data), stringsAsFactors=TRUE)
  3. model.predict(data)
  4. jsonlite::toJSON
  5. API response

You can use rjson instead of jsonlite. In the Promote UI, navigate to your model, and then to its Advanced tab. Once there, set the JSONLITE environment variable to equal FALSE.

Example

R
  1. # Below (for example) is incoming JSON, parsed BEFORE it gets sent to model.predict().
  2. # API Requests --> model.predict(jsonlite::fromJSON(df))
  3.  
  4. model.predict <- function(df) {
  5.   lg <- df
  6.   m <- lapply(lg[[1]]$users, function(x) c(paste(x$user['name'],sample(1:2,1)), x$user['user_id'], x['ts']))
  7.   m <- do.call(rbind, m)
  8.   # Below, we split the dataframe so it is returned as JSON arrays.
  9.   m <- unname(split(m, 1:nrow(m)))
  10.   m
  11. }
  12.  
  13. # jsonlite::toJSON() --> API Response

To test JSON data locally, you have to parse it in the Promote model.

 

Was This Helpful?

Running into problems or issues with your Alteryx product? Visit the Alteryx Community or contact support.