6.2.2 Manage Scripts in R

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.sriptList(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: `user`, which lists scripts owned by the current user `global`, which lists public scripts, which are visible to all users `grant`, which lists the scripts to which the current user has granted read access to others `granted`, which lists the scripts to which the current user has been granted read access by another user `all`, which lists all of the user, public, and granted scripts

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.sriptLoad(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}