README.textile

Overview and motivation

Incanter is a Clojure-based, R-like statistical computing and graphics environment for the JVM. At the core of Incanter are the Parallel Colt numerics library, a multithreaded version of Colt, and the JFreeChart charting library, as well as several other Java and Clojure libraries.

The motivation for creating Incanter is to provide a JVM-based statistical computing and graphics platform with R-like semantics and interactive-programming environment. Running on the JVM provides access to the large number of existing Java libraries for data access, data processing, and presentation. Clojure’s seamless integration with Java makes leveraging these libraries much simpler than is possible in R, and Incanter’s R-like semantics makes statistical programming much simpler than is possible in pure Java.

Start the Clojure REPL (aka the shell) by double-clicking on the downloaded executable or, if you downloaded the pre-built distribution, running one of the scripts in the Incanter directory: script/repl or script\repl.bat on Windows. NOTE: The lein repl task uses Clojure 1.1, and Incanter 1.2.x requires Clojure 1.2, so use the repl script instead of lein.

From the Clojure REPL, load the Incanter libraries:

user=> (use '(incanter core stats charts))

Try an example: sample 1,000 values from a standard-normal distribution and view a histogram:

user=> (view (histogram (sample-normal 1000)))

Try another simple example, a plot of the sine function over the range -4 to 4:

user=> (view (function-plot sin -10 10))

The online documentation for most Incanter functions contain usage examples. The documentation can be viewed using Clojure’s doc function. For example, to view the documentation and usage examples for the linear-model function, call (doc linear-model) from the Clojure shell. Use (find-doc "search term") to search the online documentation from the Clojure shell. The API documentation can also be found at http://liebke.github.com/incanter.

Problems Moving to Clojure 1.3

Numerics

(repeat 100 2))@ and (reduce * (repeat 100 3)). Workaround:
change * to *’ in the test. Open question: propagating number
promotion looks to be a big pain. Should we add ticks to all the
arithmetic operators, or should be force them to bigint by adding an
“N” to the original literals?

Promotion problems:

Test failure in (dice-string) (stats_tests.clj:184), comparing a double (0.25) to a Ratio (1/4).

Test failure in (chebyshev) (stats_tests.clj:236), comparing an integer to a double.

Workaround: Change from equality operator (=) to equivalence operator (==). This should probably be done comprehensively.

Bit ops no longer support doubles. Appears to only affect
incanter.core/get-dummies, which was passing a double but didn’t
need to. Have made that explicitly an integer.

(matrix) promotes to double.

Equality tests are now problematic. Either use = and double or
bigint literals, or use == and don’t force precision on literals.

However, matrix-to-list or lazy-seq-to-list compares don’t work with
==. Symmetry is broken and and clojure lists don’t look like numeric
lists, and clojure vectors don’t look like algebraic vectors.

Sequences

Matrix.java no longer accepted as seq. Previously, implementing ISeq
was sufficient, now it appears the marker interface
clojure.lang.Sequential is also needed. Workaround: added Sequential
to Matrix’s implements clause. Open question: Should this be
Sequential vs. Seqable?

Dynamic vars

Compiler complains about *test-statistic-iterations* and*test-statistic-map* looking like dynamic vars, but not being
declared as such. They aren’t rebound in incanter-core, but the
docstring for test-statistic-distribution implies than an
application can rebind them, so I’m adding ^:dynamic to the decls.

$data was not declared as dynamic, could not be rebound. Workaround:
added ^{:dynamic true} to metadata. Open question: does rebinding
this fit in the 1.3 model for vars? Check with Stu about threading.

Leiningen

Complains that class clojure.set not found (called from
incanter.core as clojure.set/difference). This didn’t happen when
building under cake, for some reason. Workaround: change call from
clojure.set/difference to just difference, add :use in ns decl.

Contrib migration

From clojure.contrib.core, defvar and defvar- didn’t make it into
core.incubator. Scope: only used by distributions.clj. Workaround:
changed defvar- calls to just def.