This file will work better with org-mode and David Ito´s org-babel-lisp. Along those lines, please note his hypo approach to literate programming for gaming, as an org-babel extension. [fn:1] . That approach describes a literate approach for describing games, but clearly is no different than the literate approaches described for data analysis, which is just another game.

Fast Start

Common Lisp Stat is a very rich and mature framework for data exploration and visualisation using statistics with the Common Lisp Environment.

This design choice gives a number of advantages - both in the ability to create fast running code, as well as being able to express complex algorithms in a powerful and consistent language.

However, as with all large complex things, setup requires a few steps.

We assume that you have a lisp installed and that you have a passing acquaintence with the unix shell.

1. The first point that you should note that is that these instructions

are written with the assumption of the availibility of quicklisp.

If you do not have quicklisp , please go to www.quicklisp.org and install it now

1. The second point to note is that you will need the “git” utility

installed on your machine.

for mac osx sudo port install git for linux (eg debian) sudo apt-get install git

1. Once that is done execute the following shell commands

cd ~/quicklisp/local-projects
git clone git://github.com/blindglobe/common-lisp-stat.git
cd comon-list-stat
git submodules init

These commands copy the the source from the repository and all the associated libraries. It will live as a quicklisp project in the local-projects directory. I find it convenient to symbolically link the quicklisp direct to ~/lisp for easy access

ln ~/quicklisp/local-projects ~/lisp

1. Configure the locations of the BLAS and LINPACK libraries

For MacOS, we will use the pre installed libraries

For linux, make sure you have the neccessary libraries installed, through apt, yum or otherwise viz

viz sudo apt-get install libblas, sudo apt-get install liblapack

1. For visualization we are currently implementing a gnuplot interface, stay tuned.

For windows, we recommend you use cygwin to get straightforward access. I’ll document the steps if there is a demand.

1. You need to check that your dynamic library path has been properly set up in the shell.

In your .bashrc (or equivalent shell init file) For Mac OSX set DYLD_FALLBACK-LIBRARY_PATH=$DYLD_FALLBACK_LIBRARY_PATH:/opt/local/lib For Linux set LD_LIBRARY_PATH=$LD_LIBRARY_PATH:????

If you get this wrong the load process will not be able to find the libraries and will prompt you.

1. Once the pre prequisites have been done, start your favourite lisp and enter

(ql:register-local-projects)
(ql:quickload :cls) 

Retire for a well earned coffee and upon your return you should find the package completely installed.Obviously, potential errors can creep in with spelling the filenames correctly, so be careful.

Example Usage steps

change directory into the CommonLispStat working directory.

start your lisp

follow the commands in the ls-demo.lisp (need to add link) file, i.e.

(ql:quickload :cls)

(in-package :cls)

Initially we will work in the cls package as all the basic functions we would need are present

For serious work we would create our own workspace and save it in a separate package, but for now we will take this short cut.

(normal-rand 20)

(setf mytest (normal-rand 20))

… (and so on) …

and see if they work (basic CFFI functionality for external C library, LIFT package for unit-testing framework to ensure run time stability).

Inform moi of problems or successes

mailto:[email protected] if there is anything wrong, or even if something happens to work.

Current beliefs:

• CMUCL and SBCL seem to work just fine at this stage.
• CLISP is finicky regarding the problems that we have with CFFI conversation. In particular that we can not really do typing that we need to take care of. I think this is my problem, not someone elses.
• Need to test ECL. Clozure-CL seems to work.

History

See Doc/README* for history and design considerations See Doc/INSTALL for getting this to work and run

Working on your own modifications

git clone git://repo.or.cz/CommonLispStat.git 
cd CommonLispStat
git submodules init
git submodules update

will pull the whole repository, and create a “master” branch to work on. If you are making edits, which I’d like, you don’t want to use the master branch, but more to use a topic-centric branch, so you might:

git checkout -b myTopicBranch

and then work on myTopicBranch, pulling back to the master branch when needed by

git checkout master
git pull . myTopicBranch

(or

git rebase myTopicBranch

)

of course, perhaps you want to contribute to the mob branch. For that, after cloning the repository as above, you would:

git checkout -b mob remotes/origin/mob

(work, work, work… through a cycle of

       <edit>
	 git add <files just edited>
	 git commit -m "what I just did"

ad-nauseum. When ready to commit, then just:

git push git+ssh://[email protected]/srv/git/CommonLispStat.git mob:mob

)

and it’ll be put on the mob branch, as a proposal for merging.

Another approach would be to pull from the topic branch into the mob branch before uploading. Will work on a formal example soon.

(the basic principle is that instead of the edit cycle on mob, do something like:

git checkout mob
git pull . myTopicBranch   
git push git+ssh://[email protected]/srv/git/CommonLispStat.git mob:mob

)

Alternatively, one can work on the github repositories as well. They are a bit differently organized, and require one to get a github account and work from there. In that case, you’d need to D/L the libraries.

That gets a bit tricky, but see ./bin/GetRepos.sh for an example.

Documentation and examples

I’ve started putting examples of use in function documentation. If you are a lisp’er, you’ll find this pendantic and insulting. Many of the uses are trivial. However, this has been tested out on a number of research statisticians (the primary user audience) and found useful.

Still need to write the (run-doc-ex ‘function-name) function, which would print out the example and run it live. Hopefully with the same results. I’ve used XML markup for this, but for no particular reason, we could have used SEXPs as well. This is currently done by using an <example> tag set, as in

<example>
(progn
  (example-code-for-function))
</example>

Footnotes

[fn:1] I´m not including instructions for Emacs or git, as the former is dealt with other places and the latter was required for you to get this. Since disk space is cheap, I´m intentionally forcing git to be part of this system. Sorry if you hate it. Org-mode, org-babel, and org-babel-lisp, and hypo are useful for making this file a literate and interactively executable piece of work.