README.org

   1
   2 Time-stamp: <2012-10-05 04:19:12 tony>
   3
   4 * Current Status: COMPLETELY BROKEN
   5
   6   but we are rebuilding it.
   7
   8 * Fast Start
   9
  10   You probably did  (preferred)
  11
  12 #+name: GitClone
  13 #+begin_src shell
  14   git clone git://github.com/blindglobe/common-lisp-stat.git
  15 #+end_src
  16
  17   or (coming soon!) from within a Lisp instance,
  18
  19 #+name: QuickLispLoad
  20 #+begin_src lisp
  21   (ql:quickload :cls)
  22 #+end_src
  23
  24   At one point, I planned a pure git-delivery via cloning and
  25   submodules, but this proved to be a bit more complex than needed,
  26   thanks to the creation of quicklisp.  It's also a stupid idea if
  27   one plans to have users who are not hackers or developers, and
  28   eventually we want users.
  29
  30   Despite quicklisp, there will need to be a version for delivering a
  31   system development-oriented CLS environment and this will consist of
  32   git repositories, possibly through submodules, but this (submodules)
  33   is for discussion.
  34
  35   There are quite a few libraries that are needed, and right now we
  36   are working on simplifying the whole thing.   Once you get past
  37   this step, then you should:
  38
  39   1. run a common lisp (SBCL, CMUCL, CLISP, CLOZURE-CL) starting in
  40      the current directory.  You will need ASDF at a minimum,
  41      QUICKLISP preferred.  And you should have QUICKLISP.
  42
  43   2. (on Debian or similar systems: can use CLC (Common Lisp
  44      Controller) or SBCL approaches, i.e.  ~/.clc/systems or
  45      ~/.sbcl/systems should contain softlinks to the cls and other
  46      required ASDF files (i.e. cls.asd, cffi.asd, and lift.asd).
  47
  48   There are example sessions and scripts for data analysis, some real,
  49   some proposed, in the file:examples/ directory.  Also see
  50   file:TODO.org for snippets of code that work or fail to work.
  51
  52 ** Example Usage steps [2/7]
  53
  54 *** DONE Start and Load
  55
  56 1. start your lisp
  57 2. load CLS
  58
  59 #+BEGIN_SRC lisp
  60 (ql:quickload :cls)
  61 #+END_SRC
  62
  63 *** DONE Setup a place to work
  64
  65 In Common Lisp, you need to select and setup namespace to store data
  66 and functions.  There is a scratch user-package, or sandbox, for
  67 CLS, *cls-user* , which you can select via:
  68
  69 #+BEGIN_SRC lisp -n :tangle "readme-example.lisp"
  70 (in-package :cls-user)
  71 #+END_SRC
  72
  73 and this has some basic modules from CLS instantiated (dataframes,
  74 probability calculus, numerical linear algebra, basic summaries
  75 (numerical and visual displays).
  76
  77 However, it can be better is to create a package to work in, which
  78 pulls in only desired functionality:
  79
  80
  81 #+BEGIN_SRC lisp +n :tangle "readme-example.lisp"
  82   (in-package cl-user)
  83   (defpackage :my-package-user
  84     (:documentation "demo of how to put serious work should be placed in
  85       a similar package elsewhere for reproducibility.  This hints as to
  86       what needs to be done for a user- or analysis-package.")
  87     (:nicknames :my-clswork-user)
  88     (:use :common-lisp ; always needed for user playgrounds!
  89           :lisp-matrix ; we only need the packages that we need...
  90           :common-lisp-statistics
  91           :cl-variates
  92           :lisp-stat-data-examples) ;; this ensures access to a data package
  93     (:shadowing-import-from :lisp-stat
  94         ;; This is needed temporarily until we resolve the dependency and call structure.
  95         call-method call-next-method
  96
  97         expt + - * / ** mod rem abs 1+ 1- log exp sqrt sin cos tan
  98         asin acos atan sinh cosh tanh asinh acosh atanh float random
  99         truncate floor ceiling round minusp zerop plusp evenp oddp
 100         < <= = /= >= > > ;; complex
 101         conjugate realpart imagpart phase
 102         min max logand logior logxor lognot ffloor fceiling
 103         ftruncate fround signum cis
 104
 105         <= float imagpart)
 106
 107     (:export summarize-data summarize-results this-data this-report))
 108
 109   (in-package :my-clswork-user) ;; or :my-package-user
 110
 111   (setf my-data
 112         (let ((var1 )) ))
 113
 114 #+END_SRC
 115
 116 We need to pull in the packages with data or functions that we need;
 117 just because the data/function is pulled in by another package, in
 118 that package's namespace, does NOT mean it is available in this name
 119 space.  However, the *common-lisp-statistics* package will ensure
 120 that fundamental objects and functions are always available.
 121
 122
 123 *** TODO Get to work [0/3]
 124
 125 **** TODO Pull in or create data
 126
 127 **** TODO Summarize results
 128
 129 **** TODO Save work and results for knowledge building and reuse
 130
 131 One can build a package, or save an image (CL implementation
 132 dependent) or...
 133
 134 *** TODO Inform  moi of problems or successes
 135
 136     NEED TO SETUP A MAILING LIST!!
 137
 138     mailto:blindglobe@gmail.com if there is anything wrong, or
 139     even if something happens to work.
 140
 141     Current beliefs:
 142     - SBCL is target platform.   CCL and CMUCL should be similar.
 143     - CLISP is finicky regarding the problems that we have with CFFI
 144       conversation.  In particular that we can not really do typing
 145       that we need to take care of.  I think this is my (Tony's)
 146       problem, not someone elses, and specifically, not CLISP's
 147     - Need to test ECL.
 148
 149 * History
 150
 151    See files in file:Doc/  for history, design considerations, and
 152    random, sometimes false and misleading, musings.
 153
 154 * Local modifications, Development, Contributions
 155
 156 #+begin_src shell
 157    git clone git://repo.or.cz/CommonLispStat.git
 158    cd CommonLispStat
 159 #   git submodules init
 160 #   git submodules update
 161 #+end_src
 162
 163    will pull the whole repository, and create a "master" branch to
 164    work on.  If you are making edits, which I'd like, you don't want
 165    to use the master branch, but more to use a topic-centric branch,
 166    so you might:
 167
 168 #+begin_src shell
 169     git checkout -b myTopicBranch
 170 #+end_src
 171
 172 and then work on myTopicBranch, pulling back to the master branch when
 173 needed by
 174
 175 #+begin_src shell
 176     git checkout master
 177     git pull . myTopicBranch
 178 #+end_src
 179
 180 (or
 181 #+begin_src shell
 182     git rebase myTopicBranch
 183 #+end_src
 184 )
 185
 186 of course, perhaps you want to contribute to the mob branch.   For
 187 that, after cloning the repository as above, you would:
 188
 189 #+begin_src shell
 190     git checkout -b mob remotes/origin/mob
 191 #+end_src
 192
 193 (work, work, work... through a cycle of
 194
 195 #+begin_src shell
 196          <edit>
 197          git add <files just edited>
 198          git commit -m "what I just did"
 199 #+end_src
 200
 201  ad-nauseum.  When ready to commit, then just:
 202
 203 #+begin_src shell
 204      git push git+ssh://mob@repo.or.cz/srv/git/CommonLispStat.git mob:mob
 205 #+end_src
 206
 207 )
 208
 209 and it'll be put on the mob branch, as a proposal for merging.
 210
 211 Another approach would be to pull from the topic branch into the mob
 212 branch before uploading.   Will work on a formal example soon.
 213
 214 (the basic principle is that instead of the edit cycle on mob, do
 215 something like:
 216
 217 #+begin_src shell
 218   git checkout mob
 219   git pull . myTopicBranch
 220   git push git+ssh://mob@repo.or.cz/srv/git/CommonLispStat.git mob:mob
 221 #+end_src
 222
 223 )
 224
 225 Alternatively, one can work on the github repositories as well.  They
 226 are a bit differently organized, and require one to get a github
 227 account and work from there.  In that case, you'd need to D/L the
 228 libraries.
 229
 230 That gets a bit tricky, but see ./bin/GetRepos.sh for an example.
 231
 232 * Documentation and examples
 233
 234   I've started putting examples of use in function documentation.  If
 235   you are a lisp'er, you'll find this pendantic and insulting.  Many
 236   of the uses are trivial.  However, this has been tested out on a
 237   number of research statisticians (the primary user audience) and
 238   found useful.
 239
 240   Still need to write the (run-doc-ex 'function-name) function, which
 241   would print out the example and run it live.  Hopefully with the
 242   same results.  I've used XML markup for this, but for no particular
 243   reason, we could have used SEXPs as well.  This is currently done by
 244   using an <example> tag set, as in
 245
 246 #+srcname:
 247 #+begin_src xml
 248   <example>
 249   (progn
 250     (example-code-for-function))
 251   </example>
 252 #+end_src
 253
 254 * Footnotes
 255
 256 [fn:1] I´m not including instructions for Emacs or git, as the former
 257 is dealt with other places and the latter was required for you to get
 258 this.  Since disk space is cheap, I´m intentionally forcing git to be
 259 part of this system.  Sorry if you hate it.  Org-mode, org-babel, and
 260 org-babel-lisp, and hypo are useful for making this file a literate
 261 and interactively executable piece of work.