WHOMP? What's that?

A few years ago, I was a member of a small investment club. Through some defect in my character, or perhaps because I didn't duck fast enough, I was elected treasurer, and thus I had the task of generating a financial report each month. I did that by hand for a while, but it got tedious... so I wrote myself a small set of perl programs to do most of the grunt work for me. That's what this is.

WHOMP was the name of our club; it stands for "We Hope Our Money Performs". All in all, I would have to say we (or at least I) did fantastically well with this club: over about five years, 1998 to 2003, we managed to lose no more than about 10% of our money (that part's not so great, but not too terrible considering we, like everyone else, invested in such temporarily-stellar performers as Lucent and Cisco) and, when we shut down in October 2003, I took away the lesson that broad-based index funds are the way to go (that's the fantastically good part, in my humble opinion). Are you sure you don't want to go with index funds yourself?

image of sample report Ok, then... here is an image of a sample report (the actual generated report is a TeX/postscript file, so it's nice and clean and will print very well). If you think something like this might be useful for your investment club, read on!

Before you go any farther, a disclaimer: there is NO WARRANTY on this software. It is your responsibility to verify the accuracy of your financial transactions and records. Just so we're clear on that. Also, all of the numbers in the example are fake: I have made up numbers for 2005 and 2006, and my crystal ball is no better than yours (and may well be worse). And another disclaimer: I originally wrote this solely for my own use, and initially with no intention of releasing it. So there are some fragilities there, and some things are more hard-wired than they probably ought to be. But it all worked well for me for several years, and the difference between my reckoning and our broker's was never more than a penny or two... close enough for our simple needs! It may be adequate for you as well.

With that out of the way, here's what you'll need to make this work:

The last two are only necessary if you want to generate plots of your portfolio's value over time (but that's half the fun, so make sure those are present too). You'll also need to be comfortable with running perl and shell scripts from a command-line, and editing text files; basically, you probably need to be a geek (like I am).

I have only ever used this on a Linux-based computer, where all of this stuff is easily available; I don't know of any reason though why it couldn't work on a Windows-based computer or a Macintosh.

All right: you've downloaded and installed all the software, now what? First, have a look at the files 200501.keep, which is the initial state file describing the state of the club's finances as of January 15, 2005, and 200501.changes, which is the file describing transactions and changes in the club's portfolio. The format of these files is described in comments in the files themselves, and also in comments inside the perl script whomper. The basic idea is that you are maintaining a database of your club's transactions over time in a bunch of files. The *.changes files are your responsibility: you enter text into each month's file to describe what happened that month. The *.state files are updated by the whomper script. You can run that directly by hand, but you're better off sticking it into a shell script, so that you can easily keep track from month to month.

Here is the shell script which I used for the examples I made up, and here are the initial state file and all the changes files for the example. There are transactions in essentially all months, but I've noted a few of the more interesting ones.

Here are images of all the reports that get generated from them: Here is the file in which we keep track of the cost basis for each stock we own (this is one of the more-fragile parts of the system).

Once you're ready to start generating your own reports, open the script whomper in your favorite text editor, and navigate down to about line 198, where you'll see something like

# who are the members?
my %full_name = (
      'Alice' => 'Alice Carroll',
      'Bob' => 'Bob Steelward',
      'Chuck' => 'Charles Rhoste',
      'Dude' => 'Dudley Dooright',
      'Eve' => 'Eve Eden',
      'Uwe' => 'Uwe Hollerbach'
);
Edit this list of names to reflect your own club's membership, then generate your own initial state file, and then each month generate a changes file, and you're off! If a new member joins your club, just add him or her into this list of names, and carry on; there's no need to add the new member to old state files. Good luck and successful investing!

If you have questions or comments or bug reports, or better yet patches for bugs or enhancements, send them to me at the email address below.

Enjoy!

Uwe Hollerbach
<korg@korgwal.com>