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 - Embedded R-Skriptausführungsfunktionen
}
\description{
Führt eine Funktion innerhalb der Oracle-Datenbank unter unterschiedlichen Bedingungen aus.
}
\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}{
Ein \code{\linkS4class{ore.frame}}-Objekt.
}
\item{INDEX}{
Ein \code{\linkS4class{ore.vector}}- oder \code{\linkS4class{ore.frame}}-Objekt,
das \code{\linkS4class{ore.factor}}-Objekte oder -Spalten enthält, die jeweils gleich
lang sind wie Argument \code{X}. Damit werden die Daten
in \code{X} vor dem Senden an Funktion \code{FUN} partitioniert.
Die unterstützten entsprechenden R-Typen sind "logical", "integer", "numeric",
"character", "factor".
}
\item{times}{
Gibt an, wie oft eine Funktion ausgeführt werden soll.
}
\item{FUN}{
Die anzuwendende Funktion. Für Funktionen \code{ore.groupApply},
\code{ore.rowApply} und \code{ore.tableApply} muss das erste Argument für
das Argument \code{FUN} ein
\code{\link[base]{data.frame}}-Objekt darstellen. Für Funktion
\code{ore.indexApply} muss das erste Argument für \code{FUN}
die Indexzahl darstellen. Bei Funktion \code{ore.doEval} sind
keine Argumente für \code{FUN} erforderlich. Die von
\code{FUN} angegebene Funktion kann eingebettete R-APIs nicht rekursiv aufrufen.
Kann nicht mit Argument \code{FUN.NAME} verwendet werden.
}
\item{\dots}{
Zusätzliche Argumente für \code{FUN}.
Argumente, die mit \code{ore.} beginnen, sind spezielle Steuerargumente.
Sie werden nicht an die durch die Argumente
\code{FUN} oder \code{FUN.NAME} angegebene Funktion übergeben, sondern steuern
das Verhalten vor bzw. nach Ausführung der Schließung. Folgende
Steuerargumente werden unterstützt:
\\enumerate{
\item \code{ore.drop} - Steuert den Objekttyp für die Eingabe-
daten. Bei \code{TRUE} wird eine Spalte \code{data.frame} in
\code{vector} konvertiert. Der Standardwert ist \code{TRUE}.
\item \code{ore.na.omit} - Steuert den Umgang mit fehlenden Werten
in den Eingabedaten. Wenn \code{TRUE}, werden Zeilen oder Vektorelemente
mit fehlenden Werten, je nach \code{ore.drop}-Einstellung,
aus den Eingabedaten entfernt. Wenn alle Zeilen in einem
Chunk fehlende Werte enthalten, sind die Eingabedaten für dieses Chunk
in \code{data.frame} oder \code{vector} leer. Der Standardwert
ist \code{FALSE}.
\item \code{ore.connect} - Steuert, ob innerhalb der Schließung automatisch
eine Verbindung zu Oracle R Enterprise hergestellt werden soll. Dies
entspricht einem \code{ore.connect}-Aufruf mit denselben
Zugangsdaten wie für die Clientsession. Der Standardwert ist
\code{FALSE}.
\item \code{ore.graphics} - Steuert, ob ein Grafiktreiber gestartet
und nach Bildern gesucht werden soll. Der Standardwert ist \code{TRUE}.
\item \code{ore.png.*} - Wenn \code{ore.graphics} \code{TRUE} ist,
zusätzliche Parameter für den \code{\link[grDevices]{png}}-
Grafikgerätetreiber. Die Benennung dieser Argumente erfolgt
üblicherweise über das Hinzufügen eines \code{ore.png.}-Präfix zu den Argumenten der
\code{\link[grDevices]{png}}-Funktion. Beispiel: Bei Angabe von
\code{ore.png.height} wird das Argument \code{height} an die
\code{\link[grDevices]{png}}-Funktion übergeben. Fehlt die Angabe,
werden die Standardwerte für die \code{\link[grDevices]{png}}-
Funktion verwendet.
\item \code{ore.envAsEmptyenv} - Steuert, ob die referenzierten Umgebungen
in einem Objekt bei der Serialisierung durch eine leere
Umgebung ersetzt werden sollen. Einige Typen von Eingabeparametern
und Rückgabeobjekten, wie \code{list}, \code{formula}, werden
serialisiert, bevor sie in der Datenbank gespeichert werden. Wenn \code{TRUE},
wird die referenzierte Umgebung im Objekt durch eine
leere Umgebung ersetzt, deren übergeordnetes Objekt \code{.GlobalEnv} ist. Daher
werden die Objekte in der ursprünglich referenzierten Umgebung
nicht serialisiert. In einigen Situationen könnte die Größe der serialisierten
Objekte dadurch erheblich verringert werden. Wenn \code{FALSE}, werden
alle Objekte in der referenzierten Umgebung serialisiert und könnten später
deserialisiert und wiederhergestellt werden. Der Standardwert wird
von der globalen Option \code{ore.envAsEmptyenv} gesteuert.
}
}
\item{FUN.VALUE}{
Ein Wert \code{data.frame} oder \code{\linkS4class{ore.frame}}, der als
Vorlage für den Rückgabewert verwendet werden soll.
Das Attribut \code{ora.type} kann auf Spalte \code{data.frame} angewendet werden,
um anzugeben, dass die entsprechende Ausgabespalte von
\code{\linkS4class{ore.frame}} den Typ \code{CLOB} oder \code{BLOB} verwendet.
}
\item{FUN.NAME}{
Eine Zeichenfolge, die den Namen des serialisierten \R-Skripts angibt,
das eine einzelne \R-Funktionsdefinition innerhalb des datenbankinternen
\R-Skriptarchivs von Oracle R Enterprise enthält. Kann nicht mit
\code{FUN} verwendet werden.
Oracle R Enterprise enthält eine Reihe von vordefinierten grafischen Skripten. Alle
vordefinierten Skripte haben einen reservierten Namen, der mit \code{RQG$} beginnt,
gefolgt von einem Funktionsnamen aus dem \\pkg{graphics}-Package, das das
Skript umschließt. Je nach Funktion werden die erste, die erste und zweite
oder alle Spalten der Eingabe \code{\link[base]{data.frame}} verwendet.
Somit können vordefinierte Skripte nur mit
\code{ore.tableApply}, \code{ore.groupApply} oder \code{ore.rowApply} verwendet werden.
Jede Funktion verfügt außerdem über \code{...}, sodass jeder Parameter an
die Funktion übergeben werden kann, die er umschließt. Im Folgenden finden Sie
eine Liste der vordefinierten grafischen Skripte:
\\enumerate{
\item \code{RQG$plot1d} - Ein Wrapper für \code{\link[graphics]{plot}}.
Bearbeitet die erste Spalte des
\code{\link[base]{data.frame}}-Eingabeobjekts.
\item \code{RQG$plot2d} - Ein Wrapper für \code{\link[graphics]{plot}}.
Bearbeitet die ersten beiden Spalten des
\code{\link[base]{data.frame}}-Eingabeobjekts.
\item \code{RQG$hist} - Ein Wrapper für \code{\link[graphics]{hist}}.
Bearbeitet die erste Spalte des
\code{\link[base]{data.frame}}-Eingabeobjekts.
\item \code{RQG$boxplot} - Ein Wrapper für \code{\link[graphics]{boxplot}}.
Bearbeitet die erste Spalte des
\code{\link[base]{data.frame}}-Eingabeobjekts.
\item \code{RQG$smoothScatter} - Ein Wrapper für
\code{\link[graphics]{smoothScatter}}. Bearbeitet die ersten beiden
Spalten des \code{\link[base]{data.frame}}-Eingabeobjekts.
\item \code{RQG$cdplot} - Ein Wrapper für \code{\link[graphics]{cdplot}}.
Bearbeitet die ersten beiden Spalten des
\code{\link[base]{data.frame}}-Eingabeobjekts.
\item \code{RQG$pairs} - Ein Wrapper für \code{\link[graphics]{pairs}}.
Bearbeitet alle Spalten des
\code{\link[base]{data.frame}}-Eingabeobjekts.
\item \code{RQG$matplot} - Ein Wrapper für \code{\link[graphics]{matplot}}.
Bearbeitet alle Spalten des
\code{\link[base]{data.frame}}-Eingabeobjekts.
}
Oracle R Enterprise wird auch mit einer Reihe von vordefinierten \R- und Package-
Versionsskripten geliefert. Diese Skripte beginnen mit \code{RQ$} gefolgt von einem
\R-Funktionsnamen, den das Skript umschließt, und kann nur mit
\code{ore.doEval} verwendet werden. Im Folgenden finden Sie eine Liste dieser vordefinierten Skripte:
\\enumerate{
\item \code{RQ$R.Version} - Ein Wrapper für \code{\link[base]{R.Version}}.
Verwendet kein Argument und gibt für die \R-Version relevante Informationen zurück.
\item \code{RQ$getRversion} - Ein Wrapper für
\code{\link[base]{getRversion}}. Verwendet kein Argument und gibt \R-
Versionsnummer zurück.
\item \code{RQ$installed.packages} - Ein Wrapper für
\code{\link[utils]{installed.packages}}. Verwendet kein Argument und gibt
Packagename, Versionsnummer und Packageinstallations-
verzeichnis der installierten Packages zurück.
\item \code{RQ$packageVersion} - Ein Wrapper für
\code{\link[utils]{packageVersion}}. Verwendet den Packagenamen als
Argument und gibt die Packageversionsnummer zurück.
}
}
\item{FUN.OWNER}{
Eine optionale Zeichenfolge, die den Eigentümer des \R-Skripts \code{FUN.NAME}
angibt. Der Benutzer, der ein \R-Skript mit \code{\link{ore.scriptCreate}} erstellt,
ist der Eigentümer des Skripts. Das Schema \code{RQSYS}
ist der Eigentümer der globalen und vordefinierten \R-Skripte.
Wenn \code{FUN.OWNER} nicht angegeben wird oder \code{NULL} ist, sucht
Oracle R Enterprise in folgender Reihenfolge nach dem Eigentümer:
Benutzer der aktuellen Session, \code{RQSYS}. Argument \code{FUN.OWNER}
wird nur mit Argument \code{FUN.NAME} verwendet.
}
\item{rows}{
Die Höchstanzahl von Zeilen in jedem Chunk.
}
\item{parallel}{
Ein bevorzugter Parallelitätsgrad, der in dem Embedded R-Job verwendet werden soll;
entweder eine positive Ganzzahl größer als oder gleich \code{2} bei einem
bestimmten Parallelitätsgrad,
ein Wert von \code{FALSE} oder \code{1} bei keiner Parallelität,
ein Wert von \code{TRUE} bei der Standardparallelität des \code{data}-Arguments
oder
\code{NULL} bei dem Datenbankstandardwert für den Vorgang.
Der Standardwert wird von der globalen Option
\code{ore.parallel} reguliert.
}
}
\details{
Funktion \code{ore.doEval} führt entweder die Funktion \code{FUN} oder \code{FUN.NAME} innerhalb
eines \R-Prozesses aus, der in der Oracle-Datenbank ausgeführt wird.
Funktion \code{ore.groupApply} partitioniert ein datenbankinternes Dataset nach einer
(potenziell abgeleiteten) Spalte und führt eine Funktion bei diesen
Partitionen innerhalb der \R-Prozesse aus, die in der Oracle-Datenbank
ausgeführt werden. Jede Partition muss ganz in einen einzelnen \R-Prozess
passen. Funktion \code{ore.indexApply} führt eine Funktion \code{index}-mal in der Oracle-Datenbank aus.
Funktion \code{ore.rowApply} partitioniert ein datenbankinternes Dataset in
Zeilen-Chunks und führt bei diesen Partitionen eine Funktion innerhalb
der \R-Prozesse aus, die in der Oracle-Datenbank ausgeführt werden.
Jede Partition muss ganz in einen einzelnen \R-Prozess passen.
Funktion \code{ore.tableApply} führt eine Funktion bei einem datenbankinternen
Dataset aus.
Es muss entweder Argument \code{FUN} oder \code{FUN.NAME} bereitgestellt werden.
Aus Sicherheitsgründen sind für die Verwendung von Argument \code{FUN}
die Oracle Database-Berechtigungen \\option{RQADMIN} erforderlich. Da die
Erstellung des \R-Skriptes, das von Argument \code{FUN.NAME} dargestellt wird, von einer
Person mit \\option{RQADMIN}-Zugangsdaten veröffentlicht werden muss,
kann es von jeder Person verwendet werden, die zur Verwendung von Oracle R Enterprise
berechtigt ist.
Argument \code{FUN.OWNER} kann mit Argument \code{FUN.NAME} verwendet werden,
um eine im \R-Skript-Repository definierte \R-Funktion eindeutig anzugeben.
Das Argument \code{parallel} steuert die Verwendung eines Hinweises
\\option{/*+ parallel */}, \\option{/*+ parallel(DOP) */} oder
\\option{/*+ no_parallel */}, der der zugrunde liegenden SQL-Abfrage
hinzugefügt wird. Weitere Informationen finden Sie in der Oracle Database-Dokumentation.
Die anzuwendende Funktion, die über Argument \code{FUN}
oder \code{FUN.NAME} angegeben wird, wird automatisch mit denselben Zugangsdaten
wie die aufrufende Clientsession bei Oracle R Enterprise angemeldet.
Nur ein Äquivalent von \code{ore.connect} wird aufgerufen.
Funktionen wie \code{ore.sync}, \code{ore.attach} und \code{ore.get} müssen
explizit aufgerufen werden.
}
\value{
Wenn Argument \code{FUN.VALUE} bereitgestellt wird, wird ein
\code{\linkS4class{ore.frame}}-Objekt zurückgegeben, das der
\code{FUN.VALUE}-Vorlage entspricht.
Wenn Argument \code{FUN.VALUE} nicht bereitgestellt wird, geben die Funktionen
\code{ore.doEval} und \code{ore.tableApply} ein
\code{\linkS4class{ore.object}} zurück, während die Funktionen \code{ore.groupApply},
\code{ore.indexApply} und \code{ore.rowApply} ein
\code{\linkS4class{ore.list}} zurückgeben.
}
\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