compiles again -- fixed function calls, but need to get the generic function signatur...
[CommonLispStat.git] / README.org
blob62beb6e13244b867b645675feb9cf82917ad0a09
2 Time-stamp: <2012-10-08 15:44:30 tony>
4 * Current Status: COMPLETELY BROKEN
6   but we are rebuilding it.
8 * Fast Start
10 ** Version 2 (David)
12    (This held for the version before we removed liblispstat and plplot
13    and some other "crutches" which had a bit too much bitrot).
15    We assume that you have a lisp installed and that you have a
16    passing acquaintence with the unix shell.
18    1. The first point that you should note that is that these
19       instructions are written with the assumption of the availibility
20       of quicklisp.
22    If you do not have quicklisp , please go to www.quicklisp.org and
23    install it now
25    2. The second point to note is that you will need the "git" utility
26       installed on your machine.
28       for mac osx sudo port install git
29       for linux (eg debian) sudo apt-get install git
31    3. Once that is done execute the following shell commands
33 #+begin_src shell
34   cd ~/quicklisp/local-projects
35   git clone git://github.com/blindglobe/common-lisp-stat.git
36   cd comon-list-stat
37   git submodules init
38 #+end_src
40       These commands copy the the source from the repository and all
41       the associated libraries. It will live as a quicklisp project in
42       the local-projects directory. I find it convenient to
43       symbolically link the quicklisp direct to ~/lisp for easy access
45 #+begin_src shell
46    ln ~/quicklisp/local-projects ~/lisp
47 #+end_src
49    4. Configure the locations of the BLAS and LINPACK libraries
51       Currently this is a manual operation, which will change in a
52       later version.
54       Edit the file external/cl-blapack/load-blapack-libs.lisp
56       Search for the following 3 parameters *gfortran-lib* *blas-lib*
57       *lapack-lib*
59       For OS X: change the parameters as suggested in the file. Both
60       BLAS and LAPACK are pre installed on Mac OSX.
62       For linux, make sure you have the neccessary libraries installed,
63       through apt, yum or otherwise
65       i.e.: 
66 #+BEGIN_SRC shell
67 sudo apt-get install libblas
68 sudo apt-get install liblapack
69 #+END_SRC
71    5. For visualization we are currently using plplot and the
72       cl-plplot interface. this requires the installation of the
73       plplot library
75       for MAC OSX you can use macports or homebrew
77       5.1 sudo port install xquartz (or download from the xquartz home site)
79       5.2 sudo port install plplot
81       and on linux your favourite package manager of course.
83       For windows, we recommend you use cygwin to get straightforward
84       access. I'll document the steps if there is a demand.
86    6. You need to check that your dynamic library path has been
87       properly set up in the shell.  In your .bashrc (or equivalent
88       shell init file)
90       For Mac OSX set 
92 #+BEGIN_SRC 
93 DYLD_FALLBACK-LIBRARY_PATH=$DYLD_FALLBACK_LIBRARY_PATH:/opt/local/lib
94 #+END_SRC
96       For Linux set 
98 #+BEGIN_SRC 
99 LD_LIBRARY_PATH=$LD_LIBRARY_PATH:????
100 #+END_SRC
102       If you get this wrong the load process will not be able to find
103       the libraries and will prompt you.
105    5. Once the pre prequisites have been done, start your favourite lisp
106       and enter 
108 #+begin_src lisp
109 (ql:register-local-projects)
110 (ql:quickload :cls) 
111 #+end_src lisp
113       Retire for a well earned coffee and upon your return you should
114       find the package completely installed.Obviously, potential
115       errors can creep in with spelling the filenames correctly, so be
116       careful.
118 ** Version 1 (Tony)
120   You probably did  (preferred)
122 #+name: LoadWithGitClone
123 #+begin_src shell
124   git clone git://github.com/blindglobe/common-lisp-stat.git
125 #+end_src
127   (or maybe using the repo.or.cz git repository archive), or (coming
128   soon!) from within a Lisp instance:
130 #+name: LoadWithQuickLisp
131 #+begin_src lisp
132   (ql:quickload :cls)
133 #+end_src
135   At one point, I planned a pure git-delivery via cloning and
136   submodules, but this proved to be a bit more complex than needed,
137   thanks to the creation of quicklisp.  It's also a stupid idea if
138   one plans to have users who are not hackers or developers, and
139   eventually we want users.
141   Despite quicklisp, there will need to be a version for delivering a
142   system development-oriented CLS environment and this will consist of
143   git repositories, possibly through submodules, but this (submodules)
144   is for discussion.
146   There are quite a few libraries that are needed, and right now we
147   are working on simplifying the whole thing.   Once you get past
148   this step, then you should:
150   1. run a common lisp (SBCL, CMUCL, CLISP, CLOZURE-CL) starting in
151      the current directory.  You will need ASDF at a minimum,
152      QUICKLISP preferred.  And you should have QUICKLISP.
154   2. (on Debian or similar systems: can use CLC (Common Lisp
155      Controller) or SBCL approaches, i.e.  ~/.clc/systems or
156      ~/.sbcl/systems should contain softlinks to the cls and other
157      required ASDF files (i.e. cls.asd, cffi.asd, and lift.asd).
159   There are example sessions and scripts for data analysis, some real,
160   some proposed, in the file:examples/ directory.  Also see
161   file:TODO.org for snippets of code that work or fail to work.
163 ** Example Usage steps [2/7]
165 *** DONE Start and Load 
166   
167 1. start your lisp
168 2. load CLS
170 #+BEGIN_SRC lisp
171 (ql:quickload :cls)
172 #+END_SRC
174 *** DONE Setup a place to work
176 In Common Lisp, you need to select and setup namespace to store data
177 and functions.  There is a scratch user-package, or sandbox, for
178 CLS, *cls-user* , which you can select via:
180 #+BEGIN_SRC lisp -n :tangle "readme-example.lisp"
181 (in-package :cls-user)
182 #+END_SRC
184 and this has some basic modules from CLS instantiated (dataframes,
185 probability calculus, numerical linear algebra, basic summaries
186 (numerical and visual displays).  
188 However, it can be better is to create a package to work in, which
189 pulls in only desired functionality:
192 #+BEGIN_SRC lisp +n :tangle "readme-example.lisp"
193   (in-package cl-user)
194   (defpackage :my-package-user
195     (:documentation "demo of how to put serious work should be placed in
196       a similar package elsewhere for reproducibility.  This hints as to
197       what needs to be done for a user- or analysis-package.")
198     (:nicknames :my-clswork-user)
199     (:use :common-lisp ; always needed for user playgrounds!
200           :lisp-matrix ; we only need the packages that we need...
201           :common-lisp-statistics
202           :cl-variates
203           :lisp-stat-data-examples) ;; this ensures access to a data package
204     (:shadowing-import-from :lisp-stat
205         ;; This is needed temporarily until we resolve the dependency and call structure. 
206         call-method call-next-method
207   
208         expt + - * / ** mod rem abs 1+ 1- log exp sqrt sin cos tan
209         asin acos atan sinh cosh tanh asinh acosh atanh float random
210         truncate floor ceiling round minusp zerop plusp evenp oddp 
211         < <= = /= >= > > ;; complex
212         conjugate realpart imagpart phase
213         min max logand logior logxor lognot ffloor fceiling
214         ftruncate fround signum cis
215   
216         <= float imagpart)
217   
218     (:export summarize-data summarize-results this-data this-report))
219   
220   (in-package :my-clswork-user) ;; or :my-package-user
221   
222   (setf my-data
223         (let ((var1 )) ))
224   
225 #+END_SRC
227 We need to pull in the packages with data or functions that we need;
228 just because the data/function is pulled in by another package, in
229 that package's namespace, does NOT mean it is available in this name
230 space.  However, the *common-lisp-statistics* package will ensure
231 that fundamental objects and functions are always available. 
234 *** TODO Get to work [0/3]
236 **** TODO Pull in or create data
238 **** TODO Summarize results
240 **** TODO Save work and results for knowledge building and reuse 
242 One can build a package, or save an image (CL implementation
243 dependent) or...
244   
245 *** TODO Inform  moi of problems or successes
247     NEED TO SETUP A MAILING LIST!!
249     mailto:blindglobe@gmail.com if there is anything wrong, or
250     even if something happens to work.
252     Current beliefs:
253     - SBCL is target platform.   CCL and CMUCL should be similar.
254     - CLISP is finicky regarding the problems that we have with CFFI
255       conversation.  In particular that we can not really do typing
256       that we need to take care of.  I think this is my (Tony's)
257       problem, not someone elses, and specifically, not CLISP's
258     - Need to test ECL.
260 * History
262    See files in file:Doc/  for history, design considerations, and
263    random, sometimes false and misleading, musings.
265 * Local modifications, Development, Contributions
267   Since this project is 
269 #+begin_src shell
270 #   git clone git://repo.or.cz/CommonLispStat.git 
271    git clone git://github.com/blindglobe/common-lisp-stat.git 
272    cd common-lisp-stat
273 #   git submodules init
274 #   git submodules update
275 #+end_src
277    will pull the whole repository, and create a "master" branch to
278    work on.  If you are making edits, which I'd like, you don't want
279    to use the master branch, but more to use a topic-centric branch,
280    so you might:
282 #+begin_src shell
283     git checkout -b myTopicBranch
284 #+end_src
286 and then work on myTopicBranch, pulling back to the master branch when
287 needed by
289 #+begin_src shell
290     git checkout master
291     git pull . myTopicBranch
292 #+end_src
295 #+begin_src shell
296     git rebase myTopicBranch
297 #+end_src
300 BETTER DOCUMENTATION EXAMPLES EXIST ON-LINE!! PLEASE READ THEM, THE
301 ABOVE IS SPARSE AND MIGHT BE OUTDATED!
304 ** Contributing through GitHub
306    Alternatively, one can work on the github repositories as well.
307    They are a bit differently organized, and require one to get a
308    github account and work from there.
310    basically, clone the repository on github on the WWW interface,
311    then make a branch (as below), push back the branch to github, and
312    notify the main repository that there is something to be pulled.
313    And we'll pull it back in.
315 ** Commiting with the MOB on repo.or.cz
317 of course, perhaps you want to contribute to the mob branch.   For
318 that, after cloning the repository as above, you would:
320 #+begin_src shell
321     git checkout -b mob remotes/origin/mob
322 #+end_src
324 (work, work, work... through a cycle of
326 #+begin_src shell
327          <edit>
328          git add <files just edited>
329          git commit -m "what I just did"
330 #+end_src
332  ad-nauseum.  When ready to commit, then just:
334 #+begin_src shell
335      git push git+ssh://mob@repo.or.cz/srv/git/CommonLispStat.git mob:mob
336 #+end_src
340 and it'll be put on the mob branch, as a proposal for merging. 
342 Another approach would be to pull from the topic branch into the mob
343 branch before uploading.   Will work on a formal example soon.
345 (the basic principle is that instead of the edit cycle on mob, do
346 something like:
348 #+begin_src shell
349   git checkout mob
350   git pull . myTopicBranch   
351   git push git+ssh://mob@repo.or.cz/srv/git/CommonLispStat.git mob:mob
352 #+end_src
356 ** Licensing
358    Licensing will be important.  Next decade.  But do think through
359    what you intend with your contributions.  Should we become famous
360    (Ha!) make sure that you've communicated your expectations...
362 * Footnotes
364 [fn:1] I´m not including instructions for Emacs or git, as the former
365 is dealt with other places and the latter was required for you to get
366 this.  Since disk space is cheap, I´m intentionally forcing git to be
367 part of this system.  Sorry if you hate it.  Org-mode, org-babel, and
368 org-babel-lisp, and hypo are useful for making this file a literate
369 and interactively executable piece of work.