beancounter - Stock portfolio performance monitor tool
beancounter [options] command [command_arguments ...]
addindex index args add stock(s) to market index 'indx'
addportfolio sym:nb:fx:type:o:pp:pd ...
add 'nb' stocks of company with symbol 'sym'
that are listed in currency 'fx' to the
portfolio with optional 'type' and 'owner'
info, purchase price 'pp' and date 'pd';
see below for a complete example
addstock arg ... add stock(s) with symbol arg to the database
backpopulate arg ... fill with historic data for given stock(s)
dailyjob combines 'update' and 'dayendreport'
dayendreport combines 'update' and 'plreport'
deletestock arg ... delete stock(s) from database
destroydb delete the BeanCounter database
plreport run an end-of-day portfolio report
quote arg ... report current data for given stock(s)
status status summary report for portfolio
update update the database with day's data
warranty display the short GNU GPL statement
--help show this help --verbose more verbose operation, debugging --date date report for this date (today) --prevdate date relative to this date (yesterday) --currency fx set home currency --restriction sql impose SQL restriction --extrafx fx1,fx2,... additional currencies to load --rcfile file use different configuration file
beancounter analyses stock market data to evaluate portfolio performance. It has several modes of operation. The first main mode is data gathering: both current data (e.g. end-of-day closing prices) and historical price data (to back-populate the database) can be automatically retrieved and stored in a relational database (which is developed on PostgreSQL but should be easily portable to other database systems thanks to the Perl DBI layer). The second main mode is data analysis where the stored data is evaluated to provide performance information.
Data is retrieved from the Yahoo! Finance web sites with support for North America (i.e. US and Canada), Europe (for the Continent as well as Great Britain), several Asian stock markets, Australia and New Zealand. New markets are easy to add by following the (fairly extensively commented) Perl code. Patches are welcome!
beancounter can aggregate the change in value for the entire portfolio over arbitrary time horizons. Using the powerful date-parsing routine available to Perl, you can simply say 'from six months ago to today' (see below for examples).
beancounter has been written and tested under Linux. It should run under any standard Unix as long as the required Perl modules are installed, as as long as the DB (currently only tested with PostgreSQL) is found.
beancounter addportfolio SUNW:100:USD:joe:401k:85.50:19991117 \
IBM:100:USD:joe:401k:90.25:20000320 \
SPY:50:USD:joe:ira:142.25:20000620
This adds the two stocks Sun and IBM to the 401k portfolio of Joe,
as well as SP500 'Spiders' to his IRA portfolio. The stocks are
also added to the general stock info tables.
beancounter addstock LNUX RHAT COR.TO
This adds these three Linux companies to the database without adding
them to any specific portfolios.
beancounter backpopulate --prevdate '1 year ago' \
--date 'friday 1 week ago' IBM SUNW HWP
This backpopulates the database with historic prices for three
hardware companies. Note how the date specification is very general.
beancounter plreport --prevdate '1 month ago' --date 'today' \
--restriction "owner='joe'"
This calculates portfolio profits or losses over the last year. It
also imposes the database restriction that only stocks owned by
'joe' are to be included.
beancounter status --restriction "type='401k'"
This shows a portfolio status report with the restriction that only
stocks from the '401k' account are to be included.
The following few paragraphs will illustrate the use of beancounter. We will set up two fictional accounts for two brothers Bob and Bill (so that we can illustrate the 'owner' column). The prices below are completely ficticious, as are the portfolios.
We suppose that beancounter is installed and that the 'setup_beancounter' command has been run. We can then create a two-stock (computer hardware) portfolio for Bob as follows:
beancounter addportfolio SUNW:100:USD:bob:401k:85.50:19991117 \
IBM:100:USD:bob:401k:90.25:20000320
Here we specify that 100 shares each of Sun and IBM, priced in US Dollars, are in Bob's portfolio which is tagged as a 401k retirement account. The (fictious) purchase price and date are also given.
Let's suppose that Bill prefers networking equipment, and that he has a brokerage account in Canada:
beancounter addportfolio CSCO:100:USD:bill:spec:78.00:19990817 \
NT:200:CAD:bill:spec:cad:90.25:20000212
Now we can backpopulate the database from 1998 onwards for all four stocks:
beancounter backpopulate --prevdate 19980101 CSCO IBM NT SUNW
With this historical data in place, we now compare how Bob's portfolio would have fared over the last 18 months:
beancounter plreport --prevdate '18 months ago' --restriction "owner='bob'"
Note how we use double quotes to protect the arguments, and how the SQL restriction contains a further single quote around the literal string.
We can also review the performance for Bill at the most recent trading day:
beancounter dayendreport --restriction "owner='bill'"
or the status of holdings and their respective values:
beancounter dayendreport --restriction "owner='bill'"
addportfolio is the most important 'position entry' command. As with other commands, several arguments can be given at the same time. For each of these, records are separated using a colon and specify, in order, stock symbol, number of stocks held, currency, account type, account owner, purchase price and purchase date. Only the first three arguments are required, the others are optional. Executing addportfolio implicitly executes addstock. The account type column can be used to specify whether the account is, e.g., a tax-sheltered retirement account, or it could be used to denote the brokerage company is it held at.
plreport retrieves the most recent quotes(s). This is useful for
illiquid securities which might not have traded that day, or if a public
holiday occurred, or if there was a data error at Yahoo!. Two dates can be
specified which determine the period over which the profit or loss is
computed. This will fail if price data (or currency data in the case of
foreign stocks data) data is not available for either of those two dates.
This can be restrictive for foreign stocks where we cannot backpopulate due
to lack of public data source for historical currency quotes.
dayendreport is similar to plreport but is always over a one-day period. It also uses only one date record by calculating performance given the 'previous close' data.
status shows holdings amounts, total position values, annualized returns in percentages and holding periods in days. Note that the annualized returns can appear excessive if, e.g., a ten-day return from a recently purchased stock is extrapolated to an annual time period.
addindex adds stocks a the index table. Currently, no further analysis references this table.
addstock adds stocks to the database. From then on data will be retrieved for the
given symbol(s) and stored in the database whenever the update command is executed.
addpopulate fills the database with historic prices for the given symbols and date period. Note that this works for stocks only, but not for currencies due to the lack of a public source of historical FX prices.
quote simply shows a price quote for the given symbol(s).
update updates the database with quotes for all stocks for the given day. No output is generated making the command suitable for cron execution.
dailyjob is a simple wrapper around update and dayendreport.
deletestock removes the given symbols from the database.
destroydb deletes the BeanCounter database.
warranty display a short GNU General Public License statement.
--currency can be used to select a different home currency. Instead of having all values converted to the default currency, the selected currency is used.
--date allows to choose a different reference date. This is then be be used by commands working on a date, or date period, such as plreport, dayendreport, backpopulate or status. --prevdate allows to choose a different start date for return calculations, or data gathering.
--restriction can be used to restrict the database selection. The argument must be a valid part of valid SQL statement in the sense that existing columns and operators have to be employed. The argument to this option will be completed with a leading and. The SQL restriction will typcally be over elements of the portfolio table which comprises the columns symbol, shares, currency, type, owner, cost and date. A simple example would be currency='CAD'. Note that this has to protected by double quotes "I on the command-line.
--extrafx allows to gather data on additional currency rates beyond those automatically selected as shares are listed in them. A typical example would be for a European investor wanting to convert from the EUR in which the shares are listed into one of the member currencies which beancounter would no longer retrieve as shares are no longer listed in these.
--rcfile allows to specify a resource file different from the default ~/.beancounterrc.
The --verbose and --debug switches can be used in debugging an testing, and --help triggers the display of help message.
The following section details some of the database and configuration options.
beancounter currently depends of PostgreSQL. Another DB backend could be used, provided suitable Perl DBI drivers are available. The setup_beancounter script initializes the database, creates the required tables and fills them with some example data. It is a starting point for local modifications.
The connection to the database is made via a dedicated function in the BeanCounter.pm module, changes would only have to be made there. As of this writing the Perl DBI (the database-independent interface for Perl) is used along the DBI driver for PostgreSQL; an extension is planned for the DBI ODBC driver. Ports for MySQL, Oracle, ... are encouraged.
A configuration file ~/.beancounterrc is read if found. It currently supports the following options:
An example file example.beancounterrc should have come with the sources (or the Debian package); please consult this file for more examples.
There are now several ODBC systems for Linux / Unix. The following ~/.odbc.ini work with the iODBC library on my Debian GNU/Linux system:
[ODBC Data Sources] beancounter = BeanCounter Database
[beancounter] Driver = /usr/lib/libpsqlodbc.so Database = beancounter Servername = localhost
[ODBC] InstallDir = /usr/lib
Suggestions are welcome of how to set beancounter up with other ODBC libraries.
Finance::BeanCounter and beancounter are so fresh that there are only missing features :) Seriously, check the TODO list. This code or its predecessors have been used by the author since the end of 1998.
There might be issues with Perl 5.6 and PostgreSQL 7.* which have yet to be installed on the machines the author is running beancounter on.
Finance::BeanCounter.3pm, smtm.1, Finance::YahooQuote.3pm, LWP.3pm, Date::Manip.3pm
beancounter is (c) 2000 by Dirk Eddelbuettel <edd@debian.org>
Updates to this program might appear at http://rosebud.sps.queensu.ca/~edd/code/beancounter.html.
This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. There is NO warranty whatsoever.
The information that you obtain with this program may be copyrighted by Yahoo! Inc., and is governed by their usage license. See http://www.yahoo.com/docs/info/gen_disclaimer.html for more information.
The Finance::YahooQuote module by Dj Padzensky (on the web at http://www.padz.net/~djpadz/YahooQuote/) served as the backbone for data retrieval, and a guideline for the extension to the non-North American quotes which was already very useful for the real-time ticker http://rosebud.sps.queensu.ca/~edd/code/smtm.html.