[Blotter-commits] r479 - pkg/blotter/R

[noreply at r-forge.r-project.org]

Author: peter_carl
Date: 2010-11-30 12:56:13 +0100 (Tue, 30 Nov 2010)
New Revision: 479

Modified:
   pkg/blotter/R/initPortf.R
Log:
- added roxygen documentation


Modified: pkg/blotter/R/initPortf.R
===================================================================
--- pkg/blotter/R/initPortf.R	2010-11-30 11:18:13 UTC (rev 478)
+++ pkg/blotter/R/initPortf.R	2010-11-30 11:56:13 UTC (rev 479)
@@ -1,22 +1,59 @@
-#' Initializes a portfolio object, 
+#' Initializes a portfolio object.
 #' 
-#' Initializes a portfolio object, which is constructed from is constructed of the following:
-#' $symbols: the identifier used for each instrument contained in the portfolio. Use names(Portfolio$symbols) to get a list of symbols.
-#' $[symbol]$txn: irregular xts object of transactions data 
-#' $[symbol]$posPL: regular xts object of positions P&L calculated from transactions
-#' $[symbol]$posPL.ccy: regular xts object of positions P&L converted to portfolio currency
-#' $summary: summary slot
+#' Constructs and initializes a portfolio object, which is used to contain transactions, positions, and aggregate level values.
+#'
+#' Initializes a portfolio object, which is constructed from the following:
+#' $symbols: the identifier used for each instrument contained in the portfolio. Use \code{names(Portfolio$symbols)} to get a list of symbols.
+#' $symbols$[symbol]$txn: irregular xts object of transactions data 
+#' $symbols$[symbol]$posPL: regular xts object of positions P&L calculated from transactions
+#' $symbols$[symbol]$posPL.ccy: regular xts object of positions P&L converted to portfolio currency
+#' $summary: aggregated portfolio values
+#'
+#' Each symbol has three associated tables.  The first, txn, is the transactions table, an irregular time series that contains information about trades or other position adjustments with the following columns:
+#' \itemize{
+#' \item Txn.Qty: the quantity, usually in units of contracts, changing hands. Positive values indicate a "buy" transaction; negative values are used to indicate a "sell."
+#' \item Txn.Price: the price at which the transaction was made,
+#' \item Txn.Fees: the sum total of transaction fees associated with the trade,
+#' \item Txn.Value: the notional value of the transaction,
+#' \item Avg.Txn.Cost: a calculated value for the average net price paid (received) per contract bought (received),
+#' \item Pos.Qty: the resulting position quantity of contracts, calculated as the sum of the current transaction and the prior position,
+#' \item Pos.Avg.Cost: the calculated average cost of the resulting position, and
+#' \item Realized.PL: any profit or loss realized in the transaction from closing out a prior position
+#' }
+#'
+#' The second, posPL, is a container used to store calculated P&L values from transactions and close prices within an instrument. The data series is, however, a regular time series. Columns of the table include:
+#' \itemize{
+#' \item Pos.Qty the quantity of the position held in the symbol,
+#' \item Pos.Value the notional value of the position,
+#' \item Txn.Value the net value of the transactions occuring,
+#' \item Txn.Fees the total fees associated with transactions,
+#' \item Realized.PL any net profit or loss realized through transactions,
+#' \item Unrealized.PL any profit or loss associated with the remaining or ’open’ position, and
+#' \item Trading.PL the sum of net realized and unrealized profit and loss.
+#' }
 #' 
+#' The third, posPL.ccy, is the same as the second but translated into the portfolio currency.
+#'
+#' For each portfolio, the summary slot contains a table that tracks calculated portfolio information through time. The table contains the following columns, held in a regular xts time series:
+#' \item Long.Value: The sum of the notional value of all positions held long in the portfolio.
+#' \item Short.Value: The sum of the notional value of all positions held short in the portfolio.
+#' \item Net.Value: The sum of the notional long and notional short value of the portfolio.
+#' \item Gross.Value: The sum of the notional long and absolute value of the notional short value of the portfolio.
+#' \item Txn.Fees: The sum of brokerage commissions, exchange and other brokerage fees paid by the portfolio during the period.
+#' \item Realized.PL: The sum of net realized profits or losses aggregated from the underlying positions in the portfolio. Gross realized profits can be calculated by adding ’Txn.Fees’, the brokerage commission expenses for the period.
+#' \item Unrealized.PL: The sum total increase or decrease in unrealized profits or losses on open positions in the portfolio at the end of the period.
+#' \item Net.Trading.PL: Net realized profit or loss plus interest income plus change in unrealized profit or loss across all positions in the portfolio.
+#' 
 #' TODO: add $account: name of the (one) affiliated account
 #
 #' Outputs
 #' Initialized portfolio structure with a start date and initial positions.
 #' 
-#' @param name 
-#' @param symbols  instrument identifiers of those instruments contained in the portfolio 
-#' @param initPosQty initial position, default is zero
-#' @param initDate date prior to the first close price given, used to contain initial account equity and initial position
-#' @param currency ISO currency idenifier used to locate the portfolio currency
+#' @param name A name for the resulting portfolio object
+#' @param symbols  A list of instrument identifiers for those instruments contained in the portfolio 
+#' @param initPosQty Initial position quantity, default is zero
+#' @param initDate A date prior to the first close price given, used to contain initial account equity and initial position
+#' @param currency ISO currency identifier used to locate the portfolio currency
 #' @author Peter Carl
 #' @export
 initPortf <- function(name="default", symbols, initPosQty = 0, initDate = '1950-01-01', currency='USD')