README.org

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