Skip to content
This repository has been archived by the owner on Oct 28, 2019. It is now read-only.

Commit

Permalink
Rebuild documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
@andrie
andrie committed Nov 9, 2015
1 parent 195c467 commit bab4b31
Show file tree
Hide file tree
Showing 4 changed files with 169 additions and 141 deletions.
142 changes: 80 additions & 62 deletions man/consume.Rd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -9,15 +9,13 @@ consume(endpoint, ..., globalParam, retryDelay = 10, output = "output1")
\arguments{
\item{endpoint}{AzureML Web Service endpoint returned by \code{\link{endpoints}}}

\item{...}{variable number of requests entered as lists in key-value format;
optionally a single data frame argument.}
\item{...}{variable number of requests entered as lists in key-value format; optionally a single data frame argument.}

\item{globalParam}{global parameters entered as a list, default value is an empty list}

\item{retryDelay}{the time in seconds to delay before retrying in case of a server error}

\item{output}{name of the output port to return usually 'output1' or 'output2';
set to NULL to return everything as raw results in JSON-encoded list form}
\item{output}{name of the output port to return usually 'output1' or 'output2'; set to NULL to return everything as raw results in JSON-encoded list form}
}
\value{
data frame containing results returned from web service call
Expand All @@ -27,67 +25,87 @@ Score data represented as lists where each list key represents
a parameter of the web service.
}
\note{
Set \code{...} to a list of key/value pairs corresponding to web service
inputs. Optionally, set \code{...} to a single data frame with columns corresponding
to web service variables. The data frame approach returns output from the evaluation
of each row of the data frame (see the examples).
Set \code{...} to a list of key/value pairs corresponding to web service inputs. Optionally, set \code{...} to a single data frame with columns corresponding to web service variables. The data frame approach returns output from the evaluation of each row of the data frame (see the examples).
}
\examples{
\dontrun{
# Use a default configuration in ~/.azureml, alternatively
# see help for `workspace`.
ws <- workspace()

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


# 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=(expr="getwd()"))$ans)
cat(consume(ep, list=(expr=".packages(all=TRUE)"))$ans)


# 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="lexi",
inputSchema=list(x="numeric"), outputSchema=list(ans="numeric"))
cat(consume(ep, list(x=2))$ans)


# Example showing the use of consume to score all the rows of a data frame
# at once. The columns of the data frame correspond to the input parameters
# of the web service.
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

# Use a default configuration in ~/.azureml, alternatively
# see help for `workspace`.
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))


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


# 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 = "lexi",
inputSchema = list(x = "numeric"),
outputSchema = list(ans = "numeric"))
cat(consume(ep, list(x=2))$ans)


