Links: Tom Edelson's home page; Tom Edelson's LiveJournal
The purpose of this document is to help you to decide whether my "Asset Allocation Report" software ("ASAL", for short) might be useful to you: that is, whether it might be helpful in managing your investments.
There is a parallel document to this one, called "Information for Programmers". It also addresses the question of whether the reader might want to download the ASAL software; but it is addressed to a different audience, who might want it for quite different reasons (namely, because they might learn something by studying its "source code" (the actual program), that might help them in writing other programs). If you are a prospective "end user", meaning that you [might] want to use the software to manage your investments, and don't care about how it works "under the hood", then you shouldn't have to look at the "Information for Programmers". But you're certainly welcome to, if you're curious.
This document for end users, and the other document for programmers, have a common introduction, titled simply "My Asset Allocation Report Software". It outlines what an "asset allocation report" is, at a basic level; and it is intended to be read before reading either this user document or the programmer document. So if you didn't come here from there, it would probably be helpful to read that introductory document now.
I don't want to mislead anyone: I think this software does something very useful, but (in its current state, and from an end user perspective), it's not terribly easy to use. I want you to make an informed choice as to whether to try it now ... or wait until it's more polished ... or forget about it. Accordingly, a summary of the rest of this article is as follows:
In the section titled "The Sales Talk", I tell you the good stuff: why I think the information provided by my Asset Allocation Report is useful, and, in particular, why I think that it's better than other "asset allocation information" that you may already be receiving (for example, from your broker(s)).
In the section titled "The Fine Print", I tell you the two ways in which I think that it is [currently] harder to use than it should be.
And in the "Conclusion", I suggest how to communicate with me about your interest in it (if any). (Communicating with me would be the next step, if you do have an interest, because, as mentioned in the introductory document, the software has not yet been released.)
If you invest through a broker, they probably send you a monthly statement which provides, among many other things, some information about how your assets are allocated. I have found such broker-provided asset allocation information not sufficient for my needs, for (at least) the following reasons:
If you have more than one account with the same broker (for example, a taxable account and an IRA (Individual Retirement Arrangement)), the broker may, or may not, give you asset allocation information on a consolidated basis, that is, for all your accounts taken together.
If you have more than one account with different brokers, it is very unlikely that anyone is supplying you with asset allocation information on a consolidated basis, that is, information about the securities held in all of your accounts, taken together.
When financial institutions provide asset allocation information, they often show how your funds are distributed among a list of asset classes which includes stocks (but only individual ones), bonds (again, only individual bonds that you own directly), and mutual funds. You may prefer, as I do, not to regard mutual funds as a separate class: to combine stock mutual funds with individual stocks, and bond mutual funds with individual bonds. That is, you may want to know how your assets are divided between stocks and bonds, without regard to whether you own them directly or indirectly.
Finally, what if you own shares in a mutual fund, which in turn divides its own investments between stocks and bonds? (Some such funds are referred to as "balanced" funds.) It is very unlikely, if my experience is any guide, that the asset allocation information provided by a broker will take account of this properly. What (I would assume) you want in this case is to have the money you have invested in such a fund show up partly under stocks and partly under bonds, in proportion to how the mutual fund invests its own assets.
My Asset Allocation Report software meets all of these needs.
It also does one useful thing that doesn't really fall under the category of asset allocation. What if you own shares of the same security in more than one account (whether those accounts be with the same broker, or not)? Wouldn't it be nice to know how many shares of, say, Acme Corporation you own, in total? This software offers a sort of auxiliary report which gives you that information, for each security, including not only the number of shares, but also the total value of those shares at the current price.
It doesn't currently also tell you what percentage of your total assets is invested in that one security, but that would be easy to add if someone is interested.
This section explains how, from the point of view of a typical computer user, my Asset Allocation Report software (as it stands at present) is difficult to use. But first, I need to give you just a little bit of background information, which will help you to understand the difficulties ... and which is also something you need to know, anyway, in order to know whether this ASAL program is something you could use.
The software gets most of the information it needs from your personal finance program ("PFP", for short), so one of its requirements is that you have one of its supported PFPs, and use that program to record investment transactions, including security prices. ("Supported PFP" is programmer talk for "PFP that my ASAL software knows how to work with.")
And what are the supported PFPs? At present, there are two of them: jGnash and Moneydance. Only certain versions of each are supported; for those details, see the "System Requirements" document.
So to get my wonderful Asset Allocation Report, you have to be a user of either jGnash or Moneydance (either already, or willing to become one). If that doesn't scare you off, then keep reading and I will tell you the reasons why, even if you've conscientiously entered all possible relevant data into jGnash or Moneydance, getting an ASAL report is still not as easy as it should be. It's difficult in two ways, that I know of:
There's no GUI (graphical user interface) with which you can tell your computer to run the ASAL program. In order to "launch" this program, you have to type some commands in a "terminal window"; and it seems safe to predict that, to most non-programmers, these commands will be cryptic and hard to remember.
Even before that, you have to prepare a special "control file", from which ASAL gets certain information about the securities you own: information which it can't get from your PFP, because your PFP doesn't have it. The format of the control file will also look cryptic, to someone without any technical background.
The first of these tasks, the commands to launch the program, has to be performed each time you run the program: that is, each time you want to produce a new asset allocation report, reflecting the latest data.
The second task, preparing the control file, is something you don't need to do as often. You could get away with doing it just once and then forgetting about it; you'd get more accurate results if you did change it occasionally, but there's no reason to do it every time you run the program, because the information that you put into the control file doesn't change (at least not significantly) nearly as often as does other information which the ASAL program needs, and which it can get directly from your PFP.
Now my "ASAL" is not "part of" either jGnash or Moneydance. How, then, can it get access to the data which is "owned" by one of those programs? (We say that the data is owned by the PFP because it is stored in a format which is particular to that PFP.)
One possible answer to that is that the PFP could export the information into a file which has some known format, and ASAL could read it from that file. But that's not how ASAL works. It is designed to get the information from the PFP's "internal" data: data kept, not on disk, but in the volatile memory of the computer, and which is present there only while the PFP is running.
A second possibility, which would have achieved this effect: I could have written the ASAL report software as a "script". A script, once installed, looks to the user as if it were part of the application that "hosts" it: in this case, your PFP (jGnash or Moneydance). That would be easier to use; in a perfect world, I would have written it that way.
But I didn't. Why not? Because in order to do so, I would first have to have made some sizeable changes in the "host programs" themselves: jGnash and Moneydance. They would need to be enhanced in order to "support" (there's that word again) scripts like ASAL.
What to I mean by "scripts like ASAL"? ASAL is written in a particular programming language, called SISC. So "scripts like ASAL" effectively means, here, other scripts written in the same language.
So, since running ASAL as a script is not an option, today, how do you run it? Essentially you take the process of running it as a script, and turn that process upside down. The user starts a program called the "SISC interpreter", or just "SISC" for short, and tells it to run ASAL. The first major thing that ASAL does is to launch jGnash 1, or Moneydance: generically, "your PFP" (personal finance program). Then it tells your PFP to give it the data it needs, crunches those numbers, and produces its report.
And this is the first reason why ASAL would have to be considered something less than maximally "user-friendly". Users today expect to have a graphical user interface which shows them the actions that a program is able to perform for them, so that they can just select from a menu or click on an icon. They don't expect to have to remember a series of commands, which have to be typed just so, and which don't look much like English.
Here's one example of what the commands to run the asset allocation report might look like. They could vary, depending on the type of computer (e.g. Macintosh or Windows), and what "set-up" may have been done to prepare the program for use. This is how I currently do it, on a Macintosh, taking the data from jGnash:
. $alloc/jgnash/jg-setup siscjg (load "/Users/edelsont/projects/finance/investing/asset-allocation/jgnash/jg-asset-allocation.scm") (asal "sample-report")
Some of that I would probably paste in from another window, rather than actually type it. Still, with that understood, the four lines above are all input from the user; they don't include the prompts, or other output from the computer. (The first two lines launch the SISC "interpreter" program; the remaining two are read and executed by that program, with the effect of producing an asset allocation report in a file named "sample-report-jg.lis".)
If you were determined enough, and good enough at following directions precisely, you could do this without actually knowing anything about SISC. That is, you could follow a "cheat sheet" which contained notations like "replace this with the location of your PFP's data file". You can judge for yourself whether this is something you would be willing to undertake.
As I said, that's about half of the reason why ASAL is hard to use. What's the other half?
This stems from the fact that ASAL needs, for each security than you own, one piece of information that your PFP (jGnash or Moneydance) can't provide: the asset class. (Or, in the case of a mutual fund which invests in both stocks and bonds, the mix of asset classes: what percent of this mutual fund is invested in stocks, and what percent in bonds.) Your PFP can't give you this information because your PFP has no provision for entering or storing this information.
So where can ASAL get it? Answer: you must create a small file, specifically for use by ASAL, which contains it. This must be a "plain text" file, meaning that you will use a "text editor" to create it: for example, Notepad (on Windows), TextEdit (on Mac OS X), or Emacs (anywhere).
Furthermore, this plain text file needs to have a very specific "syntax", or structure. Here's a sample entry from one such file; specifically, this is how you would tell ASAL that the Pax World Balanced Fund (currently) invests 73% of its assets in stocks, and 26% in bonds (and thus, by implication, 1% in "other", probably something considered equivalent to cash):
(|^Pax World| "Pax World Balanced Fund" ((stocks . 73) (bonds . 26)) )
If you had written programs in the language understood by the SISC interpreter (or in some similar, "Lisp-like" language), this format would probably look at least somewhat familiar. Otherwise, not so much.
Just as with the commands to launch the program, so also with creating or editing this "control file": given a cheat sheet, you might well be able to do it without really knowing anything about SISC. I suspect, though, that most people wouldn't really want to. (But maybe you could hire someone to do it for you ....)
If you'd like a more detailed understanding of why ASAL is the way that it is, then perhaps you're one of those people who would benefit from looking at the "Information for Programmers" document, as well as this one.
So, my Asset Allocation Report program, as it currently stands, might scare some people off. If you're not one of those people, let me know. I'll be happy to write up some detailed instructions and let you give it a try.
If you'd like to use the program, but not until it's made more user-friendly, let me know that, too. Given the two main points of difficulty described in "The Fine Print", making it more user-friendly would consist mostly of:
making it easier to launch the program; and
making it easier to create and maintain the "control file", which supplies ASAL with information about the asset class(es) to which each individual security belongs.
What are the prospects of my doing these things?
For the first one, making it easier to launch ASAL: provided that, say, a half-dozen people are interested ... the prospects are pretty good. This would be mostly a matter of making jGnash, and/or Moneydance, able to run programs like this one (in other words, SISC programs) as "scripts"; and this would have advantages beyond being able to run this particular report program. (So, if you are interested, one of the things you should let me know is which personal finance program you are using.)
I'm not so sure how readily I could, or would, make it a lot easier to create and maintain the "control file". But ... well, I'll just say again: if you're interested in using the program, let me know. If enough people are interested, we'll work something out.
What's that? You're asking how to let me know? That's easy: send me an email. My email address? Take the username "edelsont", and put it together with the domain "well.com".
I look forward to hearing from you.
This page created: 2010-11-02
This page last modified: 2010-11-10
© Copyright 2010 by Tom Edelson.