BeanCounter -- A stock portfolio performance monitoring tool 1. Introduction Ever wondered what happened to your portfolio on a day the market moved 500 points? Ever wondered what your portfolio returned over the last (odd) period? Ever wondered if there was a simple cron job to report portfolio changes on a daily basis? Ever wondered if you could database the (public) price, volume, ... info on dozens of stocks for further analysis? BeanCounter does all this, and provides a convenient command-line tool as well as a Perl library that can be used by other applications. Beancounter support stocks from exchanges in the US, Canada, Britain, France, Germany, Italy, Singapore, Taiwan, Thailand, HongKong... as well as Australia and New Zealand. Tested patches for other markets are always welcome. US mutual funds are supported, as are foreign exchange rates and some precious metals. This is still somewhat beta in the sense that the command-line options and function interfaces might change. The (initial) release number is kept low intenionally. However, similar code has been working here since the fall of 1998. 2. How to get started You need Perl and PostgreSQL, or MySQL (as of version 0.4.0). Plus a host of Perl modules such as DBI (Database independent interface) with either the DBD ODBC or the DBD Postgres driver (i.e. DBD-Pg) or the DBD Mysql driver, LWP networking as well as Date::Manip and Statistics::Descriptive. All of this is readily available for Debian; or else in source code at www.postgresql.org and www.cpan.org. Upon opening the .tar.gz archive, run $ perl Makefile.PL $ make install and everything should be fine. Run $ beancounter --help for a quick check. Run 'setup_beancounter' to create the new database and tables, and to have them filled with example data. This even runs a first portfolio report on the (example) portfolio. The 'setup_beancounter' script has a few sanity checks to ensure that Postgres (or MySQL) is running, that the current user is a valid database user, that it is not called by root, and that the database hasn't already been created. 3. How to use it Beancounter's --help options shows the main functionality. This currently comprised the following operations: o "addindex index sym1 sym2 ..." fills the indices table with info on stocks comprising a market index. o "addportfolio sym1:nb1:fx sym2:nb:fx ..." fills the portfolio table with the specified quantities (eg 'nb1' or 'nb2' in the example above) of the specified stocks. Additional attributes of the holding can be specified as well. These are 'type' in which one could store the tax classification of a retirement account, eg 'rrsp' in Canada or '401k' in the USA, 'holder' which can carry the name of the account holder so that one could e.g. differentiate between spousal accounts, 'cost' which stores the purchase price and 'purchasedate' for the time of the purchase. o "addstock sym1 sym2 ..." to add one (or several) stock(s) to the database by filling both the 'stockinfo' table with general company and stock info, as well as the `stockprices' table with the most recent price data. Its purpose is to initialise the database for new stocks. o "backpopulate sym1 sym2 ..." backpopulates the database for one (or several) stock(s). It can be used to extend the database with historic prices. Limiting dates can be supplied via the --fromdate and --todate arguments. o "dailyjob" which combines 'update' and 'dayendreport' o "dayendreport" runs a report summarising day-over-day changes o "destroydb" removes the database entirely with not further warning. o "plreport" runs an end-of-day profit/loss report on the portfolio. It can be run automatically by cron(8) via an entry in crontab(5) such as 15 17 * * 1-5 beancounter update && beancounter plreport It can be run from cron(8) just after 'daily_update.pl'. o "risk" runs an risk analysis with parametric Value-at-Risk (VaR) calculated via the standard Delta method (a.k.a. RiskMetric (TM)), a non-parametric VaR (using the 1% quantile) as well as marginal VaR analysis. o "quote sym1 sym2 ..." retrieves price info from the Web and displays it without touching the database. This is useful for verifying a stock symbol as well the network status. o "status" computes a holdings value and (annualized) return summary which also shows how long a stock has been held. o "update" updates the database with day-end information. It can be run automatically by cron(8) via an entry in crontab(5) such as 15 17 * * 1-5 beancounter update (but also see about combining this with a call to beacounter plreport') o "warranty" shows a brief statement about the GNU General Public License The shell script 'setup_beancounter' initialises the database, creates the tables and fills them with initial data. The shell script 'update_beancounter' changes, if necessary, the database table to bring an older (0.1.*) installation up to speed. 5. To Do More error checking. More performance analytics. More markets. More documentation. Maybe a GUI. See the TODO file. 6. Disclaimer (taken straight from the GPL) NO WARRANTY 11. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION. 12. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. In short: if it breaks, you can keep the pieces. This is Free Software, use it as you see fit, but don't come running or screaming if it doesn't work as intended. Dirk Eddelbuettel $Id: README,v 1.6 2001/10/12 01:47:53 edd Exp edd $