[Quantmod-commits] r596 - in pkg: . R man
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Wed Jan 2 04:15:27 CET 2013
Author: jryan
Date: 2013-01-02 04:15:26 +0100 (Wed, 02 Jan 2013)
New Revision: 596
Modified:
pkg/NAMESPACE
pkg/R/getSymbols.R
pkg/R/zzz.R
pkg/man/getSymbols.Rd
pkg/man/internal-quantmod.Rd
Log:
o more changes surrounding getSymbols and 'env'
o new startup message
o new getSymbols documentation updates
o env=NULL now equal to setting auto.assign=FALSE
Modified: pkg/NAMESPACE
===================================================================
--- pkg/NAMESPACE 2013-01-01 18:21:59 UTC (rev 595)
+++ pkg/NAMESPACE 2013-01-02 03:15:26 UTC (rev 596)
@@ -1,4 +1,4 @@
-export(quantmodenv)
+export(quantmodenv, .quantmodEnv)
S3method(print, quantmodEnv)
# NAMESPACE file for quantmod
Modified: pkg/R/getSymbols.R
===================================================================
--- pkg/R/getSymbols.R 2013-01-01 18:21:59 UTC (rev 595)
+++ pkg/R/getSymbols.R 2013-01-02 03:15:26 UTC (rev 596)
@@ -9,7 +9,17 @@
symbol.lookup=TRUE,
auto.assign=TRUE,
...) {
+ if(is.null(.quantmodEnv$options$newEnvmessage)) {
+ # transition message for 0.4-0 to 0.5-0
+ message(paste(' As of 0.4-0,',sQuote('getSymbols'),'uses env=parent.frame() by default.\n',
+ 'This behavior will be phased out in 0.5-0 when the call will check\n',
+ 'getOptions("getSymbols")$env for default value. If NULL, auto.assign will\n',
+ 'be set to FALSE. This message is only shown once per session.'))
+ .quantmodEnv$options$newEnvmessage <- TRUE
+ }
importDefaults("getSymbols")
+ if(is.null(env)) # default as of 0.5-0
+ auto.assign <- FALSE
if(!auto.assign && length(Symbols)>1)
stop("must use auto.assign=TRUE for multiple Symbols requests")
force(Symbols) # need to check if symbol lookup defined _within_ call
@@ -40,7 +50,7 @@
Symbols <- tmp.Symbols
}
old.Symbols <- NULL
- if(exists('.getSymbols',env,inherits=FALSE)) {
+ if(auto.assign && exists('.getSymbols',env,inherits=FALSE)) {
old.Symbols <- get('.getSymbols',env)
}
if(reload.Symbols) {
Modified: pkg/R/zzz.R
===================================================================
--- pkg/R/zzz.R 2013-01-01 18:21:59 UTC (rev 595)
+++ pkg/R/zzz.R 2013-01-02 03:15:26 UTC (rev 596)
@@ -12,6 +12,7 @@
}
.onAttach <- function(libname,pkgname) {
+ packageStartupMessage("Version 0.4-0 included new data defaults. See ?getSymbols.")
# --as-cran check is complaining of this, as a NOTE
#attach(NULL, name='.quantmodEnv')
}
Modified: pkg/man/getSymbols.Rd
===================================================================
--- pkg/man/getSymbols.Rd 2013-01-01 18:21:59 UTC (rev 595)
+++ pkg/man/getSymbols.Rd 2013-01-02 03:15:26 UTC (rev 596)
@@ -51,7 +51,7 @@
\arguments{
\item{Symbols}{ a character vector specifying
the names of each symbol to be loaded}
- \item{env}{ where to create objects. (new.env()) }
+ \item{env}{ where to create objects. Setting env=NULL is equal to auto.assign=FALSE }
\item{reload.Symbols}{ boolean to reload current symbols
in specified environment. (FALSE)}
\item{verbose}{ boolean to turn on status of retrieval.
@@ -61,59 +61,62 @@
(yahoo)}
\item{symbol.lookup}{ retrieve symbol's sourcing method
from external lookup (TRUE) }
- \item{auto.assign}{ should results be loaded to the
- environment }
+ \item{auto.assign}{ should results be loaded to \code{env}
+ If \code{FALSE}, return results instead.
+ As of 0.4-0, this is the same as setting env=NULL }
\item{file.path}{ character string of file location }
\item{\dots}{ additional parameters }
}
\details{
\code{getSymbols} is a wrapper to load data from
-different sources - be them local or remote. Data is
-fetched through one of the available \code{getSymbols} methods
-and saved in the \code{env} specified - the parent.frame()
-by default. Data is loaded in much the same way that \code{load}
-behaves. By default, it is assigned automatically
-to a variable in the specified environment, \emph{without} the
-user explicitly assigning the returned data to a variable.
+various sources, local or remote. Data is
+fetched via one of the available \code{getSymbols} methods
+and either saved in the \code{env} specified - the \code{parent.frame()}
+by default -- or returned to the caller. The functionality derives from \code{base::load}
+behavior and semantics, i.e. is assigned automatically
+to a variable in the specified environment \emph{without} the
+user explicitly assigning the returned data to a variable. The assigned variable
+name is that of the respective Symbols value.
The previous sentence's point warrants repeating - getSymbols is called
-for its side effects, and \emph{does not} return the data object
+for its side effects, and by default\emph{does not} return the data object
loaded. The data is \sQuote{loaded} silently by the function
-into a new environment by default - or the environment specified. This
-behavior can be overridden by setting auto.assign to FALSE,
-though it is not advised.
+into the environment specified.
-The early (pre 2009) versions of getSymbols assigned each object into the user's
-.GlobalEnv by name. This behavior is now supported by setting
-env=.GlobalEnv (the current default is to the calling \sQuote{parent.frame()},
-which in interactive use may be the global environment,
-or by using the wrapper \code{loadSymbols}. Many
-thanks to Kurt Hornik and Achim Zeileis for suggesting this change.
+If automatic assignment is not desired, \code{env} may be set to NULL, or
+\code{auto.assign} set to FALSE.
-By default the variable chosen is an \R-legal name derived
+The early versions of getSymbols assigned each object into the user's
+.GlobalEnv by name (pre 2009 up to versions less than 0.4-0).
+This behavior is now supported by manually setting
+env=.GlobalEnv. As of version 0.4-0, the environment is set
+to parent.frame(), which preserved the user workspace when
+called within another scope.
+
+\emph{This behavior is expect to change as of 0.5-0, and all results will instead be explicitly returned to the caller
+unless a valid \code{env=} argument is passed or set.}
+Many thanks to Kurt Hornik and Achim Zeileis for suggesting this change, and
+further thanks to Dirk Eddebuettel for encouraging the move to a more functional
+default by 0.5-0.
+
+Using auto.assign=TRUE, the variable chosen is an \R-legal name derived
from the symbol being loaded. It is possible, using
\code{setSymbolLookup} to specify an alternate
-name if the default is not desired, see that function for
+name if the default is not desired. See that function for
details.
-The result of a call to \code{getSymbols} when auto.assign
-is set to TRUE (the default) is a new object
-or objects in the user's specified environment - with the
-loaded symbol(s) names returned upon exit if that environment
-is the .GlobalEnv.
-
-%By default, a new environment is returned which contains
-%all the objects loaded into it.
-
-If auto.assign is set to FALSE
+If auto.assign=FALSE or env=NULL (as of 0.4-0)
the data will be returned from the call, and will require
-the user to assign the results himself.
+the user to assign the results himself. Note that only \emph{one} symbol
+at a time may be requested when auto assignment is disabled.
-Most, if not all, documentation and functionality in \pkg{quantmod}
-assumes that auto.assign remains set to TRUE.
+Most, if not all, documentation and functionality related
+to model construction and testing in \pkg{quantmod}
+assumes that auto.assign remains set to TRUE and \code{env} is
+a valid environment object for the calls related to those functions.
Upon completion a list of
-loaded symbols is stored in the global environment
+loaded symbols is stored in the specified environment
under the name \code{.getSymbols}.
Objects loaded by \code{getSymbols} with auto.assign=TRUE
@@ -146,17 +149,23 @@
used (\sQuote{yahoo}).
}
\value{
-A call to getSymbols will load into the specified
-environment one object for each
+Called for its side-effect with \code{env} set to a
+valid environment and auto.assign=TRUE,
+\code{getSymbols} will load into the specified
+\code{env} one object for each
\code{Symbol} specified, with class defined
by \code{return.class}. Presently this may be \code{ts},
\code{its}, \code{zoo}, \code{xts}, or \code{timeSeries}.
-If \code{auto.assign} is set to FALSE an object of type
+If env=NULL or auto.assign=FALSE an object of type
\code{return.class} will be returned.
}
\author{ Jeffrey A. Ryan }
\note{
+As of version 0.4-0, the default \code{env} value is now
+\code{parent.frame()}. In interactive use this should provide
+the same functionality as the previous version.
+
While it is possible to load symbols as classes other
than \code{zoo}, \pkg{quantmod} requires most, if not
all, data to be of class \code{zoo} or inherited
@@ -177,22 +186,42 @@
}
\examples{
\dontrun{
-setSymbolLookup(QQQQ='yahoo',SPY='MySQL')
+setSymbolLookup(QQQ='yahoo',SPY='google')
-getSymbols(c('QQQQ','SPY'))
# loads QQQQ from yahoo (set with setSymbolLookup)
# loads SPY from MySQL (set with setSymbolLookup)
+getSymbols(c('QQQ','SPY'))
+# loads Ford market data from yahoo (the formal default)
getSymbols('F')
-# loads Ford market data from yahoo (the formal default)
-setDefaults(getSymbols,verbose=TRUE,src='MySQL')
-getSymbols('DIA')
# loads symbol from MySQL database (set with setDefaults)
+getSymbols('DIA', verbose=TRUE, src='MySQL')
+# loads Ford as time series class ts
getSymbols('F',src='yahoo',return.class='ts')
-# loads Ford as time series class ts
+# load into a new environment
+data.env <- new.env()
+getSymbols("YHOO", env=data.env)
+ls.str(data.env)
+
+# constrain to local scope
+local( {
+ getSymbols("AAPL")
+ str(AAPL)
+ })
+
+exists("AAPL") # FALSE
+
+# assign into an attached environment
+attach(NULL, name="DATA.ENV")
+getSymbols("AAPL", env=as.environment("DATA.ENV"))
+ls("DATA.ENV")
+
+# directly return to caller
+str( getSymbols("AAPL", env=NULL) )
+
}
}
\keyword{ data }
Modified: pkg/man/internal-quantmod.Rd
===================================================================
--- pkg/man/internal-quantmod.Rd 2013-01-01 18:21:59 UTC (rev 595)
+++ pkg/man/internal-quantmod.Rd 2013-01-02 03:15:26 UTC (rev 596)
@@ -1,4 +1,5 @@
\name{internal-quantmod}
+\alias{.quantmodEnv}
\alias{addShading}
\alias{chartShading}
\title{ Internal quantmod Objects }
More information about the Quantmod-commits
mailing list