Investments::Journal

LastUpdated: $Id: InvJournal.html,v 1.1.1.1 2001/08/09 19:02:56 moreejt Exp $

commands:

  display => "Investment Journal",
  new => "New Investment",
  edit => "Edit Investment",
  delete => "Delete Investment",
  save => "Save Investment",
  shareSelect => "Select Lots",
  lotSelect => "Select Lots",
  searchForm => "Historical Transactions",
  search => "Historical Transactions",

display

new

    This command handles all investment journal actions.

shareSelect

This command presents a screen to the user with lot information for a given date, account, and stock.  All pertinent lots are displayed on the screen with fields to allow the user to select shares for sale or transfer.

lotSelect

Now an ajax screen command that returns a list of lot numbers for the given account, stock, and date in a JSON notation.

searchForm

Displays the form for searching for investment transactions

search

Displays a list of investment transactions.  Usually all transactions will be related by account, stock, and maybe lot.

General Design Concepts

When stocks are puchased as X shares at Y price it is called a lot.  Someone might purchase 500 shares of Red Hat at $10.00 and another 100 shares at $11.00.  Two days later there might be another purchase of 500 shares at $20.00.  A buy event would be entered for each purchase which would create 3 lots.  If we look at a chart we would have:

Buy Date
Account
Stock
Lot
price
shares
cost
2006-1-1
Broker
Red Hat
1
10.00
500
5000
2006-1-1
Broker
Red Hat 2
11.00
100
1100
2006-1-2
Broker
Red Hat 3
20.00
500
10000

It would be great if it remained that simple but it does not.  What happens when you sell some of those shares?  A sell event would be entered which specifies one or more lots to use for that event.  Let's say that we sell 100 shares at $40.00.  The simple thing to do is to use the lot that has exactly 100 shares but you might want to minimize your capital gains by using the lot with the highest cost.  When finished you would have.

Buy Date
Account
Stock
Lot
cost/share
shares
cost
2006-1-1
Broker
Red Hat
1
10.00
500
5000
2006-1-1
Broker
Red Hat 2
11.00
100
1100
2006-1-2
Broker
Red Hat 3
20.00
400
8000

SellNotice that lot 3 how only has 400 shares.  How do we keep track of all of these changes?  This system treats each lot as a tree with nodes at each change (event). 

What about when other events happen such as a stock split.   Lets say that a 2 for 1 stock split happens on 2007-2-1.  The chart would now look like this

Buy Date
Account
Stock
Lot
cost/share
shares
cost
2006-1-1
Broker
Red Hat
1
5.00
1000
5000
2006-1-1
Broker
Red Hat 2
5.50
200
1100
2006-1-2
Broker
Red Hat 3
10.00
800
8000

SplitNote that the cost per share drops in half because the shares doubled.  The cost remains the same.  Let's also say that we sell the rest of Lot 3 on 2007-3-1. 

This tree structure has a node at each change.  The system uses an object called LotNode to hold this information.  All of the LotNodes together make up a tree for a lot.  The node information is stored in a database table called lot_node_tb.  To find the balances for cost or shares for any given date we search for a node on the tree.  The last node with a date less than or equal to the given date is the current node.

Now let us suppose that Red Hat has ownership in Widgets Inc. and they decide to divest this ownership to the shareholders of Red Hat.  This is often called a spin off.  We enter an event called SpinOff into the system.  It will contain the new number of shares and the amount of cost to allocate to the new lot that will be created.  This happens on 2007-12-31 so it will not affect lot 3 because it has a zero balance at that point in time.  Lot 1 and 2 will be used in calculations.  To make things simple we will have a 1 for 1 split with 25% of the cost going to the new lots.

Buy Date
Account
Stock
Lot
cost/share
shares
cost
2006-1-1
Broker
Red Hat
1
3.75
1000
3750
2006-1-1
Broker
Red Hat 2
4.13 (4.125)
200
825
2006-1-1
Broker
Widgets 4
1.25
1000
1250
2006-1-1 Broker
Widgets
5
1.38 (1.375)
200
275

Spin OffNotice that there are two new lots based on the two old lots. The number of shares in each new lot matches the old lots because it was a 1 for 1 split. Next notice that the dates used for the new lots are the same as the old lots.  The cost has been split between the new and old lots.  If you add lot 1 and lot 4 costs you will get the old $5000 cost from before the transaction.  The cost per share is rounded to 2 decimals. 

The tree visual of lot 1 now has a branch over to a new subtree for lot 5.  The types of events which create new lots are Transfer, Spin Off, Merger. 


Processes

The general idea is that events create nodes in a lot tree.  A buy event always starts a new tree.  Events will add 1 or 2 new nodes to each affected tree.  The event->insert method gathers a list of affected lots.  For each lot node the old tree after the event date must be deleted so that this new event data can be input and the tree can be reconstructed.  We call this method deleteTree and propagateLot. (Rename to growTree at some point?)

Some tricky aspects of this are that the insertion of an event in between other events may invalidate some of them.  For example, if a lot were transferred on 2006-1-1 and a sell was entered on 2005-12-1 for all shares then the lot cannot be transferred. 

Since the data is stored in this tree structure it is possible to run a Return on Investment (ROI) on each lot which would include all the other lots created from the current one.  This allows you to compare the initial ivestment with the current market value for all of the tree.

At some point it may be possible to merge lots together and average the costs between them.  That will make ROI graphs much harder to create.


Copyright (c) 2001 HLR
Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.1; A copy of the license is available at http://www.gnu.org/licenses/licenses.html#FDL.

Updated: $Id: InvJournal.html,v 1.1.1.1 2001/08/09 19:02:56 moreejt Exp $