README for bsr_analysis

This is the code used with the Greg Kochanski and Burton S. Rosner 2009 paper
"Maximum Likelihood Solutions for The Law of Categorical Judgment (Corrected)".
(The previous release said that also, but we mean it this time.)

The .pyx code here compiles with Cython version 0.11 .
The C++ code (.cpp) compiles with gcc-4.3.3 .
Python runs on python-2.5.4.

Contents:
-rw-rw-r--   1 gpk      gpk           380 Jul 13 15:12 ./README.txt
This file.

-rwxrwxr-x   1 gpk      gpk          3611 Jun  2 12:46 ./bin/bsr_analysis.py
The main program for running the analysis.


-rw-rw-r-- 1 gpk phonstaff  903 2009-07-15 10:55 ./test/cs500sa.mcmci
-rw-rw-r-- 1 gpk phonstaff 5170 2009-07-15 10:55 ./test/cs500sa.mcmco
-rw-rw-r-- 1 gpk phonstaff  914 2009-07-15 10:55 ./test/fs500sa.mcmci
-rw-rw-r-- 1 gpk phonstaff 5300 2009-07-15 10:55 ./test/fs500sa.mcmco
-rw-rw-r-- 1 gpk phonstaff  889 2009-07-15 10:55 ./test/sd500sa.mcmci
-rw-rw-r-- 1 gpk phonstaff 5343 2009-07-15 10:55 ./test/sd500sa.mcmco
Input files (.mcmci) and output files (.mcmco) for test runs.

-rw-rw-r--   1 gpk      gpk          2348 Jun  2 12:45 ./lib/lawcjcrk.h
-rw-rw-r--   1 gpk      gpk         40253 Jun  2 12:45 ./lib/lawcjcrk.cpp
-rw-rw-r--   1 gpk      gpk           358 Jun  2 12:45 ./lib/stats.h
-rw-rw-r--   1 gpk      gpk           131 Jun 22 23:00 ./lib/wsd.h
Problem-specific module and header files.

-rw-rw-r--   1 gpk      gpk          4527 Jun  2 12:45 ./lib/bsr_analysis_guts.pyx
Cython code to interface the C++ problem-specific module to the AMCMC algorithm.

-rw-rw-r--   1 gpk      gpk           144 Jun  2 12:45 ./MANIFEST.in
List of contents.

-rw-rw-r--   1 gpk      gpk          6713 Jun  2 12:45 ./valgrind-python.supp
Code for use with "valgrind" for debugging purposes.

-rw-rw-r--   1 gpk      gpk          1788 Jul 13 14:43 ./setup.py
Code for the python distutils module.   This is used for installing the package
and for creating a distribution.  To install, run

python setup.py install

or (if you want to install somewhere other than the default location)

python setup.py install --prefix=$HOME/local

If you do so, make sure that $HOME/local/lib/pythonVERSION/site-packages
is on the PYTHONPATH.


Before you install this, you need to install numpy (Numerical Python, from
http://scipy.org ).   This package is now (2009) standard in most Linux
python distributions.
Also, you need the the "gmisclib" and "gpklib" packages
from the Sourceforge "speechresearch" project.   (This code should also be
available under http://www.phon.ox.ac.uk .)
After the download, do this:

tar xvzf SOMEWHERE/gmisclib-VERSION.tar.gz
tar xvzf SOMEWHERE/gpklib-VERSION.tar.gz

First, go to the gpklib folder and follow the directions in
that README file.    You need to select three files (to adjust for one
flavour or another of Linux), then run "make" and "make install".

Then, go to the gmisclib folder and run

python setup.py install

or

python setup.py install --prefix=$HOME/local




RUNNING THE TEST CODE
At the head of lawcjcrk.cpp is a description of the input file required by
the program. You should examine one of the input files (*.mcmci) as you read
the description. The input file is the only one required by the program. It
creates its own output file with the same name as the input file but with
extension .mcmco.

The output file includes the maximum likelihood parameters with their
confidence limits, the theoretical probabilities with their
confidence limits, and measures of goodness of fit. The sample output
files do not include the Kullback-Leibler divergence measure, but
lawcjcrk.cpp does compute it and write it now.

Here is a shell script for running the program, after it has been set up as 
described above. Replace  "burton" with your user name. Replace  "bsr"
in the script with a directory name of your own. 

To run the program, do

./runbsr.sh FILENAME

where FILENAME is the name without any extension of your .mcmci file.

----------------------------------------------------------------

#!/bin/sh

source /users/burton/.bashrc
source /users/burton/cgo.sh

cd /users/burton/bsr/bin


python bsr_analysis.py $*

----------------------------------------------------------------

A script that is useful for submitting a run to a grid engine:

----------------------------------------------------------------
#!/bin/sh


source /users/burton/.bashrc
source /users/burton/cgo.sh


#$ -cwd

python bsr_analysis.py $*


----------------------------------------------------------------




HACKING THE CODE:
One thing that many people will want to change is the number of logged
samples.   This is the NSAMP variable at the top of bin/bsr_analysis.py .
