publishWebService: Publish a function as a Microsoft Azure Web Service.

In AzureML: Interface with Azure Machine Learning Datasets, Experiments and Web Services

Description

Publish a function to Microsoft Azure Machine Learning as a web service. The web service created is a standard Azure ML web service, and can be used from any web or mobile platform as long as the user knows the API key and URL. The function to be published is limited to inputs/outputs consisting of lists of scalar values or single data frames (see the notes below and examples). Requires a zip program to be installed (see note below).

Usage

publishWebService(ws, fun, name, inputSchema, outputSchema,
  data.frame = FALSE, export = character(0), noexport = character(0),
  packages, version = "3.1.0", serviceId, host = ws$.management_endpoint,
  .retry = 3)

updateWebService(ws, fun, name, inputSchema, outputSchema, data.frame = FALSE,
  export = character(0), noexport = character(0), packages,
  version = "3.1.0", serviceId, host = ws$.management_endpoint,
  .retry = 3)

Arguments

ws	An AzureML workspace reference returned by workspace.
fun	a function to publish; the function must have at least one argument.
name	name of the new web service; ignored when serviceId is specified (when updating an existing web service).
inputSchema	either a list of fun input parameters and their AzureML types formatted as list("arg1"="type", "arg2"="type", ...), or an example input data frame when fun takes a single data frame argument; see the note below for details.
outputSchema	list of fun outputs and AzureML types, formatted as list("output1"="type", "output2"="type", ...), optional when inputSchema is an example input data frame.
data.frame	TRUE indicates that the function fun accepts a data frame as input and returns a data frame output; automatically set to TRUE when inputSchema is a data frame.
export	optional character vector of variable names to explicitly export in the web service for use by the function. See the note below.
noexport	optional character vector of variable names to prevent from exporting in the web service.
packages	optional character vector of R packages to bundle in the web service, including their dependencies.
version	optional R version string for required packages (the version of R running in the AzureML Web Service).
serviceId	optional Azure web service ID; use to update an existing service (see Note below).
host	optional Azure regional host, defaulting to the global management_endpoint set in workspace
.retry	number of tries before failing

Value

A data.frame describing the new service endpoints, cf. endpoints. The output can be directly used by the consume function.

Note

Data Types

AzureML data types are different from, but related to, R types. You may specify the R types numeric, logical, integer, and character and those will be specified as AzureML types double, boolean, int32, string, respectively.

Input and output schemas

Function input must be:

1. named scalar arguments with names and types specified in inputSchema

2. one or more lists of named scalar values

3. a single data frame when data.frame=TRUE is specified; either explicitly specify the column names and types in inputSchema or provide an example input data frame as inputSchema

Function output is always returned as a data frame with column names and types specified in outputSchema. See the examples for example use of all three I/O options.

Updating a web service

Leave the serviceId parameter undefined to create a new AzureML web service, or specify the ID of an existing web service to update it, replacing the function, inputSchema, outputSchema, and required R pacakges with new values. The name parameter is ignored serviceId is specified to update an existing web service.

The updateWebService function is nearly an alias for publishWebService, differing only in that the serviceId parameter is required by updateWebService.

The publishWebService function automatically exports objects required by the function to a working environment in the AzureML machine, including objects accessed within the function using lexical scoping rules. Use the exports parameter to explicitly include other objects that are needed. Use noexport to explicitly prevent objects from being exported.

Note that it takes some time to update the AzureML service on the server. After updating the service, you may have to wait several seconds for the service to update. The time it takes will depend on a number of factors, including the complexity of your web service function.

External zip program required

