[R-SIG-Finance] blotter and dividends

[Brian G. Peterson]

Mark Breman wrote:
> I want to add a dividend payment from a stock to blotter. How do I do that?
>
> According to the blotter documentation it should be done as a transaction:
> "In the most common use, 'transactions' are trades in an instrument.
> Instruments are bought or sold in a transaction. Other transaction types
> include splits, dividends, expirations, assignments, etc."
>
> but it looks like addTxn() does not support dividends.
>   
You're right, addTxn doesn't yet support dividends. 

It hasn't been important enough to the 'blotter' authors, including 
myself, to get around to adding it.

If it is important to you, we'd love some collaboration to make the 
toolkit better for everyone.

I'm going to state some obvious stuff before launching into design 
details, please bear with me.

Dividends are cash payments from the company to its  equity (stock) 
holders.  Interest, in a similar vein, is cash payments to an issuers 
debt (bond) holders.  There are exceptions to this, but generally 
speaking that definition should be enough to work from.

In blotter, this would need to be evidenced as a cash (in some currency) 
payment into the Account object (where cash/capital/acct equity value of 
the portfolios are held)

We could model this as a cash payment 'on' a Stock/Bond instrument into 
the Portfolio object.  This would make tracking things easier, I think.  
It would add the complication that you might need to add a currency 
position in the portfolio to hold that money.  Another approach would be 
to add a 'adjustments' table to the portfolio object in the list for 
each asset.  The second approach is more work, but might be beneficial 
from a speed perspective, as the adjustments could be stored as a text 
matrix or data.frame, allowing more freedom to add human-readable 
information (the $txn and $posPL slots are all numeric xts objects, for 
increased ease of handling the numeric and time series portions)

I think this is probably best implemented with a new function, not in 
addTxn (which is part of why it hasn't been done yet).  The other types 
of special transactions that you mentioned above (splits, expiration, 
assignment, exercise, etc.) are also different in their effects from 
buying or selling a specific instrument.  All of these, except for 
splits, similarly act on a cash balance.

An addDividend function would be trivial to write (probably fewer than 
20 lines of code), assuming that it adds cash to a portfolio. 

I'm not set on the design details, by any means, but this is my reaction 
to knowing that someone is actually ready to use blotter with 
dividends.  So if anyone has a better implementation proposal, feel free 
to chime in.

If you want to collaborate on this, we'd love your help.  Otherwise, 
I'll bump it up a little in priority on my (long) list of things to do.

In other 'blotter' news, I know that Jeff is starting to look at more 
options-specific handling, which might get some of the other special 
transaction types worked through as well.

Regards,

   - Brian

-- 
Brian G. Peterson
http://braverock.com/brian/
Ph: 773-459-4973
IM: bgpbraverock