README This file discusses the Common LISP version of the VOTE program and covers the following topics: * Introduction * The conversion from T to Common LISP * Installation of the program * Getting Started with VOTE * Bugs * Future work I would be happy to hear from you, if you have problems or not. Stephen Slade Information Systems Department Stern School of Business New York University 44 West 4th Street New York, NY 10012 (212) 998-0818 (212) 995-4228 fax sslade@stern.nyu.edu ========================================================================== * Introduction ========================================================================== VOTE is a program which simulates Congressional roll-call voting. It was developed as part of my PhD dissertation at the Yale Computer Science Department. The best description of the underlying theory and the program is found in: Goal-based Decision Making: An Interpersonal Model Stephen Slade Lawrence Erlbaum Associates, 1994. In addition, there is a PostScript file "inside_vote.ps" included in this archive. It contains additional details not found in the Erlbaum book. VOTE embodies a general model of decision making that need not be restricted to political domains. I have had students at Yale apply VOTE to a range of mundane decision problems. At the NYU business school, we are beginning to apply VOTE to a number of traditional and novel business decision problems. The original version of the program was written in the T programming language, which is a version of the Scheme dialect of LISP. The T version is available at this same site in the file vote.t.tar.Z. If you are interested in learning more about T, you may wish to read the following: The T Programming Language: A Dialect of LISP Stephen Slade Prentice-Hall, 1987. ========================================================================== * The conversion from T to Common LISP ========================================================================== In an effort (a) to make VOTE available to a wider audience, and (b) to take advantage of some of the wonderful features found in Common LISP, particularly CLOS, I have undertaken the thankless task of converting VOTE from T to Common LISP. Given that both T and Common LISP are LISP dialects, this should not have been a big deal. Well, guess again. I wrote an awk script that made all obvious changes, e.g., add1 becomes 1+, positive? becomes plusp, etc. However, there still was a lot left over. VOTE took advantage of many of idiosyncratic features of T, which are not found in Common LISP. Therefore, each file had to be reviewed closely after the batch conversion. To get a sense of the types of problems encountered, you may wish to scan the file change.notes which served as a log of the conversion process. The resulting changes were significant and substantial. It is not possible to test all functions under all circumstances. We therefore expect that not every piece of code will be up to par. If unreliable code were not bad enough, I must also state that the comments in the code are likely to be absent. I hope to remedy this in the future. Another caveat is related to Common LISP implementations. We have tested this code on two versions of Common LISP: Macintosh Common LISP (MCL) and Allegro Common LISP (Allegro). We have found subtle incompatibilities which we addressed through the inclusion of implementation specific compatibility files. However, if you are trying to run VOTE using some other LISP dialect, you may encounter some problems. If so, let me know. There may be a solution. ========================================================================== * Installation of the program ========================================================================== At this point, I assume that you have successfully untar'd the tar file. This process created several subdirectories in the current directory. db the database program db/data the data files doc documentation, such as it is gen natural language generation pol VOTE's database definitions and related code utils utility functions In the current directory, you will also find the following files: README this file load_utils.lisp a secondary load file load_vote.lisp the main load file In the doc directory, you will find the following files: change.notes the change history file compile.transcript a detailed transcript of steps 2 through 4 below inside_vote.ps PostScript document describing VOTE's dbs Here is what you need to do. 1. Edit load_vote.lisp, making the changes indicated in the file, mainly indicating the pathname for the vote root directory. 2. Start LISP, and compile the file "myload.lisp", then load the file load_vote.lisp, which in turn will load the rest of the files. 3. In LISP, execute the command (compile-everything) which should compile all the code files. This may take a while and also result in a number of warning messages that you can safely ignore. 4. In LISP, execute the command: (compile-dbs) which should compile all the data files, e.g., for bills and members. This will likewise take a while. 5. Exit LISP. You have now compiled all the code and data. From now on, VOTE will always load the compiled files, recompiling code files as needed, automatically. The data files will be compiled only at the user's request, with the compile command in dbase/tdb. ========================================================================== * Getting Started with VOTE ========================================================================== From now on you may start VOTE simply by starting LISP and executing the following commands: (load "load_vote.lisp") (init-pol) The latter command loads the databases. Listed below are some things to try out when exploring VOTE. - protocol and debugging output To turn on protocol output, execute: (no-output nil) To turn off protocol output, execute: (no-output t) To turn on debugging output, execute: (setf db-format t) To turn off debugging output, execute: (setf db-format nil) - Running one vote: Turn on protocol output, and execute: (vote 'gingrich 'child-care) You may substitute other members for 'Gingrich and other bills for 'child-care. - Running all bills for a given member: Turn off protocol output, and execute: (vote-all 'gingrich) - Running all members for a given bill: Turn off protocol output, and execute: (vote-all 'child-care) - Running all members on all bills: Turn off protocol output, and execute: (vote-all) You may wish to produce statistics on your results using one of the following commands: (analyze-decisions 'gingrich) (analyze-decisions 'child-care) (analyze-decisions) With or without analysis, the voting results are kept in the DECISION database, which you may examine using the command: (dbase decision) The next step is to start to add your own members, bills, issues, and groups. You should now refer to the file inside_vote.ps, which discusses how to use the database program upon which VOTE depends. Unfortunately, inside_vote was written for the T version. However, it should be correct more often than not. ========================================================================== * Bugs ========================================================================== - The French language generation code is not included in this release. - The code lacks proper comments and documentation. ========================================================================== * Future Work ========================================================================== Most of our current research focusses on applying VOTE to other domains, primarily business decisions. That work requires the development of new domain databases (members, bills, issues, groups) and new language facilities. The former is fairly easily done, while the latter is not. Therefore, one near term goal is to create a database for language generation, making it easier to modify and extend the language generation component of VOTE.