<a border="0" href="http://incanter.org" ><img src="http://incanter.org/incanter-banner.png" alt="Incanter" /></a>


* <a href="#overview">Overview</a>
* <a href="#clojure">Getting started with Clojure</a>
* <a href="#getstarted">Getting started with Incanter</a>
* <a href="#docs">Documentation and examples</a>
* <a href="#build">Building Incanter</a>
* <a href="#depends">Dependencies</a>

<a name="overview"></a>

h2. Overview and motivation

<a href="http://incanter.org">_Incanter</a> is a <a href="http://clojure.org">Clojure</a>-based, <a href="http://www.r-project.org/">R</a>-like statistical computing and graphics environment for the JVM._  At the core of Incanter are the <a href="http://sites.google.com/site/piotrwendykier/software/parallelcolt">Parallel Colt</a> numerics library, a multithreaded version of <a href="http://acs.lbl.gov/~hoschek/colt/">Colt</a>, and the <a href="http://www.jfree.org/jfreechart/">JFreeChart</a> 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 <i><a href="http://books.google.com/books?id=8Cf16JkKz30C&pg=PA21">Back to the Future: Lisp as a Base for a Statistical Computing System by Ihaka and Lang (2008)</a></i>. Incanter is also inspired by the now dormant Lisp-Stat (see the special volume in the Journal of Statistical Software on <a href="http://www.jstatsoft.org/v13">Lisp-Stat: Past, Present, and Future</a> from 2005).

Motivation for a JVM-based Lisp can be found at the <i><a href="http://clojure.org">Clojure website</a></u></i>, and screencasts of several excellent Clojure talks by the language’s creator, Rich Hickey, can be found at <i><a href="http://clojure.blip.tv/">clojure.blip.tv</a></i>.


<a name="clojure"></a>

h2. Getting started with Clojure

For a great introduction to programming in Clojure, read "Clojure - Functional Programming for the JVM.":http://ociweb.com/mark/clojure/article.html by R. Mark Volkmann. For an even more extensive introduction, get the newly released book "Programming Clojure":http://www.pragprog.com/titles/shcloj/programming-clojure by Stuart Halloway.

*Other Clojure resources*

* "Clojure website":http://clojure.org
* "Getting Started with Clojure":http://www.assembla.com/wiki/show/clojure/Getting_Started
* "Clojure Google group":http://groups.google.com/group/clojure
* "clojure.blip.tv":http://clojure.blip.tv
* "Clojure Programming Wikibook":http://en.wikibooks.org/wiki/Clojure_Programming
* "Learning Clojure Wikibook":http://en.wikibooks.org/wiki/Learning_Clojure


<a name="getstarted"></a>

h2. Getting started with Incanter

Start by visiting the <a href="http://incanter.org">Incanter website</a> for an overview, checkout the <a href="http://incanter-blog.org/contents/">documentation page</a> for a listing of HOW-TOs and examples, and then download a pre-built version of either <a href="http://incanter.org/downloads/incanter-latest.zip">the latest build of Incanter</a>, which includes all the necessary dependencies, and unpack the file (if you would like to build it from source, read <a href="#build">Building Incanter</a>).

Start the Clojure shell (aka the REPL) from 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.

If you want the latest version of Incanter, 

1. Clone the repository with git: @git clone git://github.com/liebke/incanter.git@

2. Install Leiningen
  a. Download the lein script: @wget http://github.com/technomancy/leiningen/raw/stable/bin/lein@
     (use <a href="http://github.com/technomancy/leiningen/raw/stable/bin/lein.bat">lein.bat</a> on Windows)
  b. Place it on your path and chmod it to be executable: @chmod +x lein@
  c. Run: @lein self-install@

3. From the incanter directory, download the necessary dependencies: @lein deps@ 

4. Start a REPL: @script/repl@ or @script\repl.bat@, or start a Swank server: @script/swank@ or @script\swank.bat@

5. From the Clojure shell, load the Incanter libraries: 
<pre><code>user=> (use '(incanter core stats charts))</code></pre>

Try an example: sample 1,000 values from a standard-normal distribution and view a histogram: 
<pre><code>user=> (view (histogram (sample-normal 1000)))</code></pre>
<img src="http://incanter.org/images/examples/newtheme/hist-norm.png" />

Try another simple example, a plot of the sine function over the range -4 to 4:
<pre><code>user=> (view (function-plot sin -10 10))</code></pre>
<img src="http://incanter.org/images/examples/newtheme/xy-sin.png" />


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 <a href="http://liebke.github.com/incanter">http://liebke.github.com/incanter</a>.

*More Incanter examples*

* See the <a href="http://incanter.wordpress.com">Incanter blog</a>
* See Incanter wiki
** "Sample plots":http://wiki.github.com/liebke/incanter/sample-plots-in-incanter
** "Matrices":http://wiki.github.com/liebke/incanter/matrices
** "Datasets":http://wiki.github.com/liebke/incanter/datasets
** "Statistics examples":http://wiki.github.com/liebke/incanter/statistics-examples
** "Probability distributions":http://wiki.github.com/liebke/incanter/probability-distributions
* See the @examples/@ directory for additional usage examples.
**  @script/clj examples/run_prob_plots.clj@ to generate example probability distribution plots



<a name="docs"></a>

h2. Documentation

The following documentation covers the Incanter and Clojure APIs and the APIs of the underlying java libraries.

*Incanter documentation*
* "Doc Index":http://incanter-blog.org/contents/
* "API":http://liebke.github.com/incanter


*Related API documentation*
* "Clojure API":http://richhickey.github.com/clojure/
* "Clojure-contrib API":http://richhickey.github.com/clojure-contrib/
* "Parallel Colt Java API":http://incanter.org/docs/parallelcolt/api/
* "JFreeChart Java API":http://www.jfree.org/jfreechart/api/javadoc/index.html
* "Processing API":http://www.processing.org/reference/


<a name="build"></a>

h2. Building Incanter

To build and test Incanter, you will need to have <a href="http://github.com/technomancy/leiningen/">Leiningen</a> and <a href="http://git-scm.com/">git</a> installed:

* First, clone the Incanter Github repository: @git clone git://github.com/liebke/incanter.git@
* cd into the incanter directory
* use Leiningen to download the necessary dependencies: @lein deps@
* You can now use the @script/repl@ and @script/swank@ scripts (or on Windows @repl.bat@ and @swank.bat@) to start a REPL and Swank server respectively.
* If you want to run the tests for each of Incanter's modules, use @script/test@ 
* Each of Incanter's modules are independent Leiningen projects. Just cd into modules/incanter-* and use Leiningen to build each one as a standalone library.
* @script/install@ uses Leiningen to build all the modules and install them in your local ~/.m2 repository.



<a name="depends"></a>

h2. Incanter dependencies

* "Clojure":http://code.google.com/p/clojure/
* "Clojure-Contrib":http://code.google.com/p/clojure-contrib/ 
* "Parallel Colt":http://sites.google.com/site/piotrwendykier/software/parallelcolt
** "Netlib-Java":http://code.google.com/p/netlib-java/ (included with Parallel Colt)
* "JFreeChart":http://www.jfree.org/jfreechart/
** "JCommon":http://www.jfree.org/jcommon/ (included with JFreeChart)
** "GnuJaxp":http://www.gnu.org/software/classpathx/jaxp/jaxp.html (included with JFreeChart)
* "OpenCSV":http://opencsv.sourceforge.net/
* "iText":http://itextpdf.com/
* "Congomongo":http://github.com/somnium/congomongo
* "Clojure-json":http://github.com/danlarkin/clojure-json
* "JLine":http://jline.sourceforge.net/