# Example showing the use of consume to score all the rows of a data frame
# at once. The columns of the data frame correspond to the input parameters
# of the web service.
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

}
}
\seealso{
Expand Down
3 changes: 1 addition & 2 deletions man/endpoints.Rd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,8 +16,7 @@ getEndpoints(ws, service_id, endpoint_id,

\item{service_id}{A web service Id, for example returned by \code{\link{services}}.}

\item{endpoint_id}{An optional endpoint id. If supplied, return the endpoint information for just
that id. Leave undefined to return a data.frame of all end points associated with the service.}
\item{endpoint_id}{An optional endpoint id. If supplied, return the endpoint information for just that id. Leave undefined to return a data.frame of all end points associated with the service.}

\item{uri}{The AzureML web services URI}
}
Expand Down
157 changes: 85 additions & 72 deletions man/publishWebService.Rd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -43,8 +43,7 @@ in the web service}
\code{\link{workspace}}.}
}
\value{
A data.frame describing the new service endpoints, cf. \code{\link{endpoints}}. The output
can be directly used by the \code{\link{consume}} function.
A data.frame describing the new service endpoints, cf. \code{\link{endpoints}}. The output can be directly used by the \code{\link{consume}} function.
}
\description{
Publish a function to Microsoft Azure Machine Learning as a web service. The
Expand All @@ -54,79 +53,93 @@ The function to be published is limited to inputs/outputs consisting of
lists of scalar values.
}
\note{
AzureML data types are different than, but related to, R types. You may specify
the R types \code{numeric, logical, integer,} and \code{character} and those will
be specified as AzureML types \code{double, boolean, int32, string}, respectively.

Leave the \code{wsid} parameter undefined to create a new AzureML web service, or
specify the ID of an existing web service to update it, replacing the function
and required R pacakges with new values. Although the API allows that the name,
input and output schema to also be specified when updating it's not possible to
change those values.
The \code{\link{updateWebService}} function is nearly an alias for \code{\link{publishWebService}},
differing only in that the \code{wsid} parameter is required by \code{\link{updateWebService}}.
The \code{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 \code{exports} parameter to explicitly include other objects that
are needed. Use \code{noexport} to explicitlt prevent objects from being exported.
AzureML data types are different than, but related to, R types. You may specify the R types \code{numeric, logical, integer,} and \code{character} and those will be specified as AzureML types \code{double, boolean, int32, string}, respectively.

Leave the \code{wsid} parameter undefined to create a new AzureML web service, or specify the ID of an existing web service to update it, replacing the function and required R pacakges with new values. Although the API allows that the name, input and output schema to also be specified when updating it's not possible to change those values.
The \code{\link{updateWebService}} function is nearly an alias for \code{\link{publishWebService}}, differing only in that the \code{wsid} parameter is required by \code{\link{updateWebService}}.
The \code{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 \code{exports} parameter to explicitly include other objects that are needed. Use \code{noexport} to explicitlt prevent objects from being exported.
}
\examples{
\dontrun{
# Use a default configuration in ~/.azureml, alternatively
# see help for `workspace`.
ws <- workspace()
# Really simple example:
add <- function(x,y) x + y
endpoint <- publishWebService(ws, add, "addme", list(x="numeric", y="numeric"), list(ans="numeric"))
consume(endpoint, list(x=pi, y=2))
# 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=(expr="getwd()"))$ans)
cat(consume(ep, list=(expr=".packages(all=TRUE)"))$ans)
# 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="lexi",
inputSchema=list(x="numeric"), outputSchema=list(ans="numeric"))
cat(consume(ep, list(x=2))$ans)
# Example showing the use of consume to score all the rows of a data frame
# at once. The columns of the data frame correspond to the input parameters
# of the web service.
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
# Use a default configuration in ~/.azureml, alternatively
# see help for `workspace`.
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))
# 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)
# 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 = "lexi",
inputSchema = list(x = "numeric"),
outputSchema = list(ans = "numeric"))
cat(consume(ep, list(x=2))$ans)
# Example showing the use of consume to score all the rows of a data frame
# at once. The columns of the data frame correspond to the input parameters
# of the web service.
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
}
}
\seealso{
Expand Down
8 changes: 3 additions & 5 deletions man/services.Rd
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,11 +13,9 @@ getWebServices(ws, service_id, name,
\arguments{
\item{ws}{An AzureML workspace reference returned by \code{\link{workspace}}.}

\item{service_id}{optional web service id. If supplied, return the web service information for just
the specified service id. Leave undefined to return a data.frame of all services.}
\item{service_id}{optional web service id. If supplied, return the web service information for just the specified service id. Leave undefined to return a data.frame of all services.}

\item{name}{optional web service name. If supplied, return the web service information for services
with matching names. Leave undefined to return all services.}
\item{name}{optional web service name. If supplied, return the web service information for services with matching names. Leave undefined to return all services.}

\item{uri}{the AzureML web services URI}
}
Expand All @@ -43,7 +41,7 @@ The result is cached in the workspace environment similarly to datasets and expe
\examples{
\dontrun{
workspace_id <- "" # Your AzureML workspace id
authorization_token <- "" # Your AsureML authorization token
authorization_token <- "" # Your AzureML authorization token

ws <- workspace(
id = workspace_id,
Expand Down

0 comments on commit bab4b31

Please sign in to comment.