The function uses zip to compress information before transmission to AzureML. To use this, you need to have a zip program installed on your machine, and this program should be available in the path. The program should be called zip otherwise R may not find it. On windows, it is sufficient to install RTools (see https://cran.r-project.org/bin/windows/Rtools/)

See Also

endpoints, discoverSchema, consume and services.

Other publishing functions: deleteWebService, workspace

Examples

## Not run: 
# Use a default configuration in ~/.azureml, alternatively
# see help for `?workspace`.

ws <- workspace()
  
# Publish a simple model using the lme4::sleepdata ---------------------------

library(lme4)
set.seed(1)
train <- sleepstudy[sample(nrow(sleepstudy), 120),]
m <- lm(Reaction ~ Days + Subject, data = train)

# Deine a prediction function to publish based on the model:
sleepyPredict <- function(newdata){
  predict(m, newdata=newdata)
}

ep <- publishWebService(ws, fun = sleepyPredict, name="sleepy lm",
                        inputSchema = sleepstudy,
                        data.frame=TRUE)

# OK, try this out, and compare with raw data
ans <- consume(ep, sleepstudy)$ans
plot(ans, sleepstudy$Reaction)

# Remove the service
deleteWebService(ws, "sleepy lm")



# Another data frame example -------------------------------------------------

# If your function can consume a whole data frame at once, you can also
# supply data in that form, resulting in more efficient computation.
# The following example builds a simple linear model on a subset of the
# airquality data and publishes a prediction function based on the model.
set.seed(1)
m <- lm(Ozone ~ ., data=airquality[sample(nrow(airquality), 100),])
# Define a prediction function based on the model:
fun <- function(newdata)
{
  predict(m, newdata=newdata)
}
# Note the definition of inputSchema and use of the data.frame argument.
ep <- publishWebService(ws, fun=fun, name="Ozone",
                        inputSchema = airquality,
                        data.frame=TRUE)
ans <- consume(ep, airquality)$ans
plot(ans, airquality$Ozone)
deleteWebService(ws, "Ozone")



# Train a model using diamonds in ggplot2 ------------------------------------
# This example also demonstrates how to deal with factor in the data

data(diamonds, package="ggplot2")
set.seed(1)
train_idx = sample.int(nrow(diamonds), 30000)
test_idx = sample(setdiff(seq(1, nrow(diamonds)), train_idx), 500)
train <- diamonds[train_idx, ]
test  <- diamonds[test_idx, ]

model <- glm(price ~ carat + clarity + color + cut - 1, data = train, 
             family = Gamma(link = "log"))

diamondLevels <- diamonds[1, ]

# The model works reasonably well, except for some outliers
plot(exp(predict(model, test)) ~ test$price)

# Create a prediction function that converts characters correctly to factors

predictDiamonds <- function(x){
  x$cut     <- factor(x$cut,     
                      levels = levels(diamondLevels$cut), ordered = TRUE)
  x$clarity <- factor(x$clarity, 
                      levels = levels(diamondLevels$clarity), ordered = TRUE)
  x$color   <- factor(x$color,   
                      levels = levels(diamondLevels$color), ordered = TRUE)
  exp(predict(model, newdata = x))
}


# Publish the service

ws <- workspace()
ep <- publishWebService(ws, fun = predictDiamonds, name = "diamonds",
                        inputSchema = test,
                        data.frame = TRUE
)

# Consume the service
results <- consume(ep, test)$ans
plot(results ~ test$price)

deleteWebService(ws, "diamonds")



# Simple example using scalar input ------------------------------------------

ws <- workspace()

# Really simple example:
add <- function(x,y) x + y
endpoint <- publishWebService(ws, 
                              fun = add, 
                              name = "addme", 
                              inputSchema = list(x="numeric", 
                                                 y="numeric"), 
                              outputSchema = list(ans="numeric"))
consume(endpoint, list(x=pi, y=2))

# Now remove the web service named "addme" that we just published
deleteWebService(ws, "addme")



# Send a custom R function for evaluation in AzureML -------------------------

# A neat trick to evaluate any expression in the Azure ML virtual
# machine R session and view its output:
ep <- publishWebService(ws, 
                        fun =  function(expr) {
                          paste(capture.output(
                            eval(parse(text=expr))), collapse="\n")
                        },
                        name="commander", 
                        inputSchema = list(x = "character"),
                        outputSchema = list(ans = "character"))
cat(consume(ep, list(x = "getwd()"))$ans)
cat(consume(ep, list(x = ".packages(all=TRUE)"))$ans)
cat(consume(ep, list(x = "R.Version()"))$ans)

# Remove the service we just published
deleteWebService(ws, "commander")



# Understanding the scoping rules --------------------------------------------

# The following example illustrates scoping rules. Note that the function
# refers to the variable y defined outside the function body. That value
# will be exported with the service.
y <- pi
ep <- publishWebService(ws, 
                        fun = function(x) x + y, 
                        name = "lexical scope",
                        inputSchema = list(x = "numeric"), 
                        outputSchema = list(ans = "numeric"))
cat(consume(ep, list(x=2))$ans)

# Remove the service we just published
deleteWebService(ws, "lexical scope")


# Demonstrate scalar inputs but sending a data frame for scoring -------------

# Example showing the use of consume to score all the rows of a data frame
# at once, and other invocations for evaluating multiple sets of input
# values. The columns of the data frame correspond to the input parameters
# of the web service in this example:
f <- function(a,b,c,d) list(sum = a+b+c+d, prod = a*b*c*d)
ep <-  publishWebService(ws, 
                         f, 
                         name = "rowSums",
                         inputSchema = list(
                           a = "numeric", 
                           b = "numeric", 
                           c = "numeric", 
                           d = "numeric"
                         ),
                         outputSchema = list(
                           sum ="numeric", 
                           prod = "numeric")
)
x <- head(iris[,1:4])  # First four columns of iris

# Note the following will FAIL because of a name mismatch in the arguments
# (with an informative error):
consume(ep, x, retryDelay=1)
# We need the columns of the data frame to match the inputSchema:
names(x) <- letters[1:4]
# Now we can evaluate all the rows of the data frame in one call:
consume(ep, x)
# output should look like:
#    sum    prod
# 1 10.2   4.998
# 2  9.5   4.116
# 3  9.4  3.9104
# 4  9.4   4.278
# 5 10.2    5.04
# 6 11.4 14.3208

# You can use consume to evaluate just a single set of input values with this
# form:
consume(ep, a=1, b=2, c=3, d=4)

# or, equivalently,
consume(ep, list(a=1, b=2, c=3, d=4))

# You can evaluate multiple sets of input values with a data frame input:
consume(ep, data.frame(a=1:2, b=3:4, c=5:6, d=7:8))

# or, equivalently, with multiple lists:
consume(ep, list(a=1, b=3, c=5, d=7), list(a=2, b=4, c=6, d=8))

# Remove the service we just published
deleteWebService(ws, "rowSums")

# A more efficient way to do the same thing using data frame input/output:
f <- function(df) with(df, list(sum = a+b+c+d, prod = a*b*c*d))
ep = publishWebService(ws, f, name="rowSums2", 
                       inputSchema = data.frame(a = 0, b = 0, c = 0, d = 0))
consume(ep, data.frame(a=1:2, b=3:4, c=5:6, d=7:8))
deleteWebService(ws, "rowSums2")



# Automatically discover dependencies ----------------------------------------

# The publishWebService function uses `miniCRAN` to include dependencies on
# packages required by your function. The next example uses the `lmer`
# function from the lme4 package, and also shows how to publish a function
# that consumes a data frame by setting data.frame=TRUE.  Note! This example
# depends on a lot of packages and may take some time to upload to Azure.
library(lme4)
# Build a sample mixed effects model on just a subset of the sleepstudy data...
set.seed(1)
m <- lmer(Reaction ~ Days + (Days | Subject), 
          data=sleepstudy[sample(nrow(sleepstudy), 120),])
# Deine a prediction function to publish based on the model:
fun <- function(newdata)
{
  predict(m, newdata=newdata)
}
ep <- publishWebService(ws, fun=fun, name="sleepy lmer",
                        inputSchema= sleepstudy,
                        packages="lme4",
                        data.frame=TRUE)

# OK, try this out, and compare with raw data
ans = consume(ep, sleepstudy)$ans
plot(ans, sleepstudy$Reaction)

# Remove the service
deleteWebService(ws, "sleepy lmer")

## End(Not run)

AzureML documentation built on July 28, 2019, 1:02 a.m.