2 Time-stamp: <2012-10-05 04:19:12 tony>
4 * Current Status: COMPLETELY BROKEN
6 but we are rebuilding it.
10 You probably did (preferred)
14 git clone git://github.com/blindglobe/common-lisp-stat.git
17 or (coming soon!) from within a Lisp instance,
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.
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)
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:
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.
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).
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.
52 ** Example Usage steps [2/7]
54 *** DONE Start and Load
63 *** DONE Setup a place to work
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:
69 #+BEGIN_SRC lisp -n :tangle "readme-example.lisp"
70 (in-package :cls-user)
73 and this has some basic modules from CLS instantiated (dataframes,
74 probability calculus, numerical linear algebra, basic summaries
75 (numerical and visual displays).
77 However, it can be better is to create a package to work in, which
78 pulls in only desired functionality:
81 #+BEGIN_SRC lisp +n :tangle "readme-example.lisp"
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
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
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
107 (:export summarize-data summarize-results this-data this-report))
109 (in-package :my-clswork-user) ;; or :my-package-user
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.
123 *** TODO Get to work [0/3]
125 **** TODO Pull in or create data
127 **** TODO Summarize results
129 **** TODO Save work and results for knowledge building and reuse
131 One can build a package, or save an image (CL implementation
134 *** TODO Inform moi of problems or successes
136 NEED TO SETUP A MAILING LIST!!
138 mailto:blindglobe@gmail.com if there is anything wrong, or
139 even if something happens to work.
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
151 See files in file:Doc/ for history, design considerations, and
152 random, sometimes false and misleading, musings.
154 * Local modifications, Development, Contributions
157 git clone git://repo.or.cz/CommonLispStat.git
159 # git submodules init
160 # git submodules update
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,
169 git checkout -b myTopicBranch
172 and then work on myTopicBranch, pulling back to the master branch when
177 git pull . myTopicBranch
182 git rebase myTopicBranch
186 of course, perhaps you want to contribute to the mob branch. For
187 that, after cloning the repository as above, you would:
190 git checkout -b mob remotes/origin/mob
193 (work, work, work... through a cycle of
197 git add <files just edited>
198 git commit -m "what I just did"
201 ad-nauseum. When ready to commit, then just:
204 git push git+ssh://mob@repo.or.cz/srv/git/CommonLispStat.git mob:mob
209 and it'll be put on the mob branch, as a proposal for merging.
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.
214 (the basic principle is that instead of the edit cycle on mob, do
219 git pull . myTopicBranch
220 git push git+ssh://mob@repo.or.cz/srv/git/CommonLispStat.git mob:mob
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
230 That gets a bit tricky, but see ./bin/GetRepos.sh for an example.
232 * Documentation and examples
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
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
250 (example-code-for-function))
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.