R Client
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 4.1.3. 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:
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")
Pre-Deployment Methods
promote.library
Use the promote.library method to list the libraries needed to deploy your model.
Usage
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
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)
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
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
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
promote.unload("name")
Argument
name | (required) | Name the package you want to exclude from deployment. |
Example
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
model.predict <- function(df) { data.frame("prediction"=predict(fit, df, type="response")) }
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
model.predict <- function(data) { # LMModel, a linear regression model trained previously, is executed pred <- predict(LMModel, newdata=data.frame(data)) result <- data.frame(pred) }
Deployment Methods
promote.config
Use the promote.config method to specify the information needed to deploy your model to Promote.
Usage
promote.config <- c( username = "USERNAME", apikey = "APIKEY" env = "YOURURL" )
Arguments
username | (required) | Specify your Promote username. |
apikey | (required) | Specify your Promote API key. |
env | (required) | Specify the URL of your Promote instance. |
Example
promote.config <- c( username="kermit", apikey="1234556789101112131415", env="https://promote.yourcompany.com" )
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
promote.deploy(model_name)
Argument
model_name | (required) | Specify the name of the model you want to deploy. |
Example
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")
Post-Deployment Method
promote.predict
Use the promote.predict method to send a request to your model and request a prediction.
Usage
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
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)
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:
API request
data.frame(jsonlite::fromJSON(data), stringsAsFactors=TRUE)
model.predict(data)
jsonlite::toJSON
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
# 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
注記
To test JSON data locally, you have to parse it in the Promote model.