Embedded R execution functions can invoke R functions that are stored as scripts in the Oracle R Enterprise R script repository. You can use the R functions described in this topic to create and manage scripts.
As mentioned in "Input Function to Execute," the embedded R execution functions can take a FUN.NAME
argument. That argument specifies the name of a script in the Oracle R Enterprise R script repository. Scripts in the R script repository are also available through the SQL API for embedded R execution.
The R functions for managing scripts are the following:
ore.grant
ore.revoke
ore.scriptCreate
ore.scriptList
ore.scriptLoad
ore.scriptDrop
These functions are described in the following sections:
For an example that uses these functions, see Example 6-5.
Adding a Script
To add an R function as a script in the Oracle R Enterprise R script repository, use the ore.createScript
function. To evoke this function, you must have the RQADMIN role. The ore.createScript
function has the following syntax:
ore.scriptCreate(name, FUN, global, overwrite)
The arguments are the following:
Argument | Description |
---|---|
name |
A name for the script in the Oracle R Enterprise R script repository. |
fun |
An R function. |
global |
A logical value that indicates whether the script is public (global) or private. FALSE (the default) specifies that the script is not public and is visible only to the owner or to users to whom the owner has granted read privilege access; TRUE specifies that the script is public and therefore visible to all users. |
overwrite |
A logical value that indicates whether to replace the R function of the script with the function specified in by the fun argument. TRUE specifies replacing the function, if it exists; FALSE (the default) specifies that the existing contents cannot be replaced. |
If overwrite = FALSE
, an error condition occurs if a script by the same name already exists in the R script repository; otherwise, ore.scriptCreate
returns NULL
.
Granting or Revoking Read Access to a Script
The creator of a script can use the ore.grant
function to grant read access privilege to the script and the ore.revoke
function to revoke that access. Those functions have the following syntax:
ore.grant(name, type = "rqscript", user) ore.revoke(name, type = "rqscript", user)
The arguments are the following:
Argument | Description |
---|---|
name |
The name of a script in the Oracle R Enterprise R script repository. |
type |
For a script, the type is rqscript. |
user |
The user to whom to grant or revoke read privilege access. |
The name
and type
arguments are required. If argument user
is not specified, then read privilege access is granted to or revoked from all users.
An error occurs when one of the following is true:
The named script is not in the R script repository.
The type
argument is not specified.
The user is not found.
The read privilege has already been granted to or revoked from the user.
The named script is public.
Listing the Available Scripts
To list the scripts available to you, use ore.scriptList
. You can list scripts by name, by a pattern, or by type. If you have the RQADMIN role, you can list system scripts, as well. The function has the following syntax:
ore.scriptList(name, pattern, type)
The arguments are the following:
Argument | Description |
---|---|
name |
The name of a script in the Oracle R Enterprise R script repository. Cannot be used when argument pattern is specified. |
pattern |
A regular expression pattern. Scripts that match the pattern are listed. Cannot be used when argument name is specified. |
type |
The type of the script, which can be one of the following:
|
The ore.scriptList
function returns a data.frame
that contains the names of the scripts in the R script repository and the function in the script.
Loading a Script into an R Environment
To load the R function of a script into an R environment, use ore.scriptLoad
, which has the following syntax:
ore.scriptLoad(name, owner, newname, envir)
The arguments are the following:
Argument | Description |
---|---|
name |
The name of a script in the Oracle R Enterprise R script repository. |
owner |
The owner of the script. |
newname |
A new function name in which to load the script. |
envir |
The R environment in which to load the script. |
Specifying the owner of a script is useful when access to the script has been granted to the user who is invoking ore.scriptLoad
.
Specifying a new function name is useful when the name of the script in the Oracle R Enterprise R script repository is not a valid R function name.
An error occurs when one of the following is true:
The script is not in the R script repository.
The current user does not have read access to the script.
The function specified by the name
argument is not a valid R function name.
The newname
argument is not a valid R function name.
Dropping a Script
To remove a script from the Oracle R Enterprise R script repository, use the ore.scriptDrop
function. To invoke this function, you must have the RQADMIN role. The ore.scriptDrop
function has the following syntax:
ore.scriptDrop(name, global, silent)
The arguments are the following:
Argument | Description |
---|---|
name |
A name for the script in the Oracle R Enterprise R script repository. |
global |
A logical value that indicates whether the script is global (public) or private. TRUE specifies dropping a global script; FALSE (the default) specifies dropping a script owned by the current user. |
silent |
A logical value that indicates whether to display an error message if ore.scriptDrop encounters an error condition. TRUE specifies the display of error messages; FALSE (the default) specifies no display. |
An error condition occurs when one of the following is true:
The script is not in the R script repository.
If global = TRUE
, the script is a private script.
If global = FALSE
, the script is a public script.
If successful, ore.scriptDrop
returns NULL
.
Example 6-5 Using the R Script Management Functions
# Create an ore.frame object from the data.frame for the iris data set. IRIS <- ore.push(iris) # Create a private R script for the current user. ore.scriptCreate("myRandomRedDots", function(divisor = 100){ id <- 1:10 plot(1:100, rnorm(100), pch = 21, bg = "red", cex = 2 ) data.frame(id = id, val = id / divisor) }) # Create another private R script. ore.scriptCreate("MYLM", function(data, formula, ...) lm(formula, data, ...)) # Create a public script, available to any user. ore.scriptCreate("GLBGLM", function(data, formula, ...) glm(formula = formula, data = data, ...), global = TRUE) # List only my private scripts. ore.scriptList() # List my private scripts and the public scripts. ore.scriptList(type = "all") # List my private scripts that have the specified pattern. ore.scriptList(pattern = "MY") # Grant read access to a private script to all users. ore.grant("MYLM", type = "rqscript") # Grant read access to a private script to a specific user. ore.grant("myRandomRedDots", user = "SCOTT", type = "rqscript") # List the granted scripts. ore.scriptList(type = "grant") # Use the MYLM script in an embedded R execution function. ore.tableApply(IRIS[1:4], FUN.NAME = "MYLM", formula = Sepal.Length ~ .) # Use the GLBGLM script in an embedded R execution function. ore.tableApply(IRIS[1:4], FUN.NAME = "GLBGLM", formula = Sepal.Length ~ .) # Load an R script to an R function object ore.scriptLoad(name = "MYLM") # Invoke the function. MYLM(iris, formula = Sepal.Length ~ .) # Load another R script to an R function object ore.scriptLoad(name = "GLBGLM", newname = "MYGLM") # Invoke the function. MYGLM(iris, formula = Sepal.Length ~ .) # Drop some scripts. ore.scriptDrop("MYLM") ore.scriptDrop("GLBGLM", global = TRUE) # List all scripts. ore.scriptList(type = "all")Listing for Example 6-5
R> # Create an ore.frame object from the data.frame for the iris data set. R> IRIS <- ore.push(iris) R> R> # Create a private R script for the current user. R> ore.scriptCreate("myRandomRedDots", function(divisor = 100){ + id <- 1:10 + plot(1:100, rnorm(100), pch = 21, bg = "red", cex = 2 ) + data.frame(id = id, val = id / divisor) + }) R> R> # Create another private R script. R> ore.scriptCreate("MYLM", + function(data, formula, ...) lm(formula, data, ...)) R> R> # Create a public script, available to any user. R> ore.scriptCreate("GLBGLM", + function(data, formula, ...) + glm(formula = formula, data = data, ...), + global = TRUE) R> R> # List only my private scripts. R> ore.scriptList() NAME SCRIPT 1 MYLM function (data, formula, ...) \nlm(formula, data, ...) 2 myRandomRedDots function (divisor = 100) \n{\n id & lt\n -1:10\n plot(1:100, rnorm(100), pch = 21, bg = "red", cex = 2)\n data.frame(id = id, val = id/divisor)\n} R> R> # List my private scripts and the public scripts. R> ore.scriptList(type = "all") OWNER NAME SCRIPT 1 RQSYS GLBGLM function (data, formula, ...) \nglm(formula = formula, data = data, ...) 2 RQUSER MYLM function (data, formula, ...) \nlm(formula, data, ...) 3 RQUSER myRandomRedDots function (divisor = 100) \n{\n id & lt\n -1:10\n plot(1:100, rnorm(100), pch = 21, bg = "red", cex = 2)\n data.frame(id = id, val = id/divisor)\n} R> R> # List my private scripts that have the specified pattern. R> ore.scriptList(pattern = "MY") NAME SCRIPT 1 MYLM function (data, formula, ...) \nlm(formula, data, ...) R> R> # Grant read access to a private script to all users. R> ore.grant("MYLM", type = "rqscript") R> R> # Grant read access to a private script to a specific user. R> ore.grant("myRandomRedDots", user = "SCOTT", type = "rqscript") R> R> # List the granted scripts. R> ore.scriptList(type = "grant") NAME GRANTEE 1 MYLM PUBLIC 2 myRandomRedDots SCOTT R> R> # Use the MYLM script in an embedded R execution function. R> ore.tableApply(IRIS[1:4], FUN.NAME = "MYLM", + formula = Sepal.Length ~ .) Call: lm(formula = formula, data = data) Coefficients: (Intercept) Sepal.Width Petal.Length Petal.Width 1.8560 0.6508 0.7091 -0.5565 R> R> # Use the GLBGLM script in an embedded R execution function. R> ore.tableApply(IRIS[1:4], FUN.NAME = "GLBGLM", + formula = Sepal.Length ~ .) Call: glm(formula = formula, data = data) Coefficients: (Intercept) Sepal.Width Petal.Length Petal.Width 1.8560 0.6508 0.7091 -0.5565 Degrees of Freedom: 149 Total (i.e. Null); 146 Residual Null Deviance: 102.2 Residual Deviance: 14.45 AIC: 84.64 R> R> # Load an R script to an R function object R> ore.scriptLoad(name="MYLM") R> R> # Invoke the function. R> MYLM(iris, formula = Sepal.Length ~ .) R> R> # Load another R script to an R function object R> ore.scriptLoad(name = "GLBGLM", newname = "MYGLM") R> R> # Invoke the function. R> MYGLM(iris, formula = Sepal.Length ~ .) R> R> # Drop some scripts. R> ore.scriptDrop("MYLM") R> ore.scriptDrop("GLBGLM", global = TRUE) R> R> # List all scripts. R> ore.scriptList(type = "all") OWNER NAME SCRIPT RQUSER myRandomRedDots function (divisor = 100) \n{\n id & lt\n -1:10\n plot(1:100, rnorm(100), pch = 21, bg = "red", cex = 2)\n data.frame(id = id, val = id/divisor)\n}
See Also:
"Using the ore.doEval Function" for examples that use the myRandomRedDots
script
Example 6-14 for another example of using ore.scriptCreate
and ore.scriptDrop