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{
Funzioni di esecuzione script R di Oracle R Enterprise incorporate
}
\description{
Esegue una funzione all'interno del database Oracle in varie condizioni.
}
\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}{
Oggetto \code{\linkS4class{ore.frame}}.
}
\item{INDEX}{
Oggetto \code{\linkS4class{ore.vector}} o \code{\linkS4class{ore.frame}} che
contiene oggetti o colonne \code{\linkS4class{ore.factor}}. Ognuno di tali elementi ha
la stessa lunghezza dell'argomento \code{X}. Viene usato per il
partizionamento dei dati in \code{X} prima dell'invio alla funzione \code{FUN}.
I tipi R supportati corrispondenti sono logical, integer, numeric,
character, factor.
}
\item{times}{
Numero di esecuzioni della funzione.
}
\item{FUN}{
La funzione da applicare. Per le funzioni \code{ore.groupApply},
\code{ore.rowApply} e \code{ore.tableApply}, gli argomenti dal primo argomento
all'argomento \code{FUN} devono rappresentare un oggetto
\code{\link[base]{data.frame}}. Per la funzione \code{ore.indexApply}, gli argomenti dal primo
argomento all'argomento \code{FUN} devono rappresentare
il numero di indice. Per la funzione \code{ore.doEval} non sono richiesti
argomenti per \code{FUN}. La funzione specificata da \code{FUN} non
può richiamare in modo ricorsivo le interfacce API R incorporate.
Non può essere utilizzata con l'argomento \code{FUN.NAME}.
}
\item{\dots}{
Argomenti aggiuntivi per \code{FUN}.
Gli argomenti che iniziano con \code{ore.} sono argomenti di controllo
speciali, che non vengono passati alla funzione specificata dagli
argomenti \code{FUN} o \code{FUN.NAME}, ma controllano gli eventi che si verificano
prima o dopo l'esecuzione della chiusura.
Sono supportati gli argomenti di controllo riportati di seguito.
\\enumerate{
\item \code{ore.drop}: controlla il tipo di oggetto per i dati di input.
Se \code{TRUE}, un oggetto \code{data.frame} a colonna singola verrà
convertito in \code{vector}. Il valore predefinito è \code{TRUE}.
\item \code{ore.na.omit}: controlla la gestione dei valori mancanti nei
dati di input. Se \code{TRUE}, le righe o gli elementi di vettore
con valori mancanti, a seconda dell'impostazione di \code{ore.drop},
verranno rimossi dai dati di input. Se la mancanza dei valori
interessa tutte le righe di un chunk, i dati di input corrispondenti
saranno un elemento \code{data.frame} o \code{vector} vuoto. Il valore predefinito
è \code{FALSE}.
\item \code{ore.connect}: controlla se stabilire in modo automatico la
connessione a Oracle R Enterprise nella fase di chiusura. Equivale
all'esecuzione di una chiamata \code{ore.connect} con le stesse credenziali
della sessione client. Il valore predefinito è \code{FALSE}.
\item \code{ore.graphics}: controlla se avviare un driver grafico e cercare
le immagini. Il valore predefinito è \code{TRUE}.
\item \code{ore.png.*}: se \code{ore.graphics} è \code{TRUE}, parametri aggiuntivi
per il driver di dispositivo di grafica \code{\link[grDevices]{png}}.
La convenzione di denominazione per questi argomenti
prevede l'aggiunta di un prefisso \code{ore.png.} agli argomenti
della funzione \code{\link[grDevices]{png}}. Ad esempio, se viene fornito
\code{ore.png.height}, verrà passato l'argomento \code{height} alla
funzione \code{\link[grDevices]{png}}. In assenza di un'impostazione
specifica, verranno usati i valori predefiniti standard
della funzione \code{\link[grDevices]{png}}.
\item \code{ore.envAsEmptyenv}: controlla se gli ambienti cui si fa riferimento
in un oggetto devono essere sostituiti con un ambiente
vuoto durante la serializzazione. Alcuni tipi di parametri
di input ed oggetti restituiti, come \code{list}, \code{formula}, vengono
serializzati prima del salvataggio nel database. Se \code{TRUE},
l'ambente cui si fa riferimento nell'oggetto verrà sostituito
con un ambiente vuoto il cui padre è \code{.GlobalEnv} e, pertanto,
gli oggetti nell'ambiente cui si fa riferimento originale non
verranno serializzati. In alcune situazioni, ciò può ridurre
in modo significativo la dimensione degli oggetti serializzati.
Se \code{FALSE}, tutti gli oggetti nell'ambiente cui si fa riferimento verranno
serializzati e in seguito sarà possibile annullarne la serializzazione e
recuperarli. Il valore predefinito è regolato dall'opzione globale \code{ore.envAsEmptyenv}.
}
}
\item{FUN.VALUE}{
\code{data.frame} o \code{\linkS4class{ore.frame}} da usare come
modello per il valore restituito.
L'attributo \code{ora.type} può essere applicato a una colonna \code{data.frame}
per specificare che la colonna di output corrispondente di
\code{\linkS4class{ore.frame}} utilizza un tipo \code{CLOB} o \code{BLOB}.
}
\item{FUN.NAME}{
Stringa di caratteri che specifica il nome di uno script \R serializzato,
che contiene una sola definizione di funzione \R, nell'archivio degli
script \R del database Oracle R Enterprise. Non può essere usata
con \code{FUN}.
In Oracle R Enterprise sono disponibili numerosi script grafici predefiniti.
Tutti gli script predefiniti hanno un nome riservato che inizia con \code{RQG$}
seguito da un nome funzione del package \\pkg{graphics} sottoposto
a wrapping dallo script. A seconda della funzione, vengono assunte la
prima, la prima e la seconda o tutte le colonne dell'oggetto \code{\link[base]{data.frame}} di
input, pertanto gli script predefiniti possono essere utilizzati soltanto
con \code{ore.tableApply}, \code{ore.groupApply} o \code{ore.rowApply}.
Ogni funzione dispone inoltre di \code{...} in modo da poter passare qualsiasi
parametro alla funzione sottoposta a wrapping. Di seguito viene riportata
la lista degli script grafici predefiniti.
\\enumerate{
\item \code{RQG$plot1d}: wrapper per \code{\link[graphics]{plot}}.
Agisce sulla prima colonna dell'oggetto
\code{\link[base]{data.frame}} di input.
\item \code{RQG$plot2d}: wrapper per \code{\link[graphics]{plot}}.
Agisce sulle prime due colonne dell'oggetto
\code{\link[base]{data.frame}} di input.
\item \code{RQG$hist}: wrapper per \code{\link[graphics]{hist}}.
Agisce sulla prima colonna dell'oggetto
\code{\link[base]{data.frame}} di input.
\item \code{RQG$boxplot}: wrapper per \code{\link[graphics]{boxplot}}.
Agisce sulla prima colonna dell'oggetto
\code{\link[base]{data.frame}} di input.
\item \code{RQG$smoothScatter}: wrapper per
\code{\link[graphics]{smoothScatter}}. Agisce sulle prime due
colonne dell'oggetto \code{\link[base]{data.frame}} di input.
\item \code{RQG$cdplot}: wrapper per \code{\link[graphics]{cdplot}}.
Agisce sulle prime due colonne dell'oggetto
\code{\link[base]{data.frame}} di input.
\item \code{RQG$pairs}: wrapper per \code{\link[graphics]{pairs}}.
Agisce su tutte le colonne dell'oggetto
\code{\link[base]{data.frame}} di input.
\item \code{RQG$matplot}: wrapper per \code{\link[graphics]{matplot}}.
Agisce su tutte le colonne dell'oggetto
\code{\link[base]{data.frame}} di input.
}
In Oracle R Enterprise sono inoltre disponibili numerosi script predefiniti per
la versione di \R e package. Questi script iniziano con \code{RQ$} seguito dal
nome della funzione \R sottoposta a wrapping e possono essere usati solo
con \code{ore.doEval}. Di seguito viene riportata la lista di questi script predefiniti.
\\enumerate{
\item \code{RQ$R.Version}: wrapper per \code{\link[base]{R.Version}}.
Non assume argomenti e restituisce le informazioni pertinenti sulla versione di \R.
\item \code{RQ$getRversion}: wrapper per
\code{\link[base]{getRversion}}. Non assume argomenti e restituisce il numero della
versione di \R.
\item \code{RQ$installed.packages}: wrapper per
\code{\link[utils]{installed.packages}}. Non assume argomenti e
restituisce il nome del package, il numero di versione e la posizione di
installazione dei package installati.
\item \code{RQ$packageVersion}: wrapper per
\code{\link[utils]{packageVersion}}. Assume come argomento il nome del package
e restituisce il numero di versione del package.
}
}
\item{FUN.OWNER}{
Stringa di caratteri facoltativa che specifica il proprietario dello
script \R \code{FUN.NAME}. L'utente che crea uno script \R con
\code{\link{ore.scriptCreate}} è il proprietario dello script. Lo schema
\code{RQSYS} è il proprietario degli script \R globali e predefiniti.
Quando \code{FUN.OWNER} non è specificato o è \code{NULL}, Oracle R
Enterprise cerca il proprietario usando l'ordine seguente:
utente della sessione corrente, \code{RQSYS}. L'argomento \code{FUN.OWNER}
viene usato solo con l'argomento \code{FUN.NAME}.
}
\item{rows}{
Numero massimo di righe in ogni chunk.
}
\item{parallel}{
Il grado di parallelismo preferenziale da usare nel job R incorporato:
un numero intero positivo maggiore o uguale a \code{2} per un
grado di parallelismo specifico,
il valore \code{FALSE} o \code{1} per indicare nessun parallelismo,
il valore \code{TRUE} per il parallelismo predefinito dell'argomento
\code{data} oppure
\code{NULL} per l'impostazione predefinita del database per l'operazione.
Il valore predefinito è regolato dall'opzione globale
\code{ore.parallel}.
}
}
\details{
La funzione \code{ore.doEval} esegue una funzione, \code{FUN} o
\code{FUN.NAME}, all'interno di un processo \R in esecuzione nel database Oracle.
La funzione \code{ore.groupApply} esegue la partizione di un data set nel database in
base a una colonna (potenzialmente derivata) ed esegue una funzione
sulle partizioni ottenute all'interno dei processi \R in esecuzione nel
database Oracle. Ogni partizione deve adattarsi completamente in un
singolo processo \R. La funzione \code{ore.indexApply} esegue una funzione \code{index} per un
determinato numero di volte nel database Oracle.
La funzione \code{ore.rowApply} esegue la partizione di un data set nel database in
chunk di righe ed esegue una funzione sulle partizioni ottenute all'interno
dei processi \R in esecuzione nel database Oracle. Ogni partizione deve
adattarsi completamente in un singolo processo \R.
La funzione \code{ore.tableApply} esegue una funzione su un data set
presente nel database.
È necessario fornire l'argomento \code{FUN} o \code{FUN.NAME}. Per motivi
di sicurezza, l'uso dell'argomento \code{FUN} richiede i privilegi
\\option{RQADMIN} del database Oracle. Poiché la creazione
dello script \R rappresentato dall'argomento \code{FUN.NAME} deve essere
pubblicata da un utente con credenziali \\option{RQADMIN}, ne è
consentito l'uso a qualsiasi utente autorizzato a usare Oracle R Enterprise.
L'argomento \code{FUN.OWNER} può essere usato con l'argomento \code{FUN.NAME} per specificare
in modo univoco una funzione \R definita nel repository degli script \R.
L'argomento \code{parallel} regola l'uso di un suggerimento
\\option{/*+ parallel */}, \\option{/*+ parallel(DOP) */} o
\\option{/*+ no_parallel */} aggiunto alla query SQL di base.
Vedere la documentazione del database Oracle per ulteriori informazioni.
La funzione da applicare specificata tramite l'argomento \code{FUN} o
\code{FUN.NAME} viene connessa in modo automatico a Oracle R Enterprise
con le stesse credenziali della sessione client che la richiama.
Viene richiamato solo un equivalente di \code{ore.connect}.
Le funzioni \code{ore.sync}, \code{ore.attach} e \code{ore.get} devono essere chiamate
in modo esplicito.
}
\value{
Se l'argomento \code{FUN.VALUE} viene fornito, viene
restituito un oggetto \code{\linkS4class{ore.frame}} conforme al
modello \code{FUN.VALUE}.
Se l'argomento \code{FUN.VALUE} non viene fornito, le
funzioni \code{ore.doEval} e \code{ore.tableApply} restituiscono
\code{\linkS4class{ore.object}}, mentre le funzioni \code{ore.groupApply},
\code{ore.indexApply} e \code{ore.rowApply} restituiscono
\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