- Getting started with Clojure
- Getting started with Incanter
- Documentation and examples
- Building Incanter
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.
Motivation for a Lisp-based R-like statistical environment can be found in the paper Back to the Future: Lisp as a Base for a Statistical Computing System by Ihaka and Lang (2008). Incanter is also inspired by the now dormant Lisp-Stat (see the special volume in the Journal of Statistical Software on Lisp-Stat: Past, Present, and Future from 2005).
Getting started with Clojure
For a great introduction to programming in Clojure, read Clojure – Functional Programming for the JVM. by R. Mark Volkmann. For an even more extensive introduction, get the newly released book Programming Clojure by Stuart Halloway.
Other Clojure resources
- Clojure website
- Clojure Google group
- Clojure Programming Wikibook
- Learning Clojure Wikibook
Getting started with Incanter
Start the Clojure shell (aka the REPL) from the Incanter directory:
bin\clj.bat on Windows (note: if you want to start the Clojure REPL from a directory other than the top level Incanter directory, change the INCANTER_HOME variable in the clj script so that it uses an absolute path instead the ./ directory).
From the Clojure shell, load the Incanter libraries:
(use '(incanter core stats charts))
Try an example: sample 1,000 values from a standard-normal distribution and view a histogram:
(view (histogram (sample-normal 1000)))
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 in the
docs/api/ directory and online at http://incanter.org/docs/api/.
More Incanter examples
- See the Incanter blog
- See Incanter wiki
- See the
test/incanter/*-tests.cljfor additional usage examples
examples/run_prob_plots.cljto generate example probability distribution plots
bin/runtests.cljto run test cases
The following documentation covers the Incanter and Clojure APIs and the APIs of the underlying java libraries.
Related API documentation
To build Incanter, test it, and generate the api documentation yourself, run the following commands from the Incanter directory:
- Clone the Incanter Github repository:
git clone git://github.com/liebke/incanter.git
- cd into the incanter directory
- Download and uncompress Incanter’s dependencies:
- Build target/incanter-1.0-SNAPSHOT.jar:
- Run unit tests:
- Generate API docs:
*.clj scripts won’t run on Windows systems as is. Although, the Clojure code contained in the
*.clj scripts can be run from the Clojure shell.)
For back-end processing that doesn’t require charts or visualizations, an alternative ant target, called
incanter-core, is available that creates
incanter-core-1.0-SNAPSHOT.jar, which only includes the ‘core’ and ‘stats’ libraries, and only depends on the clojure.jar and Parallel Colt libraries (colt.jar, netlib.jar, arpack-combo.jar).
Building Incanter with Maven
Incanter can be built and tested with Maven with the following commands:
mvn compile to build the incanter.Matrix Java class,
mvn clojure:compile to build the remaining Clojure classes,
mvn clojure:test to run the tests,
mvn clojure:repl to start up a Clojure REPL with Incanter and its dependencies in the CLASSPATH,
mvn package to create a standard Incanter jar file, and an uberjar that includes all of Incanter’s dependencies, in the ./target directory.
lib/license.txt file for license terms of included libraries.