Using the addDiv(command) in R from quantstrat/blotter

Question

What is the format for using the addDiv command in R? I know how to use the function as far as inputs go, but I can't figure out where it should be placed beyond a general idea. Do I place it after where I instantiate the portfolio? Below is the help article R provides:

Add cash dividend transactions to a portfolio.

Description

Adding a cash dividend does not affect position quantity, like a split would.

Usage

addDiv(Portfolio, Symbol, TxnDate, DivPerShare, ..., TxnFees = 0,  
       ConMult = NULL, verbose = TRUE)

Arguments

Portfolio A portfolio name that points to a portfolio object structured with initPortf.

Symbol An instrument identifier for a symbol included in the portfolio, e.g., IBM.

TxnDate Transaction date as ISO 8601, e.g., '2008-09-01' or '2010-01-05 09:54:23.12345'.

DivPerShare The amount of the cash dividend paid per share or per unit quantity.

TxnFees Fees associated with the transaction, e.g. commissions. See Details.

ConMult Contract or instrument multiplier for the Symbol if it is not defined in an instrument specification.

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.

... Any other passthrough parameters.

Note

**# TODO add TxnTypes to $txn table

**# TODO add AsOfDate****

Answer 1

Here's an example of how to use it, which is based on demo("longtrend") from the blotter package. As you can see, it's fine if you call it after the fact, since blotter knows your position.

That said, you'll need to call it contemporaneously if you need to know your total P&L in order to make trading decisions.

require(blotter)
demo(longtrend, ask=FALSE)

# Add dividends from SPY
spyDiv <- getDividends("SPY", from=initDate)
for(i in 1:nrow(spyDiv)) {
  obs <- spyDiv[i,]
  addDiv("longtrend", "GSPC", index(obs), obs)
}
# Need to update portfolio, account, etc again, since
# we added new transactions
updatePortf("longtrend")
updateAcct("longtrend")
updateEndEq("longtrend")

# Plot position with dividends, calling dev.new() so
# we can compare it to the original plot from the demo.
dev.new()
chart.Posn("longtrend", "GSPC", Dates="1998::")
add_SMA(n=10, col="darkgreen", on=1)

#look at a transaction summary
getTxns(Portfolio="longtrend", Symbol="GSPC")