MINI MINI MANI MO
%
% Copyright (c) 2012, 2015, Oracle and/or its affiliates. All rights reserved.
%
% NAME
% ore.doEval.Rd - embedded functions
%
% DESCRIPTION
% Methods for embedded R execution.
%
% NOTES
%
% MODIFIED (MM/DD/YY)
% qinwan 09/24/15 - update FUN argument description
% ffeli 09/03/15 - add INDEX argument descriptions
% qinwan 06/24/15 - add FUN.OWNER argument
% qinwan 05/21/15 - support lob type
% lbzhang 04/10/14 - add control arg ore.envAsEmptyenv
% paboyoun 12/27/13 - add ore.parallel option
% paboyoun 11/19/13 - add ore.na.omit control argument
% paboyoun 05/09/13 - change parallel argument default value
% lzhang 04/26/13 - bug 16587457: add DOP hint in ore.*Apply functions
% demukhin 11/12/12 - add control arguments
% qinwan 11/06/12 - doc R/Package version script
% demukhin 11/02/12 - bug 14539151: document INDEX
% demukhin 09/15/12 - prj: auto connect
%
\name{ore.doEval}
\alias{ore.doEval}
\alias{ore.groupApply}
\alias{ore.indexApply}
\alias{ore.rowApply}
\alias{ore.tableApply}
\title{
Oracle R Enterprise 嵌入式 R 脚本执行函数
}
\description{
在各种情况下运行 Oracle 数据库中的函数。
}
\usage{
ore.doEval(FUN, ..., FUN.VALUE = NULL, FUN.NAME = NULL, FUN.OWNER = NULL)
ore.groupApply(X, INDEX, FUN, ..., FUN.VALUE = NULL,
FUN.NAME = NULL, FUN.OWNER = NULL,
parallel = getOption("ore.parallel", NULL))
ore.indexApply(times, FUN, ..., FUN.VALUE = NULL,
FUN.NAME = NULL, FUN.OWNER = NULL,
parallel = getOption("ore.parallel", NULL))
ore.rowApply(X, FUN, ..., FUN.VALUE = NULL,
FUN.NAME = NULL, FUN.OWNER = NULL, rows = 1,
parallel = getOption("ore.parallel", NULL))
ore.tableApply(X, FUN, ..., FUN.VALUE = NULL,
FUN.NAME = NULL, FUN.OWNER = NULL)
}
\arguments{
\item{X}{
一个 \code{\linkS4class{ore.frame}} 对象。
}
\item{INDEX}{
一个包含 \code{\linkS4class{ore.vector}} 对象或列的
\code{\linkS4class{ore.frame}} 或 \code{\linkS4class{ore.factor}} 对象, 每个对象/列的长度
与参数 \code{X} 相同。它用于首先对
\code{X} 中的数据分区, 然后再发送到函数 \code{FUN}。
副本支持的 R 类型为逻辑, 整数, 数字,
字符, 因子。
}
\item{times}{
要执行函数的次数。
}
\item{FUN}{
要应用的函数。对于函数 \code{ore.groupApply},
\code{ore.rowApply} 和 \code{ore.tableApply}, 第一个参数到
第 \code{FUN} 个参数必须表示一个
\code{\link[base]{data.frame}} 对象。对于函数
\code{ore.indexApply}, 第一个参数到 \code{FUN} 必须
表示索引编号。对于函数 \code{ore.doEval}, \code{FUN}
不需要参数。\code{FUN} 指定的函数
不能递归调用嵌入式 R API。不能
与参数 \code{FUN.NAME} 一起使用。
}
\item{\dots}{
\code{FUN} 的附加参数。
以 \code{ore.} 开头的参数是特殊控制
参数。它们不传递到由 \code{FUN} 或 \code{FUN.NAME}
参数指定的函数, 而是控制在封闭
执行前后发生的情况。支持
以下控制参数:
\\enumerate{
\item \code{ore.drop} - 控制输入数据的对象类型。
如果为 \code{TRUE}, 则将一列 \code{data.frame} 转换为
\code{vector}。默认值为 \code{TRUE}。
\item \code{ore.na.omit} - 控制输入数据中对缺少值的
处理。如果为 \code{TRUE}, 则为行或向量元素,
具体取决于 \code{ore.drop} 设置, 所包含的缺少值
将从输入数据中删除。如果某个块中的所有行
包含缺少值, 则该块的输入数据
将为空 \code{data.frame} 或 \code{vector}。默认值
为 \code{FALSE}。
\item \code{ore.connect} - 控制是否自动连接到
封闭内部的 Oracle R Enterprise。这
等同于使用与客户机会话相同的身份证明
执行 \code{ore.connect} 调用。默认值为
\code{FALSE}。
\item \code{ore.graphics} - 控制是否启动图形
驱动程序并查找图像。默认值为 \code{TRUE}。
\item \code{ore.png.*} - 如果 \code{ore.graphics} 为 \code{TRUE},
则为 \code{\link[grDevices]{png}} 图形设备驱动程序的
附加参数。这些参数的命名惯例
是将 \code{ore.png.} 前缀添加到 \code{\link[grDevices]{png}}
函数的参数。例如, 如果提供了
\code{ore.png.height}, 则参数 \code{height} 将传递到
\code{\link[grDevices]{png}} 函数。如果未设置, 则
将使用 \code{\link[grDevices]{png}} 函数的
标准默认值。
\item \code{ore.envAsEmptyenv} - 控制在串行化期间
是否应将对象中的引用环境替换为
空环境。某些类型的输入参数
和返回的对象 (例如 \code{list}, \code{formula})
先进行串行化, 然后再保存到数据库。如果为 \code{TRUE}, 则
对象中的引用环境将替换为
其父级为 \code{.GlobalEnv} 的空环境,
因此, 原始引用环境中的对象将
不串行化。在某些情况下, 这可能会显著减少
串行化对象的大小。如果为 \code{FALSE}, 则
引用环境中的所有对象将串行化, 并且
可在以后进行反串行化和恢复。默认值
由全局选项 \code{ore.envAsEmptyenv} 控制。
}
}
\item{FUN.VALUE}{
一个 \code{data.frame} 或 \code{\linkS4class{ore.frame}}, 用作
返回值的模板。
属性 \code{ora.type} 可以应用到 \code{data.frame} 列
以指定使用 \code{\linkS4class{ore.frame}} 或 \code{CLOB} 类型的
\code{BLOB} 的对应输出列。
}
\item{FUN.NAME}{
用于指定串行化 \R 脚本名称的字符串,
其中包含一个 \R 函数定义, 在 Oracle R
Enterprise 数据库中 \R 脚本档案内。不能用于
\code{FUN}。
Oracle R Enterprise 提供了多个预定义的图形
脚本。所有预定义的脚本具有以 \code{RQG$} 开头的保留名称,
后跟来自脚本包装的 \\pkg{graphics} 程序包的
函数名。根据函数, 它将接受
输入 \code{\link[base]{data.frame}} 的第一列, 第一列和第二列
或所有列。因此, 预定义脚本只能
用于 \code{ore.tableApply}, \code{ore.groupApply} 或
\code{ore.rowApply}。每个函数还有 \code{...}, 因此它可以
将任意参数传递到其包装的函数。以下为
预定义图形脚本的列表:
\\enumerate{
\item \code{RQG$plot1d} - \code{\link[graphics]{plot}} 的包装。
作用于输入 \code{\link[base]{data.frame}} 对象的
第一列。
\item \code{RQG$plot2d} - \code{\link[graphics]{plot}} 的包装。
作用于输入 \code{\link[base]{data.frame}} 对象的
前两列。
\item \code{RQG$hist} - \code{\link[graphics]{hist}} 的包装。
作用于输入 \code{\link[base]{data.frame}} 对象的
第一列。
\item \code{RQG$boxplot} - \code{\link[graphics]{boxplot}} 的包装。
作用于输入 \code{\link[base]{data.frame}} 对象的
第一列。
\item \code{RQG$smoothScatter} - \code{\link[graphics]{smoothScatter}} 的包装。
作用于输入 \code{\link[base]{data.frame}} 对象的
前两列。
\item \code{RQG$cdplot} - \code{\link[graphics]{cdplot}} 的包装。
作用于输入 \code{\link[base]{data.frame}} 对象的
前两列。
\item \code{RQG$pairs} - \code{\link[graphics]{pairs}} 的包装。
作用于输入 \code{\link[base]{data.frame}} 对象的
所有列。
\item \code{RQG$matplot} - \code{\link[graphics]{matplot}} 的包装。
作用于输入 \code{\link[base]{data.frame}} 对象的
所有列。
}
Oracle R Enterprise 还提供了多个预定义的 \R 和
程序包版本脚本。这些脚本以 \code{RQ$} 开头,
后跟脚本包装的 \R 函数名称, 只能
用于 \code{ore.doEval}。以下为这些预定义脚本
的列表:
\\enumerate{
\item \code{RQ$R.Version} - \code{\link[base]{R.Version}} 的包装。
不接受任何参数, 返回与 \R 版本相关的信息。
\item \code{RQ$getRversion} - \code{\link[base]{getRversion}} 的包装。
不接受任何参数, 返回 \R
版本号。
\item \code{RQ$installed.packages} - \code{\link[utils]{installed.packages}} 的包装。
不接受任何参数,
返回程序包名称, 版本号和已安装程序包的
安装位置。
\item \code{RQ$packageVersion} - \code{\link[utils]{packageVersion}} 的包装。
接受程序包名称作为
参数, 返回程序包版本号。
}
}
\item{FUN.OWNER}{
指定 \code{FUN.NAME} \R 脚本所有者的可选
字符串。使用 \code{\link{ore.scriptCreate}} 创建 \R 脚本的
用户是该脚本的所有者。
\code{RQSYS} 方案是全局和预定义 \R 脚本的所有者。
\code{FUN.OWNER} 未指定或者是 \code{NULL} 时,
Oracle R Enterprise 按照以下顺序查找所有者:
当前会话的用户, \code{RQSYS}。参数 \code{FUN.OWNER}
仅与参数 \code{FUN.NAME} 一起使用。
}
\item{rows}{
每个块中的最大行数。
}
\item{parallel}{
在嵌入式 R 作业中使用的首选并行度;
可以为大于等于 \code{2} 的正整数
(表示特定并行度),
\code{FALSE} 或 \code{1} 的值 (表示无并行度),
\code{TRUE} 的值 (表示 \code{data} 参数的默认
并行度) 或者
\code{NULL} (表示操作的数据库默认值)。
默认值由全局选项
\code{ore.parallel} 控制。
}
}
\details{
函数 \code{ore.doEval} 在运行于 Oracle 数据库
内部的 \R 进程中执行函数
\code{FUN} 或 \code{FUN.NAME}。
函数 \code{ore.groupApply} 按 (可能已派生的) 列对数据库中的
数据集进行分区, 并在运行于 Oracle 数据库
内部的 \R 进程中对这些分区执行函数。每个
分区必须完全在单个 \R 进程内拟合。
函数 \code{ore.indexApply} 在 Oracle 数据库
内部执行函数 \code{index} 次。
函数 \code{ore.rowApply} 将数据库中的数据集按
行块进行分区, 并在运行于 Oracle 数据库内部的 \R 进程中
对这些分区执行函数。每个分区必须
完全在单个 \R 进程内拟合。
函数 \code{ore.tableApply} 对数据库中的数据集
执行函数。
必须提供参数 \code{FUN} 或 \code{FUN.NAME}。
出于安全原因, 使用参数 \code{FUN} 时需要
\\option{RQADMIN} Oracle 数据库权限。由于 \R 脚本
(由参数 \code{FUN.NAME} 表示) 的创建已由具有
\\option{RQADMIN} 身份证明的某人发布, 因此有权使用
Oracle R Enterprise 的任何人均可以使用它。
参数 \code{FUN.OWNER} 可以与参数 \code{FUN.NAME} 一起使用来
唯一指定在 \R 脚本资料档案库中定义的 \R 函数。
\code{parallel} 参数控制添加到底层 SQL 查询中的
\\option{/*+ parallel */}, \\option{/*+ parallel(DOP) */} 或
\\option{/*+ no_parallel */} 提示的使用。
有关详细信息, 请参阅 Oracle 数据库文档。
要应用的函数通过参数 \code{FUN} 指定,
\code{FUN.NAME} 则使用与调用它的客户机会话相同的
身份证明自动连接到 Oracle R Enterprise。
只调用等同的 \code{ore.connect}。
\code{ore.sync}, \code{ore.attach} 和 \code{ore.get} 等函数
应显式调用。
}
\value{
如果提供了参数 \code{FUN.VALUE}, 则将
返回符合 \code{\linkS4class{ore.frame}} 模板的
\code{FUN.VALUE} 对象。
如果未提供参数 \code{FUN.VALUE}, 则函数
\code{ore.doEval} 和 \code{ore.tableApply} 返回
\code{\linkS4class{ore.object}}, 而函数 \code{ore.groupApply},
\code{ore.indexApply} 和 \code{ore.rowApply} 返回
\code{\linkS4class{ore.list}}。
}
\references{
\href{http://www.oracle.com/technetwork/database/database-technologies/r/r-enterprise/documentation/index.html}{Oracle R Enterprise}
}
\author{
Oracle \email{oracle-r-enterprise@oracle.com}
}
\seealso{
\code{\link{ore.scriptCreate}},
\code{\link[OREbase]{ore.options}}
}
\examples{
## ore.doEval
eval1 <- ore.doEval(function() "Hello, world")
eval2 <-
ore.doEval(function()
data.frame(x = "Hello, world", stringsAsFactors = FALSE))
eval3 <-
ore.doEval(function()
data.frame(x = "Hello, world", stringsAsFactors = FALSE),
FUN.VALUE =
data.frame(x = character(), stringsAsFactors = FALSE))
out.df <- data.frame(x = character(), y = raw(), stringsAsFactors = FALSE)
attr(out.df$x, "ora.type") <- "clob"
attr(out.df$y, "ora.type") <- "blob"
eval4 <-
ore.doEval(function() {
res <- data.frame(x = "Hello, world",stringsAsFactors = FALSE)
res$y[[1L]] <- charToRaw("Hello, world")
res},
FUN.VALUE = out.df)
eval1
class(eval1) # ore.object
eval2
class(eval2) # ore.object
eval3
class(eval3) # ore.frame
eval4$x
rawToChar(ore.pull(eval4$y))
## copy data to the database
IRIS <- ore.push(iris)
## ore.groupApply
grpAp1 <-
ore.groupApply(IRIS, IRIS$Species,
function(df)
if(nrow(df) == 0)
NULL
else
summary(lm(Sepal.Length ~ ., data = df[1:4])),
parallel = TRUE)
grpAp2 <-
ore.groupApply(IRIS, IRIS$Species,
function(df) {
if (nrow(df) == 0) {
species <- character()
cf <- numeric()
names(cf) <- character()
} else {
species <- as.character(df$Species[1])
cf <- coef(lm(Sepal.Length ~ .,
data = df[1:4]))
}
data.frame(Species = species,
CoefName = names(cf),
CoefValue = unname(cf),
stringsAsFactors = FALSE)
},
FUN.VALUE =
data.frame(Species = character(),
CoefName = character(),
CoefValue = numeric(),
stringsAsFactors = FALSE),
parallel = TRUE)
class(grpAp1) # ore.list
class(grpAp2) # ore.frame
## ore.indexApply
ore.indexApply(5, function(i) i)
if (interactive())
ore.indexApply(5, function(i) summary(rnorm(100)), parallel = TRUE)
## ore.rowApply
# create a classification tree for iris data
library(rpart)
irisRpart <- rpart(Species ~ ., data = iris)
irisPred <-
ore.rowApply(IRIS,
function(df, model) {
library(rpart)
cbind(df, PRED = predict(model, df, type = "class"))
}, model = irisRpart,
FUN.VALUE =
cbind(iris[integer(),], PRED = character()),
rows = 50, parallel = TRUE)
## ore.tableApply
ore.tableApply(IRIS, function(df) summary(df))
}
\keyword{data}
\keyword{programming}
\keyword{iteration}
\keyword{category}
\keyword{database}
\keyword{ORE}
OHA YOOOO