Skip to main content

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.0.5. 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:

  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

# 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.

本节内容如下: