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.
Nota
We recommend that you build R models using version 4.0.5. If you have questions about R versions, contact Support.
Nota
Visit our GitHub repository or read our R Project documentation for technical information about how you deploy models with the R client.
Download and install the Promote R client either from CRAN or from GitHub.
Install from CRAN:
install.packages("promote")
Install from GitHub:
# You need the devtools package to install the Promote R client from GitHub.
install.packages("devtools")
require(devtools)
# Specify the location of the Promote R client on GitHub.
install_github("alteryx/promote-r-client")
Use the promote.library method to list the libraries needed to deploy your model.
promote.library <- function(NAME, src="CRAN", version=NULL, user=NULL, install=TRUE)
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 |
promote.library("MASS")
promote.library(c("rjson", "stringr"))
promote.library("cats", src="github", version="0.1", user="hilaryparker")
promote.library("my_proprietary_package", install=FALSE)
Use the promote.metadata method to assign related metadata to the model so the Promote platform can view it.
Aviso
The R client assigns metadata individually, with a maximum of six metadata values per model.
promote.metadata("name", value)
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. |
promote.metadata("aic", my.glm$aic)
Use the promote.unload method to remove from the model's dependency list any libraries that are not required for deployment.
promote.unload("name")
name | (required) | Name the package you want to exclude from deployment. |
promote.unload("ggplot2")
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.
model.predict <- function(df) {
data.frame("prediction"=predict(fit, df, type="response"))
}
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. |
model.predict <- function(data) {
# LMModel, a linear regression model trained previously, is executed
pred <- predict(LMModel, newdata=data.frame(data))
result <- data.frame(pred)
}
Use the promote.config method to specify the information needed to deploy your model to Promote.
promote.config <- c(
username = "USERNAME",
apikey = "APIKEY"
env = "YOURURL"
)
username | (required) | Specify your Promote username. |
apikey | (required) | Specify your Promote API key. |
env | (required) | Specify the URL of your Promote instance. |
promote.config <- c(
username="kermit",
apikey="1234556789101112131415",
env="https://promote.yourcompany.com"
)
Use the promote.deploy method to deploy your model and its related dependencies to the URL of your Promote instance.
Nota
You can call your deployed model using any programming language via the REST API.
promote.deploy(model_name)
model_name | (required) | Specify the name of the model you want to deploy. |
promote.config <- c(
username = "your username",
apikey = "your apikey",
env = "https://promote.yourcompany.com"
)
# A simple example model
iris$Sepal.Width_sq <- iris$Sepal.Width^2
fit <- glm(I(Species)=="virginica" ~ ., data=iris)
model.require <- function() {
require("randomForest")
}
model.predict <- function(df) {
data.frame("prediction"=predict(fit, df, type="response"))
}
promote.deploy("irisModel")
Use the promote.predict method to send a request to your model and request a prediction.
promote.predict(model_name = MODELNAME, data = DATA, model_owner = OWNER, raw_input = INPUT, silent = TRUE)
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 |
data <- rjson::fromJSON('{"name":"Sam"}')
promote.predict("HelloWorld",data)
# Output:
# greeting
# 1 Hello Sam!
#################### model_owner and silent example #############################
# send request to another users model, with silent = FALSE
promote.predict("HelloWorld",data, 'brandon',silent = FALSE)
# Output:
# https://promote.yourcompany.com/brandon/models/HelloWorld/username=colin&apikey=123455667781238912389
# greeting
# 1 Bye Sam!
############################## raw_input example ################################
jsonTest <- '{
"name": "colin",
"favorite_nums": [1, 2, 3, 4, 5],
"favorite_words": ["cat", "dog", "mouse",null]
}'
model.require <- function(){
library("RJSONIO")
}
# If we want to manually preprocess the JSON data
model.predict <- function(data){
data <- list(json=data)
# Below, parsing our JSON object manually with RJSONIO
d <-RJSONIO::fromJSON(data$json,nullValue = 'my_na_value')
}
promote.deploy('non_tabular_JSON')
# this will fail:
promote.predict('non_tabular_JSON', jsonTest)
# this will succeed because we are sending non-tabular data:
promote.predict('non_tabular_JSON', jsonTest,raw_input = TRUE)
Use RPostgreSQL to connect to an external database.
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:
API request
data.frame(jsonlite::fromJSON(data), stringsAsFactors=TRUE)
model.predict(data)
jsonlite::toJSON
API response
Nota
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.
# Below (for example) is incoming JSON, parsed BEFORE it gets sent to model.predict().
# API Requests --> model.predict(jsonlite::fromJSON(df))
model.predict <- function(df) {
lg <- df
m <- lapply(lg[[1]]$users, function(x) c(paste(x$user['name'],sample(1:2,1)), x$user['user_id'], x['ts']))
m <- do.call(rbind, m)
# Below, we split the dataframe so it is returned as JSON arrays.
m <- unname(split(m, 1:nrow(m)))
m
}
# jsonlite::toJSON() --> API Response
Nota
To test JSON data locally, you have to parse it in the Promote model.