[Blotter-commits] r529 - in pkg/blotter: R man
noreply at r-forge.r-project.org
noreply at r-forge.r-project.org
Thu Jan 6 16:14:00 CET 2011
Author: peter_carl
Date: 2011-01-06 16:13:59 +0100 (Thu, 06 Jan 2011)
New Revision: 529
Modified:
pkg/blotter/R/addTxn.R
pkg/blotter/R/chart.Posn.R
pkg/blotter/R/extractTests.R
pkg/blotter/R/getAccount.R
pkg/blotter/R/getTxn.R
pkg/blotter/man/blotter-package.Rd
Log:
- edits to documentation
Modified: pkg/blotter/R/addTxn.R
===================================================================
--- pkg/blotter/R/addTxn.R 2011-01-05 04:04:18 UTC (rev 528)
+++ pkg/blotter/R/addTxn.R 2011-01-06 15:13:59 UTC (rev 529)
@@ -103,8 +103,8 @@
}
#' Add multiple transactions to a portfolio
-#' @param Portfolio A portfolio name that points to a portfolio object structured with initPortf()
-#' @param Symbol An instrument identifier for a symbol included in the portfolio,e.g., IBM
+#' @param Portfolio A portfolio name that points to a portfolio object structured with \code{\link{initPortf}}
+#' @param Symbol An instrument identifier for a symbol included in the portfolio, e.g., "IBM"
#' @param TxnData An xts object containing all required txn fields
#' @param \dots Any other passthrough parameters
#' @param verbose If TRUE (default) the function prints the elements of the transaction in a line to the screen, e.g., "2007-01-08 IBM 50 \@ 77.6". Suppress using FALSE.
@@ -177,12 +177,12 @@
#'
#' Adding a cash dividend does not affect position quantity, like a split would.
#'
-#' @param Portfolio A portfolio name that points to a portfolio object structured with initPortf().
+#' @param Portfolio A portfolio name that points to a portfolio object structured with \code{\link{initPortf}}.
#' @param Symbol An instrument identifier for a symbol included in the portfolio, e.g., IBM.
#' @param TxnDate Transaction date as ISO 8601, e.g., '2008-09-01' or '2010-01-05 09:54:23.12345'.
#' @param DivPerShare The amount of the cash dividend paid per share or per unit quantity.
#' @param \dots Any other passthrough parameters.
-#' @param TxnFees Fees associated with the transaction, e.g. commissions. See Details
+#' @param TxnFees Fees associated with the transaction, e.g. commissions. See Details.
#' @param verbose If TRUE (default) the function prints the elements of the transaction in a line to the screen, e.g., "2007-01-08 IBM 50 \@ 77.6". Suppress using FALSE.
#' @param ConMult Contract or instrument multiplier for the Symbol if it is not dened in an instrument specication.
#' @export
Modified: pkg/blotter/R/chart.Posn.R
===================================================================
--- pkg/blotter/R/chart.Posn.R 2011-01-05 04:04:18 UTC (rev 528)
+++ pkg/blotter/R/chart.Posn.R 2011-01-06 15:13:59 UTC (rev 529)
@@ -1,8 +1,13 @@
-#' chart trades against market data, position through time, and equity curve
+#' Chart trades against market data, position through time, and cumulative P\&L
+#'
+#' Produces a three-panel chart of time series charts that contains prices and transactions in the top panel, the resulting position in the second, and a cumulative profit-loss line chart in the third.
+#' @note Expect changes to this function, since the underlying charts are experimental functions in quantmod.
+#'
#' @param Portfolio string identifying the portfolio to chart
#' @param Symbol string identifying the symbol to chart
-#' @param Dates date range, currently not used
-#' @param ... any other passthru parameters (typically parameters to \code{chart_Series})
+#' @param Dates currently not used
+#' @param ... any other passthru parameters to \code{\link[quantmod:chart_Series]chart_Series}}
+#' @seealso
#' @export
chart.Posn <- function(Portfolio, Symbol, Dates = NULL, ...)
{ # @author Peter Carl
Modified: pkg/blotter/R/extractTests.R
===================================================================
--- pkg/blotter/R/extractTests.R 2011-01-05 04:04:18 UTC (rev 528)
+++ pkg/blotter/R/extractTests.R 2011-01-06 15:13:59 UTC (rev 529)
@@ -1,15 +1,16 @@
-#' extract transactions from a portfolio in a manner suitable for creating tests
+#' Extract transactions from a portfolio
#'
#' This function reverse-engineers \code{\link{addTxn}} calls for all the transactions in \code{Portfolio}.
#' This is the fundamental task required to create a reproducible example, as it would replicate the
-#' state of the $txn slot in the portfolio after each addTxn call.
+#' state of the $txn slot in the portfolio after each \code{addTxn} call.
#' While market data, expected results, portfolio and account setup, etc, are also required,
#' these can usually be deduced or equivalent formulations can be found.
#'
-#' For transactions, only the exact addTxn parameters will recreate the $txn slot. This function creates that reproducibility.
+#' For transactions, only the exact \code{addTxn} parameters will recreate the $txn slot. This function creates that reproducibility, since the result (stored in 'x') can be used to regenerate transactions with \code{eval(parse(text=x))}.
#'
#' @param Portfolio string identifying the portfolio to extract from
-#' @return string vector of \code{\link{addTxn}} calls that would replicate the given portfolio
+#' @return String vector of \code{\link{addTxn}} calls that would replicate the given portfolio.
+#' @author Brian G. Peterson, Josh Ulrich
#' @export
extractTxns <- function(Portfolio)
{ # @author Brian G. Peterson, Josh Ulrich
Modified: pkg/blotter/R/getAccount.R
===================================================================
--- pkg/blotter/R/getAccount.R 2011-01-05 04:04:18 UTC (rev 528)
+++ pkg/blotter/R/getAccount.R 2011-01-06 15:13:59 UTC (rev 529)
@@ -1,9 +1,11 @@
-#' get an account object from the environment for examination or manipulation
+#' Get an account object from the .blotter environment
+#'
+#' Retrieves an account object from the \code{.blotter} environment. Useful for local examination or charting, or storing interim results for later reference.
+#'
#' @param Account string identifier for the account
-#' @param Dates
#' @return Account object
#' @export
-getAccount <- function(Account, Dates=NULL) #should symbol subsets be supported too? probably not.
+getAccount <- function(Account) #should symbol subsets be supported too? probably not.
{ # @author Brian Peterson
aname<-Account
if(!grepl("account\\.",aname)) Account<-try(get(paste("account",aname,sep='.'),envir=.blotter))
@@ -12,10 +14,10 @@
stop(paste("Account ",aname," not found, use initAcct() to create a new account"))
if(!inherits(Account,"account")) stop("Account ",aname," passed is not the name of an account object.")
- if(!is.null(Dates)){
- message("date subsetting not yet supported")
- #TODO add date subsetting in getAccount
- }
+# if(!is.null(Dates)){
+# message("date subsetting not yet supported")
+# #TODO add date subsetting in getAccount
+# }
return(Account)
}
Modified: pkg/blotter/R/getTxn.R
===================================================================
--- pkg/blotter/R/getTxn.R 2011-01-05 04:04:18 UTC (rev 528)
+++ pkg/blotter/R/getTxn.R 2011-01-06 15:13:59 UTC (rev 529)
@@ -1,24 +1,25 @@
-#' Retrieves the transactions and their attributes.
+#' Retrieve transactions and their attributes.
#'
#' Find and return the transactions and attribute values for the symbol and date in a specied portfolio.
#'
-#' This function provides easy access to the values of transactions contained in a Portfolio object. See initPortf for a detailed description of the structure of a Portfolio object.
+#' This function provides easy access to the values of transactions contained in a Portfolio object. See \code{\link{initPortf}} for a detailed description of the structure of a Portfolio object.
#'
#'
#' @param Portfolio a string identifying a portfolio object containing transactions
#' @param Symbol an instrument identifier for a symbol included in the portfolio
-#' @param Date timestamp as of which to get transactions
-#' @return xts of transactions made in the Symbol during the time period given
+#' @param Dates specified as an ISO 8601 date or an xts date range, such as "2007-01::2008-04-15"
+#' @return xts time series of transactions made in the Symbol during the time period given
+#' @seealso \code{\link{initPortf}}
#' @export
-getTxns <- function(Portfolio, Symbol, Date)
+getTxns <- function(Portfolio, Symbol, Dates)
{ # @author Peter Carl
pname<-Portfolio
- Portfolio<-get(paste("portfolio",pname,sep='.'),envir=.blotter)
+ Portfolio<-get(paste("portfolio",pname,sep='.'), envir=.blotter)
if(inherits(Portfolio,"try-error"))
stop(paste("Portfolio",pname," not found, use initPortf() to create a new portfolio first"))
TxnData = Portfolio$symbols[[Symbol]]$txn
- Txns = TxnData[Date,c('Txn.Qty', 'Txn.Price', 'Txn.Fees', 'Txn.Value', 'Txn.Avg.Cost', 'Net.Txn.Realized.PL')]
+ Txns = TxnData[Dates,c('Txn.Qty', 'Txn.Price', 'Txn.Fees', 'Txn.Value', 'Txn.Avg.Cost', 'Net.Txn.Realized.PL')]
return(Txns)
}
Modified: pkg/blotter/man/blotter-package.Rd
===================================================================
--- pkg/blotter/man/blotter-package.Rd 2011-01-05 04:04:18 UTC (rev 528)
+++ pkg/blotter/man/blotter-package.Rd 2011-01-06 15:13:59 UTC (rev 529)
@@ -19,12 +19,14 @@
Portfolios are associated with an 'account'. An account is modeled as a cash account where investments, withdrawals, management fees, and other capital account changes are made.
-The package also contains functions to help users evaluate portfolios, including charts and graphs to help with visualization.
+The package also contains functions to help users evaluate portfolios, including charts and graphs to help with visualization. A small selection of post-trade metrics has been added recently, and is likely to change and expand as we hear more about what people want to calculate.
Blotter's functions build and manipulate objects that are stored in an environment named ".blotter" rather than the global environment, \code{.GlobalEnv}. Objects may be listed using \code{ls(envir=.blotter)}. See \code{\link{environment}} for more detail.
We do that for two reasons. First, keeping them out of the \code{.GlobalEnv} means less clutter in the user's workspace and less chance of clobbering something locally. Second, we don't recommend acting on the account and portfolio objects directly. Manipulating the objects directly will almost certainly create inconsistencies and problems with the resulting calculations. Instead, we recommend copying them into the local workspace using \code{getPortfolio} or \code{getAccount} functions, or simply using blotter functions.
+Blotter relies heavily on \code{\link[xts:xts-package]{xts} for the heavy lifting of date and time subsetting. Many thanks to Jeff Ryan and Josh Ulrich for their diligent help ferretting out all those corner cases. As a result, any \code{Dates} parameter in the package leverages \code{\link[xts:xts-package]{xts} date scoping. For example, \code{getTxn(Portfolio="p", Symbol="XYZ", Dates="2007-01")} will retrieve all transactions for "XYZ" from January, 2007. Similarly, a range of dates may be specified as "2007-01::2008-04-15". Take a look at the \code{\link[xts:xts-package]{xts} documentation for more detail. Otherwise, the \code{Date} or \{Dates} parameter accepts an ISO 8601 format such as '2008-09-15' or '2010-01-05 09:54:23.12345'. In almost all cases, if the \code{Dates} parameter is unspecified, the function will return all results.
+
The sole example in the documentation of blotter follows, providing a simple but more complete overview of how blotter can be used. More extensive examples can be seen in the demos. The \code{longtrend} demo shows a simple trend-following example, and \code{turtles} shows a more complicated trend-following example. The \code{amzn_test} demo shows blotter's use with tick data.
}
More information about the Blotter-commits
mailing list