renamed t-test example file, where it fits in the hierarchy. It's still BROKEN.
[CommonLispStat.git] / README.org
blob3724fb478fc1cb4a309ef070a15d42d5d3f88399
2 Time-stamp: <2012-10-10 05:00:41 tony>
4 * Current Status: SOMEWHAT BROKEN
6   but we are rebuilding it.
9 * Introduction
11 ** Core Philosophy
13   "Languages shape how we ..."   Need to get and insert this quote
14   that Duncan Temple-Lang found.
16   The API should distinguish between the realization and the
17   statistical interpretation.  Goal is to teach statisticians how to
18   think "systems-computationally", and programmers, comp-sci types,
19   informaticists and other "data scientists" how to think
20   "statistically", in order to get a jump on the competition.
22   The goal of this system is to promote a change in thinking, to move
23   the data analysis approach, currently stuck in a mix of 70s-early
24   90s approaches, into a new generation/level.
26 ** Design Philosophy
28    The approach we are taking is one where we provide a general
29    method, and some fundamental building blocks, but don't force users
30    into approaches in order to allow for experimentation.
32    DSL's should be built on top of the core packages, as needed or
33    wanted.  
35    (TonyR:)  The DSL I want to build is a verbose statistically
36    precise computing language, but we need quality code underneathe
37    (which others could use for specialized terse DSL's).
39    DSL: domain specific language.
41 * Fast Start
43 ** Version 2 (David)
45    (This held for the version before we removed liblispstat and plplot
46    and some other "crutches" which had a bit too much bitrot).
48    We assume that you have a lisp installed and that you have a
49    passing acquaintence with the unix shell.
51    1. The first point that you should note that is that these
52       instructions are written with the assumption of the availibility
53       of quicklisp.
55    If you do not have quicklisp , please go to www.quicklisp.org and
56    install it now
58    2. The second point to note is that you will need the "git" utility
59       installed on your machine.
61       for mac osx sudo port install git
62       for linux (eg debian) sudo apt-get install git
64    3. Once that is done execute the following shell commands
66 #+begin_src shell
67   cd ~/quicklisp/local-projects
68   git clone git://github.com/blindglobe/common-lisp-stat.git
69   cd comon-list-stat
70   git submodules init
71 #+end_src
73       These commands copy the the source from the repository and all
74       the associated libraries. It will live as a quicklisp project in
75       the local-projects directory. I find it convenient to
76       symbolically link the quicklisp direct to ~/lisp for easy access
78 #+begin_src shell
79    ln ~/quicklisp/local-projects ~/lisp
80 #+end_src
82    4. Configure the locations of the BLAS and LINPACK libraries
84       Currently this is a manual operation, which will change in a
85       later version.
87       Edit the file external/cl-blapack/load-blapack-libs.lisp
89       Search for the following 3 parameters *gfortran-lib* *blas-lib*
90       *lapack-lib*
92       For OS X: change the parameters as suggested in the file. Both
93       BLAS and LAPACK are pre installed on Mac OSX.
95       For linux, make sure you have the neccessary libraries installed,
96       through apt, yum or otherwise
98       i.e.: 
99 #+BEGIN_SRC shell
100 sudo apt-get install libblas
101 sudo apt-get install liblapack
102 #+END_SRC
104    5. For visualization we are currently using plplot and the
105       cl-plplot interface. this requires the installation of the
106       plplot library
108       for MAC OSX you can use macports or homebrew
110       5.1 sudo port install xquartz (or download from the xquartz home site)
112       5.2 sudo port install plplot
114       and on linux your favourite package manager of course.
116       For windows, we recommend you use cygwin to get straightforward
117       access. I'll document the steps if there is a demand.
119    6. You need to check that your dynamic library path has been
120       properly set up in the shell.  In your .bashrc (or equivalent
121       shell init file)
123       For Mac OSX set 
125 #+BEGIN_SRC 
126 DYLD_FALLBACK-LIBRARY_PATH=$DYLD_FALLBACK_LIBRARY_PATH:/opt/local/lib
127 #+END_SRC
129       For Linux set 
131 #+BEGIN_SRC 
132 LD_LIBRARY_PATH=$LD_LIBRARY_PATH:????
133 #+END_SRC
135       If you get this wrong the load process will not be able to find
136       the libraries and will prompt you.
138    5. Once the pre prequisites have been done, start your favourite lisp
139       and enter 
141 #+begin_src lisp
142 (ql:register-local-projects)
143 (ql:quickload :cls) 
144 #+end_src lisp
146       Retire for a well earned coffee and upon your return you should
147       find the package completely installed.Obviously, potential
148       errors can creep in with spelling the filenames correctly, so be
149       careful.
151 ** Version 1 (Tony)
153   You probably did  (preferred)
155 #+name: LoadWithGitClone
156 #+begin_src shell
157   git clone git://github.com/blindglobe/common-lisp-stat.git
158 #+end_src
160   (or maybe using the repo.or.cz git repository archive), or (coming
161   soon!) from within a Lisp instance:
163 #+name: LoadWithQuickLisp
164 #+begin_src lisp
165   (ql:quickload :cls)
166 #+end_src
168   At one point, I planned a pure git-delivery via cloning and
169   submodules, but this proved to be a bit more complex than needed,
170   thanks to the creation of quicklisp.  It's also a stupid idea if
171   one plans to have users who are not hackers or developers, and
172   eventually we want users.
174   Despite quicklisp, there will need to be a version for delivering a
175   system development-oriented CLS environment and this will consist of
176   git repositories, possibly through submodules, but this (submodules)
177   is for discussion.
179   There are quite a few libraries that are needed, and right now we
180   are working on simplifying the whole thing.   Once you get past
181   this step, then you should:
183   1. run a common lisp (SBCL, CMUCL, CLISP, CLOZURE-CL) starting in
184      the current directory.  You will need ASDF at a minimum,
185      QUICKLISP preferred.  And you should have QUICKLISP.
187   2. (on Debian or similar systems: can use CLC (Common Lisp
188      Controller) or SBCL approaches, i.e.  ~/.clc/systems or
189      ~/.sbcl/systems should contain softlinks to the cls and other
190      required ASDF files (i.e. cls.asd, cffi.asd, and lift.asd).
192   There are example sessions and scripts for data analysis, some real,
193   some proposed, in the file:examples/ directory.  Also see
194   file:TODO.org for snippets of code that work or fail to work.
196 ** Example Usage steps [2/7]
198 *** DONE Start and Load 
199   
200 1. start your lisp
201 2. load CLS
203 #+BEGIN_SRC lisp
204 (ql:quickload :cls)
205 #+END_SRC
207 *** DONE Setup a place to work
209 In Common Lisp, you need to select and setup namespace to store data
210 and functions.  There is a scratch user-package, or sandbox, for
211 CLS, *cls-user* , which you can select via:
213 #+BEGIN_SRC lisp -n :tangle "readme-example.lisp"
214 (in-package :cls-user)
215 #+END_SRC
217 and this has some basic modules from CLS instantiated (dataframes,
218 probability calculus, numerical linear algebra, basic summaries
219 (numerical and visual displays).  
221 However, it can be better is to create a package to work in, which
222 pulls in only desired functionality:
225 #+BEGIN_SRC lisp +n :tangle "readme-example.lisp"
226   (in-package cl-user)
227   (defpackage :my-package-user
228     (:documentation "demo of how to put serious work should be placed in
229       a similar package elsewhere for reproducibility.  This hints as to
230       what needs to be done for a user- or analysis-package.")
231     (:nicknames :my-clswork-user)
232     (:use :common-lisp ; always needed for user playgrounds!
233           :lisp-matrix ; we only need the packages that we need...
234           :common-lisp-statistics
235           :cl-variates
236           :lisp-stat-data-examples) ;; this ensures access to a data package
237     (:shadowing-import-from :lisp-stat
238         ;; This is needed temporarily until we resolve the dependency and call structure. 
239         call-method call-next-method
240   
241         expt + - * / ** mod rem abs 1+ 1- log exp sqrt sin cos tan
242         asin acos atan sinh cosh tanh asinh acosh atanh float random
243         truncate floor ceiling round minusp zerop plusp evenp oddp 
244         < <= = /= >= > > ;; complex
245         conjugate realpart imagpart phase
246         min max logand logior logxor lognot ffloor fceiling
247         ftruncate fround signum cis
248   
249         <= float imagpart)
250   
251     (:export summarize-data summarize-results this-data this-report))
252   
253   (in-package :my-clswork-user) ;; or :my-package-user
254   
255   (setf my-data
256         (let ((var1 )) ))
257   
258 #+END_SRC
260 We need to pull in the packages with data or functions that we need;
261 just because the data/function is pulled in by another package, in
262 that package's namespace, does NOT mean it is available in this name
263 space.  However, the *common-lisp-statistics* package will ensure
264 that fundamental objects and functions are always available. 
267 *** TODO Get to work [0/3]
269 **** TODO Pull in or create data
271 **** TODO Summarize results
273 **** TODO Save work and results for knowledge building and reuse 
275 One can build a package, or save an image (CL implementation
276 dependent) or...
277   
278 *** TODO Inform  moi of problems or successes
280     NEED TO SETUP A MAILING LIST!!
282     mailto:blindglobe@gmail.com if there is anything wrong, or
283     even if something happens to work.
285     Current beliefs:
286     - SBCL is target platform.   CCL and CMUCL should be similar.
287     - CLISP is finicky regarding the problems that we have with CFFI
288       conversation.  In particular that we can not really do typing
289       that we need to take care of.  I think this is my (Tony's)
290       problem, not someone elses, and specifically, not CLISP's
291     - Need to test ECL.
293 * History
295    See files in file:Doc/  for history, design considerations, and
296    random, sometimes false and misleading, musings.
298 * Local modifications, Development, Contributions
300   Since this project is 
302 #+begin_src shell
303 #   git clone git://repo.or.cz/CommonLispStat.git 
304    git clone git://github.com/blindglobe/common-lisp-stat.git 
305    cd common-lisp-stat
306 #   git submodules init
307 #   git submodules update
308 #+end_src
310    will pull the whole repository, and create a "master" branch to
311    work on.  If you are making edits, which I'd like, you don't want
312    to use the master branch, but more to use a topic-centric branch,
313    so you might:
315 #+begin_src shell
316     git checkout -b myTopicBranch
317 #+end_src
319 and then work on myTopicBranch, pulling back to the master branch when
320 needed by
322 #+begin_src shell
323     git checkout master
324     git pull . myTopicBranch
325 #+end_src
328 #+begin_src shell
329     git rebase myTopicBranch
330 #+end_src
333 BETTER DOCUMENTATION EXAMPLES EXIST ON-LINE!! PLEASE READ THEM, THE
334 ABOVE IS SPARSE AND MIGHT BE OUTDATED!
337 ** Contributing through GitHub
339    Alternatively, one can work on the github repositories as well.
340    They are a bit differently organized, and require one to get a
341    github account and work from there.
343    basically, clone the repository on github on the WWW interface,
344    then make a branch (as below), push back the branch to github, and
345    notify the main repository that there is something to be pulled.
346    And we'll pull it back in.
348 ** Commiting with the MOB on repo.or.cz
350 of course, perhaps you want to contribute to the mob branch.   For
351 that, after cloning the repository as above, you would:
353 #+begin_src shell
354     git checkout -b mob remotes/origin/mob
355 #+end_src
357 (work, work, work... through a cycle of
359 #+begin_src shell
360          <edit>
361          git add <files just edited>
362          git commit -m "what I just did"
363 #+end_src
365  ad-nauseum.  When ready to commit, then just:
367 #+begin_src shell
368      git push git+ssh://mob@repo.or.cz/srv/git/CommonLispStat.git mob:mob
369 #+end_src
373 and it'll be put on the mob branch, as a proposal for merging. 
375 Another approach would be to pull from the topic branch into the mob
376 branch before uploading.   Will work on a formal example soon.
378 (the basic principle is that instead of the edit cycle on mob, do
379 something like:
381 #+begin_src shell
382   git checkout mob
383   git pull . myTopicBranch   
384   git push git+ssh://mob@repo.or.cz/srv/git/CommonLispStat.git mob:mob
385 #+end_src
389 ** Licensing
391    Licensing will be important.  Next decade.  But do think through
392    what you intend with your contributions.  Should we become famous
393    (Ha!) make sure that you've communicated your expectations...
395 * Footnotes
397 [fn:1] I´m not including instructions for Emacs or git, as the former
398 is dealt with other places and the latter was required for you to get
399 this.  Since disk space is cheap, I´m intentionally forcing git to be
400 part of this system.  Sorry if you hate it.  Org-mode, org-babel, and
401 org-babel-lisp, and hypo are useful for making this file a literate
402 and interactively executable piece of work.