API for charts - Incanter 2.0 (in development)

Overview

This is the core charting library for Incanter.
It provides basic scatter plots, histograms, box plots
xy plots, bar charts, line charts, as well as
specialized charts like trace plots and Bland-Altman
plots.

This library is built on the JFreeChart library
(http://www.jfree.org/jfreechart/).

Usage: (add-box-plot chart x & options)

Adds an additional box to an existing box-plot, returns the modified chart object.

Options:
  :series-label (default x expression)

Examples:

  (use '(incanter core charts stats datasets))
  (doto (box-plot (sample-normal 1000) :legend true)
        view
        (add-box-plot (sample-normal 1000 :sd 2))
        (add-box-plot (sample-gamma 1000)))


  (with-data (get-dataset :iris)
    (doto (box-plot :Sepal.Length :legend true)
      (add-box-plot :Petal.Length)
      (add-box-plot :Sepal.Width)
      (add-box-plot :Petal.Width)
      view))


References:
  http://www.jfree.org/jfreechart/api/javadoc/
  http://www.jfree.org/jfreechart/api/javadoc/org/jfree/chart/JFreeChart.html

Usage: (add-categories chart categories values & options)

Adds an additional categories to an existing bar-chart or line-chart, returns the modified chart object.

Options:
  :group-by
  :series-label

Examples:

  (use '(incanter core charts stats datasets))
  (def seasons (mapcat identity (repeat 3 ["winter" "spring" "summer" "fall"])))
  (def years (mapcat identity (repeat 4 [2007 2008 2009])))
  (def x (sample-uniform 12 :integers true :max 100))
  (def plot (bar-chart years x :group-by seasons :legend true))
  (view plot)
  (add-categories plot years [10 20 40] :series-label "winter-break")

  (add-categories plot
                  (plus 3 years)
                  (sample-uniform 12 :integers true :max 100)
                  :group-by seasons)

  (def plot2 (line-chart years x :group-by seasons :legend true))
    (view plot2)
    (add-categories plot2 (plus 3 years) (sample-uniform 12 :integers true :max 100) :group-by seasons)

    (with-data (get-dataset :iris)
      (doto (line-chart :Species :Sepal.Length
                        :data ($rollup mean :Sepal.Length :Species)
                        :legend true)
        (add-categories :Species :Sepal.Width :data ($rollup mean :Sepal.Width :Species))
        (add-categories :Species :Petal.Length :data ($rollup mean :Petal.Length :Species))
        (add-categories :Species :Petal.Width :data ($rollup mean :Petal.Width :Species))
        view))


References:
  http://www.jfree.org/jfreechart/api/javadoc/
  http://www.jfree.org/jfreechart/api/javadoc/org/jfree/chart/JFreeChart.html

Usage: (add-function chart function min-range max-range & options)

Adds a xy-plot of the given function to the given chart, returning
a modified version of the chart.

Options:
  :series-label (default x expression)
  :step-size (default (/ (- max-range min-range) 500))

See also:
  function-plot, view, save, add-function, add-points, add-lines


Examples:

  (use '(incanter core stats charts))

  ;; plot the sine and cosine functions
  (doto (function-plot sin (- Math/PI) Math/PI)
        (add-function cos (- Math/PI) Math/PI)
        view)


  ;; plot two normal pdf functions
  (doto (function-plot pdf-normal -3 3 :legend true)
        (add-function (fn [x] (pdf-normal x :mean 0.5 :sd 0.5)) -3 3)
        view)


  ;; plot a user defined function and its derivative
  (use '(incanter core charts optimize))

  ;; define the function, x^3 + 2x^2 + 2x + 3
  (defn cubic [x] (+ (* x x x) (* 2 x x) (* 2 x) 3))

  ;; use the derivative function to get a function
  ;; that approximates its derivative
  (def deriv-cubic (derivative cubic))

  ;; plot the cubic function and its derivative
  (doto (function-plot cubic -10 10)
        (add-function deriv-cubic -10 10)
        view)

Usage: (add-histogram chart x & options)

Adds a histogram to an existing histogram plot, returns the modified
chart object.

Options:
  :nbins (default 10) number of bins for histogram
  :series-label (default x expression)

Examples:

  (use '(incanter core charts stats datasets))
  (doto (histogram (sample-normal 1000)
                   :legend true)
        view
        (add-histogram (sample-normal 1000 :sd 0.5)))


  (with-data (get-dataset :iris)
    (doto (histogram :Sepal.Length :legend true)
      (add-histogram :Petal.Length)
      view))

References:
  http://www.jfree.org/jfreechart/api/javadoc/
  http://www.jfree.org/jfreechart/api/javadoc/org/jfree/chart/JFreeChart.html

Usage: (add-image chart x y img & options)

Adds an image to the chart at the given coordinates.

Arguments:
  chart -- the chart to add the polygon to.
  x, y -- the coordinates to place the image
  img -- a java.awt.Image object


Examples:
  (use '(incanter core charts latex))

   (doto (function-plot sin -10 10)
    (add-image 0 0 (latex "\\frac{(a+b)^2} {(a-b)^2}"))
    view)

Usage: (add-lines chart x y & options)

Plots lines on the given scatter or line plot (xy-plot) of the (x,y) points.
Equivalent to R's lines function, returns the modified chart object.

Options:
  :series-label (default x expression)
  :points (default false)
  :auto-sort (default true) sort data by x


Examples:

  (use '(incanter core stats io datasets charts))
  (def cars (to-matrix (get-dataset :cars)))
  (def y (sel cars :cols 0))
  (def x (sel cars :cols 1))
  (def plot1 (scatter-plot x y :legend true))
  (view plot1)

  ;; add regression line to scatter plot
  (def lm1 (linear-model y x))
  (add-lines plot1 x (:fitted lm1))

  ;; model the data without an intercept
  (def lm2 (linear-model y x :intercept false))
  (add-lines plot1 x (:fitted lm2))


  ;; Clojure's doto macro can be used to build a chart
  (doto (histogram (sample-normal 1000) :density true)
        (add-lines (range -3 3 0.05) (pdf-normal (range -3 3 0.05)))
        view)


  (with-data (get-dataset :iris)
      (doto (xy-plot :Sepal.Width :Sepal.Length :legend true)
            (add-lines :Petal.Width :Petal.Length)
            view))



References:
  http://www.jfree.org/jfreechart/api/javadoc/
  http://www.jfree.org/jfreechart/api/javadoc/org/jfree/chart/JFreeChart.html

Usage: (add-parametric chart function min-range max-range & options)

Adds a xy-plot of the given parametric function to the given chart, returning
a modified version of the chart.
Function takes 1 argument t and returns point [x y].

Options:
  :series-label (default function expression)
  :step-size (default (/ (- max-range min-range) 500))

See also:
  parametric-plot, view, save, add-function, add-points, add-lines


Examples:

  (use '(incanter core charts))

  ;;; Plot square with circle inside.
  (defn circle [t] [(cos t) (sin t)])
  (doto (xy-plot [1 -1 -1 1 1] [1 1 -1 -1 1] :auto-sort false)
        (add-parametric circle 0 (* 2 Math/PI))
        (view))

Usage: (add-pointer chart x y & options)

Adds an arrow annotation to the given chart.

Arguments:
  chart -- the chart to annotate
  x, y -- the coordinate to add the annotation


Options:
    :text -- (default "") text to include at the end of the arrow
    :angle -- (default :nw) either a number indicating the angle of the arrow
              or a keyword indicating a direction (:north :nw :west :sw :south
              :se :east :ne)


Examples:

  (use '(incanter core charts))
  (def x (range (* -2 Math/PI) (* 2 Math/PI) 0.01))
  (def plot (xy-plot x (sin x)))
  (view plot)
  ;; annotate the plot
  (doto plot
    (add-pointer (- Math/PI) (sin (- Math/PI)) :text "(-pi, (sin -pi))")
    (add-pointer Math/PI (sin Math/PI) :text "(pi, (sin pi))" :angle :ne)
    (add-pointer (* 1/2 Math/PI) (sin (* 1/2 Math/PI)) :text "(pi/2, (sin pi/2))" :angle :south))

  ;; try the different angle options
  (add-pointer plot 0 0 :text "north" :angle :north)
  (add-pointer plot 0 0 :text "nw" :angle :nw)
  (add-pointer plot 0 0 :text "ne" :angle :ne)
  (add-pointer plot 0 0 :text "west" :angle :west)
  (add-pointer plot 0 0 :text "east" :angle :east)
  (add-pointer plot 0 0 :text "south" :angle :south)
  (add-pointer plot 0 0 :text "sw" :angle :sw)
  (add-pointer plot 0 0 :text "se" :angle :se)

Usage: (add-points chart x y & options)

Plots points on the given scatter-plot or xy-plot of the (x,y) points.
Equivalent to R's lines function, returns the modified chart object.

Options:
  :series-label (default x expression)

Examples:

  (use '(incanter core stats io datasets charts))
  (def cars (to-matrix (get-dataset :cars)))
  (def y (sel cars :cols 0))
  (def x (sel cars :cols 1))

  ;; add regression line to scatter plot
  (def lm1 (linear-model y x))
  ;; model the data without an intercept
  (def lm2 (linear-model y x :intercept false))

  (doto (xy-plot x (:fitted lm1) :legend true)
        view
        (add-points x y)
        (add-lines x (:fitted lm2)))


  (with-data (get-dataset :iris)
    (doto (scatter-plot :Sepal.Length :Sepal.Width :data ($where {:Species "setosa"}))
          (add-points :Sepal.Length :Sepal.Width :data ($where {:Species "versicolor"}))
          (add-points :Sepal.Length :Sepal.Width :data ($where {:Species "virginica"}))
          view))

  ;; of course this chart can be achieved in a single line:
  (view (scatter-plot :Sepal.Length :Sepal.Width :group-by :Species :data (get-dataset :iris)))



References:
  http://www.jfree.org/jfreechart/api/javadoc/
  http://www.jfree.org/jfreechart/api/javadoc/org/jfree/chart/JFreeChart.html

Usage: (add-polygon chart coords & options)

Adds a polygon outline defined by a given coordinates. The last coordinate will
close with the first. If only two points are given, it will plot a line.

Arguments:
  chart -- the chart to add the polygon to.
  coords -- a list of coords (an n-by-2 matrix can also be used)


Examples:
  (use '(incanter core stats charts))
  (def x (range -3 3 0.01))
  (def plot (xy-plot x (pdf-normal x)))
  (view plot)

  ;; add polygon to the chart
  (add-polygon plot [[-1.96 0] [1.96 0] [1.96 0.4] [-1.96 0.4]])
  ;; the coordinates can also be passed in a matrix
  ;; (def points (matrix [[-1.96 0] [1.96 0] [1.96 0.4] [-1.96 0.4]]))
  ;; (add-polygon plot points)
  ;; add a text annotation
  (add-text plot -1.25 0.35 "95% Conf Interval")

  ;; PCA chart example
  (use '(incanter core stats charts datasets))
  ;; load the iris dataset
  (def iris (to-matrix (get-dataset :iris)))
  ;; run the pca
  (def pca (principal-components (sel iris :cols (range 4))))
  ;; extract the first two principal components
  (def pc1 (sel (:rotation pca) :cols 0))
  (def pc2 (sel (:rotation pca) :cols 1))

  ;; project the first four dimension of the iris data onto the first
  ;; two principal components
  (def x1 (mmult (sel iris :cols (range 4)) pc1))
  (def x2 (mmult (sel iris :cols (range 4)) pc2))

  ;; now plot the transformed data, coloring each species a different color
  (def plot (scatter-plot x1 x2
                          :group-by (sel iris :cols 4)
                          :x-label "PC1" :y-label "PC2" :title "Iris PCA"))

  (view plot)
  ;; put box around the first group
  (add-polygon plot [[-3.2 -6.3] [-2 -6.3] [-2 -3.78] [-3.2 -3.78]])
  ;; add some text annotations
  (add-text plot -2.5 -6.5 "Setosa")
  (add-text plot -5 -5.5 "Versicolor")
  (add-text plot -8 -5.5 "Virginica")

No usage documentation available

Adds a JFreeChart title object to a chart as a subtitle.

Examples:
  (use '(incanter core charts latex))

  (doto (function-plot sin -10 10)
    (add-subtitle "subtitle")
    (add-subtitle (latex " \\frac{(a+b)^2} {(a-b)^2}"))
    view)

Usage: (add-text chart x y text & options)

Adds a text annotation centered at the given coordinates.

Arguments:
  chart -- the chart to annotate
  x, y -- the coordinates to center the text
  text -- the text to add


Examples:

  ;; PCA chart example
  (use '(incanter core stats charts datasets))
  ;; load the iris dataset
  (def iris (to-matrix (get-dataset :iris)))
  ;; run the pca
  (def pca (principal-components (sel iris :cols (range 4))))
  ;; extract the first two principal components
  (def pc1 (sel (:rotation pca) :cols 0))
  (def pc2 (sel (:rotation pca) :cols 1))

  ;; project the first four dimension of the iris data onto the first
  ;; two principal components
  (def x1 (mmult (sel iris :cols (range 4)) pc1))
  (def x2 (mmult (sel iris :cols (range 4)) pc2))

  ;; now plot the transformed data, coloring each species a different color
  (def plot (scatter-plot x1 x2
                          :group-by (sel iris :cols 4)
                          :x-label "PC1" :y-label "PC2" :title "Iris PCA"))
  (view plot)
  ;; add some text annotations
  (add-text plot -2.5 -6.5 "Setosa")
  (add-text plot -5 -5.5 "Versicolor")
  (add-text plot -8 -5.5 "Virginica")

Usage: (area-chart categories values & options)

Returns a JFreeChart object representing an area-chart of the given data.
Use the 'view' function to display the chart, or the 'save' function
to write it to a file.

Arguments:
  categories -- a sequence of categories
  values -- a sequence of numeric values

Options:
  :title (default '') main title
  :x-label (default 'Categories')
  :y-label (default 'Value')
  :series-label
  :legend (default false) prints legend
  :vertical (default true) the orientation of the plot
  :group-by (default nil) -- a vector of values used to group the values into
                             series within each category.


See also:
  view and save

Examples:


  (use '(incanter core stats charts datasets))

  (with-data (get-dataset :co2)
    (view (area-chart :Type :uptake
                     :title "CO2 Uptake"
                     :group-by :Treatment
                     :x-label "Grass Types" :y-label "Uptake"
                    :legend true)))


  (def data (get-dataset :airline-passengers))
  (view (area-chart :year :passengers :group-by :month :legend true :data data))

  (with-data  (get-dataset :airline-passengers)
    (view (area-chart :month :passengers :group-by :year :legend true)))


  (def data (get-dataset :austres))
  (view data)
  (def plot (area-chart :year :population :group-by :quarter :legend true :data data))
  (view plot)
  (save plot "/tmp/austres_plot.png" :width 1000)
  (view "file:///tmp/austres_plot.png")


  (def seasons (mapcat identity (repeat 3 ["winter" "spring" "summer" "fall"])))
  (def years (mapcat identity (repeat 4 [2007 2008 2009])))
  (def values (sample-uniform 12 :integers true :max 100))
  (view (area-chart years values :group-by seasons :legend true))

  (view (area-chart ["a" "b" "c"] [10 20 30]))
  (view (area-chart ["a" "a" "b" "b" "c" "c" ] [10 20 30 10 40 20]
                   :legend true
                   :group-by ["I" "II" "I" "II" "I" "II"]))

  ;; add a series label
  (def plot (area-chart ["a" "b" "c"] [10 20 30] :legend true :series-label "s1"))
  (view plot)
  (add-categories plot ["a" "b" "c"] [5 25 40] :series-label "s2")

  (view (area-chart (sample "abcdefghij" :size 10 :replacement true)
                   (sample-uniform 10 :max 50) :legend true))



References:
  http://www.jfree.org/jfreechart/api/javadoc/
  http://www.jfree.org/jfreechart/api/javadoc/org/jfree/chart/JFreeChart.html

Usage: (bar-chart categories values & options)

Returns a JFreeChart object representing a bar-chart of the given data.
Use the 'view' function to display the chart, or the 'save' function
to write it to a file.

Arguments:
  categories -- a sequence of categories
  values -- a sequence of numeric values

Options:
  :title (default '') main title
  :x-label (default 'Categories')
  :y-label (default 'Value')
  :series-label

:legend (default false) prints legend
  :vertical (default true) the orientation of the plot
  :group-by (default nil) -- a vector of values used to group the values into
                             series within each category.


See also:
  view and save

Examples:


  (use '(incanter core stats charts datasets))

  (with-data (get-dataset :co2)
    (view (bar-chart :Type :uptake
                     :title "CO2 Uptake"
                     :group-by :Treatment
                     :x-label "Grass Types" :y-label "Uptake"
                    :legend true)))


  (def data (get-dataset :airline-passengers))
  (view (bar-chart :year :passengers :group-by :month :legend true :data data))

  (with-data  (get-dataset :airline-passengers)
    (view (bar-chart :month :passengers :group-by :year :legend true)))


  (def data (get-dataset :austres))
  (view data)
  (def plot (bar-chart :year :population :group-by :quarter :legend true :data data))
  (view plot)
  (save plot "/tmp/austres_plot.png" :width 1000)
  (view "file:///tmp/austres_plot.png")


  (def seasons (mapcat identity (repeat 3 ["winter" "spring" "summer" "fall"])))
  (def years (mapcat identity (repeat 4 [2007 2008 2009])))
  (def values (sample-uniform 12 :integers true :max 100))
  (view (bar-chart years values :group-by seasons :legend true))

  (view (bar-chart ["a" "b" "c"] [10 20 30]))
  (view (bar-chart ["a" "a" "b" "b" "c" "c" ] [10 20 30 10 40 20]
                   :legend true
                   :group-by ["I" "II" "I" "II" "I" "II"]))

  ;; add a series label
  (def plot (bar-chart ["a" "b" "c"] [10 20 30] :legend true :series-label "s1"))
  (view plot)
  (add-categories plot ["a" "b" "c"] [5 25 40] :series-label "s2")

  (view (bar-chart (sample "abcdefghij" :size 10 :replacement true)
                   (sample-uniform 10 :max 50) :legend true))



References:
  http://www.jfree.org/jfreechart/api/javadoc/
  http://www.jfree.org/jfreechart/api/javadoc/org/jfree/chart/JFreeChart.html

Usage: (bland-altman-plot x1 x2 & options)

Options:
  :data (default nil) If the :data option is provided a dataset,
                      column names can be used instead of sequences
                      of data for arguments x1 and x2.

Examples:

  (use '(incanter core datasets charts))
  (def flow-meter (to-matrix (get-dataset :flow-meter)))
  (def x1 (sel flow-meter :cols 1))
  (def x2 (sel flow-meter :cols 3))
  (view (bland-altman-plot x1 x2))

  (with-data (get-dataset :flow-meter)
    (view (bland-altman-plot (keyword "Wright 1st PEFR")
                             (keyword "Mini Wright 1st PEFR"))))



References:
  http://en.wikipedia.org/wiki/Bland-Altman_plot
  http://www-users.york.ac.uk/~mb55/meas/ba.htm

Usage: (box-plot x & options)

Returns a JFreeChart object representing a box-plot of the given data.
Use the 'view' function to display the chart, or the 'save' function
to write it to a file.

Options:
  :title (default '') main title
  :x-label (default x expression)
  :y-label (default 'Frequency')
  :legend (default false) prints legend
  :series-label (default x expression)
  :group-by (default nil) -- a vector of values used to group the x values into series.

See also:
  view and save

Examples:

  (use '(incanter core stats charts))
  (def gamma-box-plot (box-plot (sample-gamma 1000 :shape 1 :scale 2)
                        :title "Gamma Boxplot"
                        :legend true))
  (view gamma-box-plot)
  (add-box-plot gamma-box-plot (sample-gamma 1000 :shape 2 :scale 2))
  (add-box-plot gamma-box-plot (sample-gamma 1000 :shape 3 :scale 2))

  ;; use the group-by options
  (use '(incanter core stats datasets charts))
  (with-data (get-dataset :iris)
    (view (box-plot :Petal.Length :group-by :Species :legend true))
    (view (box-plot :Petal.Width :group-by :Species :legend true))
    (view (box-plot :Sepal.Length :group-by :Species :legend true))
    (view (box-plot :Sepal.Width :group-by :Species :legend true)))

  ;; see INCANTER_HOME/examples/probability_plots.clj for more examples of plots

References:
  http://www.jfree.org/jfreechart/api/javadoc/
  http://www.jfree.org/jfreechart/api/javadoc/org/jfree/chart/JFreeChart.html

Usage: (candle-stick-plot & options)

Produces a candle stick chart

Options:
  :data (default nil) If the :data option is provided a dataset,
                      column names can be used instead of sequences
                      of data as arguments to xy-plot.
  :date Key for accessing the underlying date series (defaults to :date)
  :high Key for accessing high value data (defaults to :high)
  :low Key for accessing low value data (defaults to :low)
  :open Key for accessing open value data (defaults to :open)
  :close Key for accessing close value data (defaults to :close)
  :volume Key for accessing volume data (defaults to :volume). Volume data is optional
  :title (default 'Candle Stick Plot') main title
  :time-label (default empty)
  :value-label (default empty)
  :legend (default false) prints legend
  :series-label (default empty)

 Example:
   ;; use default mappings so the dataset must have
   ;; :date, :high, :low, :open, :close and :volume keys
   (candle-stick-plot :data <dataset>)
   ;; more customization
   (candle-stick-plot
     :data dataset
     :high :HighPrice
     :low :LowPrice
     :open :StartOfDay
     :close :CoB
     :volume :TransactionVolume
     :legend true
     :time-label "CoB date"
     :value-label "Price"
     :series-label "Price time series"
     :title "Price information")

Usage: (clear-background chart)

Sets the alpha level (transparency) of the plot's background to zero
removing the default grid, returns the modified chart object.

References:
  http://www.jfree.org/jfreechart/api/javadoc/
  http://www.jfree.org/jfreechart/api/javadoc/org/jfree/chart/JFreeChart.html

Usage: (dynamic-scatter-plot [& slider-bindings] expression & options)

Returns an scatter-plot bound to sliders (which tend to appear behind the chart).
See the sliders macro for more information.


Examples:

(use '(incanter core stats charts))

(let [x (range -3 3 0.1)]
  (view (dynamic-scatter-plot [mean (range -3 3 0.1)
                               sd (range 0.1 10 0.1)]
          [x (pdf-normal x :mean mean :sd sd)]
          :title "Normal PDF Plot")))


 (let [x (range -3 3 0.1)]
   (view (dynamic-scatter-plot [mean (range -3 3 0.1)
                                sd (range 0.1 10 0.1)]
          (for [xi x] [xi (pdf-normal xi :mean mean :sd sd)])
          :title "Normal PDF Plot")))

Usage: (dynamic-xy-plot [& slider-bindings] expression & options)

Returns an xy-plot bound to sliders (which tend to appear behind the chart).
See the sliders macro for more information.


Examples:

  (use '(incanter core stats charts))

  (let [x (range -3 3 0.1)]
  (view (dynamic-xy-plot [mean (range -3 3 0.1)
                          sd (range 0.1 10 0.1)]
                         [x (pdf-normal x :mean mean :sd sd)]
                         :title "Normal PDF Plot")))

 (let [x (range -3 3 0.1)]
   (view (dynamic-xy-plot [mean (range -3 3 0.1)
                           sd (range 0.1 10 0.1)]
          (for [xi x] [xi (pdf-normal xi :mean mean :sd sd)])
          :title "Normal PDF Plot")))

Usage: (extend-line chart x y & options)

 Add new data set to an exiting series if it already exists,
otherwise, data set will be added to a newly created series. 

Usage: (function-plot function min-range max-range & options)

Returns a xy-plot object of the given function over the range indicated
by the min-range and max-range arguments. Use the 'view' function to
display the chart, or the 'save' function to write it to a file.

Options:
  :title (default '') main title
  :x-label (default x expression)
  :y-label (default 'Frequency')
  :legend (default false) prints legend
  :series-label (default x expression)
  :step-size (default (/ (- max-range min-range) 500))

See also:
  view, save, add-points, add-lines


Examples:

  (use '(incanter core stats charts))

  (view (function-plot sin (- Math/PI) Math/PI))
  (view (function-plot pdf-normal -3 3))

  (defn cubic [x] (+ (* x x x) (* 2 x x) (* 2 x) 3))
  (view (function-plot cubic -10 10))

Usage: (get-series chart)
       (get-series chart series-idx)

get-series

Usage: (has-series? chart series-label)

Test to see if a chart has a series name series-lab

Usage: (heat-map function x-min x-max y-min y-max & options)

Usage: (heat-map function x-min x-max y-min y-max & options)

Returns a JFreeChart object representing a heat map of the function across
the given x and y ranges. Use the 'view' function to display the chart, or
the 'save' function to write it to a file.

Arguments:
  function -- a function that takes two scalar arguments and returns a scalar
  x-min    -- lower bound for the first value of the function
  x-max    -- upper bound for the first value of the function
  y-min    -- lower bound for the second value of the function
  y-max    -- upper bound for the second value of the function

Options:
  :title
  :x-label (default 'x-min < x < x-max')
  :y-label (default 'y-min < y < y-max')
  :z-label -- defaults to function's name
  :color? (default true) -- should the plot be in color or not?
  :include-zero? (default true) -- should the plot include the origin if it
                                   is not in the ranges specified?

Examples:
  (use '(incanter core charts))
  (defn f [x y] (sin (sqrt (plus (sq x) (sq y)))))
  (view (heat-map f -10 10 -15 15))
  (view (heat-map f -10 10 -10 10 :color? false))
  (view (heat-map f 5 10 5 10 :include-zero? false))

  (defn f2 [x y] (plus (sq x) (sq y)))
  (view (heat-map f2 -10 10 -10 10))
  (view (heat-map f2 -10 10 -10 10 :color? false))

  (use 'incanter.stats)
  (defn f3 [x y] (pdf-normal (sqrt (plus (sq x) (sq y)))))
  (view (heat-map f3 -3 3 -3 3 :x-label "x1" :y-label "x2" :z-label "pdf"))
  (view (heat-map f3 -3 3 -3 3 :color? false))

  (defn f4 [x y] (minus (sq x) (sq y)))
  (view (heat-map f4 -10 10 -10 10))
  (view (heat-map f4 -10 10 -10 10 :color? false))


  (use '(incanter core stats charts))
  (let [data [[0 5 1 2]
                [0 10 1.9 1]
                [15 0 0.5 1.5]
                [18 10 4.5 2.1]]
        diffusion (fn [x y]
                    (sum (map #(pdf-normal (euclidean-distance [x y] (take 2 %))
                                           :mean (nth % 2) :sd (last %))
                              data)))]
    (view (heat-map diffusion -5 20 -5 20)))

Usage: (histogram x & options)

Returns a JFreeChart object representing the histogram of the given data.
Use the 'view' function to display the chart, or the 'save' function
to write it to a file.

Options:
  :nbins (default 10) number of bins
  :density (default false) if false, plots frequency, otherwise density
  :title (default 'Histogram') main title
  :x-label (default x expression)
  :y-label (default 'Frequency')
  :legend (default false) prints legend
  :series-label (default x expression)


See also:
  view, save, add-histogram

Examples:

  (use '(incanter core charts stats))
  (view (histogram (sample-normal 1000)))

  # plot a density histogram
  (def hist (histogram (sample-normal 1000) :density true))
  (view hist)

  # add a normal density line to the plot
  (def x (range -4 4 0.01))
  (add-lines hist x (pdf-normal x))

  # plot some gamma data
  (def gam-hist (histogram (sample-gamma 1000) :density true :nbins 30))
  (view gam-hist)
  (def x (range 0 8 0.01))
  (add-lines gam-hist x (pdf-gamma x))

  (use 'incanter.datasets)
  (def iris (get-dataset :iris))
  (view (histogram :Sepal.Width :data iris))

  (with-data (get-dataset :iris)
    (view (histogram :Petal.Length)))



References:
  http://www.jfree.org/jfreechart/api/javadoc/
  http://www.jfree.org/jfreechart/api/javadoc/org/jfree/chart/JFreeChart.html

Usage: (line-chart categories values & options)

Returns a JFreeChart object representing a line-chart of the given values and categories.
Use the 'view' function to display the chart, or the 'save' function
to write it to a file.

Arguments:
  categories -- a sequence of categories
  values -- a sequence of numeric values

Options:
  :title (default '') main title
  :x-label (default 'Categories')
  :y-label (default 'Value')
  :legend (default false) prints legend
  :series-label
  :group-by (default nil) -- a vector of values used to group the values into
                             series within each category.
  :gradient? (default false) -- use gradient on bars


See also:
  view and save

Examples:

  (use '(incanter core stats charts datasets))

  (def data (get-dataset :airline-passengers))
  (def years (sel data :cols 0))
  (def months (sel data :cols 2))
  (def passengers (sel data :cols 1))
  (view (line-chart years passengers :group-by months :legend true))
  (view (line-chart months passengers :group-by years :legend true))


  (def seasons (mapcat identity (repeat 3 ["winter" "spring" "summer" "fall"])))
  (def years (mapcat identity (repeat 4 [2007 2008 2009])))
  (def x (sample-uniform 12 :integers true :max 100))
  (view (line-chart years x :group-by seasons :legend true))

  (view (line-chart ["a" "b" "c" "d" "e" "f"] [10 20 30 10 40 20]))

  (view (line-chart (sample "abcdefghij" :size 10 :replacement true)
                       (sample-uniform 10 :max 50) :legend true))

  ;; add a series label
  (def plot (line-chart ["a" "b" "c"] [10 20 30] :legend true :series-label "s1"))
  (view plot)
  (add-categories plot ["a" "b" "c"] [5 25 40] :series-label "s2")


  (view (line-chart :year :passengers :group-by :month :legend true :data data))

  (view (line-chart :month :passengers :group-by :year :legend true :data data))

  (with-data data
    (view (line-chart :month :passengers :group-by :year :legend true)))

  (with-data (->> ($rollup :sum :passengers :year (get-dataset :airline-passengers))
                  ($order :year :asc))
    (view (line-chart :year :passengers)))

  (with-data (->> ($rollup :sum :passengers :month (get-dataset :airline-passengers))
                  ($order :passengers :asc))
    (view (line-chart :month :passengers)))


  (with-data ($rollup :sum :passengers :month (get-dataset :airline-passengers))
    (view (line-chart :month :passengers)))



References:
  http://www.jfree.org/jfreechart/api/javadoc/
  http://www.jfree.org/jfreechart/api/javadoc/org/jfree/chart/JFreeChart.html

Usage: (log-axis & options)

Create a logarithmic axis.

Note: By default, values smaller than 0.5 are rounded to 0.5 to prevent strange behavior that
happens for values close to 0.

Options:
  :base (default 10) base of the logarithm; typically 2 or 10
  :label (default none) the label of the axis
  :int-ticks? (default true) if true, use normal numbers instead of
     <base>^<exponent>, i.e. 1 instead of f.ex. 10^0.0
  :smallest-value (default: 0.5) Set the smallest value represented by the axis, set to 0.0 to 'reset'

See also:
  set-axis

References:
  http://www.jfree.org/jfreechart/api/javadoc/
  http://www.jfree.org/jfreechart/api/javadoc/org/jfree/chart/axis/LogAxis.html

Usage: (parametric-plot function min-range max-range & options)

Returns a xy-plot object of the given parametric function over the range indicated
by the min-range and max-range arguments. Use the 'view' function to
display the chart, or the 'save' function to write it to a file.
Function must take 1 argument - parameter t and return point [x y].

Options:
  :title (default '') main title
  :x-label (default 'min-x < x < max-x')
  :y-label (default 'min-y < y < max-y')
  :legend (default false) prints legend
  :series-label (default function expression)
  :step-size (default (/ (- max-range min-range) 500))

See also:
  view, save, add-parametric, function-plot


Examples:

  (use '(incanter core charts))

  (defn circle [t] [(cos t) (sin t)])
  (view (parametric-plot circle (- Math/PI) Math/PI))

  (defn spiral [t] [(* t (cos t)) (* t (sin t))])
  (view (parametric-plot spiral 0 (* 6 Math/PI)))

Usage: (pie-chart categories values & options)

Returns a JFreeChart object representing a pie-chart of the given data.
Use the 'view' function to display the chart, or the 'save' function
to write it to a file.

Arguments:
  categories -- a sequence of categories
  values -- a sequence of numeric values

Options:
  :title (default '') main title
  :legend (default false) prints legend


See also:
  view and save

Examples:


  (use '(incanter core stats charts datasets))

  (view (pie-chart ["a" "b" "c"] [10 20 30]))

   (view (pie-chart (sample "abcdefghij" :size 10 :replacement true)
                   (sample-uniform 10 :max 50) :legend true))


   (with-data (->> (get-dataset :hair-eye-color)
                   ($rollup :sum :count [:hair :eye]))
     (view $data)
     (view (pie-chart :hair :count :title "Hair Color"))
     (view (pie-chart :eye :count :title "Eye Color")))



References:
  http://www.jfree.org/jfreechart/api/javadoc/
  http://www.jfree.org/jfreechart/api/javadoc/org/jfree/chart/JFreeChart.html

Usage: (qq-plot x & options)

Returns a QQ-Plot object. Use the 'view' function to display it.

Options:
  :data (default nil) If the :data option is provided a dataset,
                      a column name can be used instead of a sequence
                      of data for argument x.

References:
  http://en.wikipedia.org/wiki/QQ_plot

Examples:

  (use '(incanter core stats charts datasets))
  (view (qq-plot (sample-normal 100)))
  (view (qq-plot (sample-exp 100)))
  (view (qq-plot (sample-gamma 100)))

  (with-data (get-dataset :iris)
    (view (qq-plot :Sepal.Length)))

Usage: (remove-series chart series-label)

Remove an existing series speicified by series-lab.
If the series does not exist it return nil

Usage: (scatter-plot)
       (scatter-plot x y & options)

Returns a JFreeChart object representing a scatter-plot of the given data.
Use the 'view' function to display the chart, or the 'save' function
to write it to a file.

Options:
  :title (default '') main title
  :x-label (default x expression)
  :y-label (default 'Frequency')
  :legend (default false) prints legend
  :series-label (default x expression)
  :group-by (default nil) -- a vector of values used to group the x and y values into series.
  :density? (default false) -- chart will represent density instead of frequency.
  :nbins (default 10) -- number of bins (i.e. bars)
  :gradient? (default false) -- use gradient on bars

See also:
  view, save, add-points, add-lines

Examples:

  (use '(incanter core stats charts datasets))
  ;; create some data
  (def mvn-samp (sample-mvn 1000 :mean [7 5] :sigma (matrix [[2 1.5] [1.5 3]])))

  ;; create scatter-plot of points
  (def mvn-plot (scatter-plot (sel mvn-samp :cols 0) (sel mvn-samp :cols 1)))
  (view mvn-plot)

  ;; add regression line to scatter plot
  (def x (sel mvn-samp :cols 0))
  (def y (sel mvn-samp :cols 1))
  (def lm (linear-model y x))
  (add-lines mvn-plot x (:fitted lm))

  ;; use :group-by option
  (use '(incanter core stats datasets charts))
  ;; load the :iris dataset
  (def iris (get-dataset :iris))
  ;; plot the first two columns grouped by the fifth column
  (view (scatter-plot ($ :Sepal.Width iris) ($ :Sepal.Length iris) :group-by ($ :Species iris)))

  (view (scatter-plot :Sepal.Length :Sepal.Width :data (get-dataset :iris)))

  (view (scatter-plot :Sepal.Length :Sepal.Width :group-by :Species :data (get-dataset :iris)))

  (with-data (get-dataset :iris)
     (view (scatter-plot :Sepal.Length :Sepal.Width)))

  (with-data (get-dataset :iris)
     (view (scatter-plot :Sepal.Length :Sepal.Width :group-by :Species)))



References:
  http://www.jfree.org/jfreechart/api/javadoc/
  http://www.jfree.org/jfreechart/api/javadoc/org/jfree/chart/JFreeChart.html

Usage: (scatter-plot-matrix & opts)

Returns a JFreeChart object displaying a scatter plot matrix for the given data.
Use the 'view' function to display the chart or 'save' to write it to a file.

Use:
  (scatter-plot-matrix & options)
  (scatter-plot-matrix data & options)

Options:
  :data data (default $data) the data set for the plot.
  :title s (default "Scatter Plot Matrix").
  :nbins n (default 10) number of bins (ie. bars) in histogram.
  :group-by grp (default nil) name of the column for grouping data.
  :only-first n (default 6) show only the first n most correlating columns of the data set.
  :only-triangle b (default false) shows only the upper triangle of the plot matrix.

Examples:
  (use '(incanter core stats charts datasets pdf))
  (view (scatter-plot-matrix (get-dataset :iris) :nbins 20 :group-by :Species ))
  (with-data (get-dataset :iris) (view (scatter-plot-matrix :nbins 20 :group-by :Species )))
  (view (scatter-plot-matrix (get-dataset :chick-weight) :group-by :Diet :nbins 20))

  ;;;Input examples for Iris
  ;; Input dataset examples: Incanter data repo, local file, remote file (url)
  (def iris (get-dataset :iris))
  (def iris (read-dataset "data/iris.dat" :delim \space :header true)) ; relative to project home
  (def iris (read-dataset "https://raw.github.com/liebke/incanter/master/data/iris.dat" :delim \space :header true))
  ;; Filter dataset to specific columns only
  (def iris ($ [:Sepal.Length :Sepal.Width :Petal.Length :Petal.Width :Species] (get-dataset :iris)))
  (def iris (sel (get-dataset :iris) :cols [:Sepal.Length :Sepal.Width :Petal.Length :Petal.Width :Species]))

  ;;; Scatter plot matrix examples
  ;; Using default options
  (def iris-spm (scatter-plot-matrix iris :group-by :Species))
  ;; filter to metrics only, no categorical dimension for grouping
  (def iris-spm (scatter-plot-matrix :data ($ [:Sepal.Length :Sepal.Width :Petal.Length :Petal.Width] iris)))

  ;; Using more options
  (def iris-spm (scatter-plot-matrix iris
                                     :title "Iris Scatter Plot Matrix"
                                     :bins 20 ; number of histogram bars
                                     :group-by :Species
                                     :only-first 4 ; most correlating columns
                                     :only-triangle false))

  ;;;Output examples
  ;; View on Display
  (view iris-spm :width 1280 :height 800)
  ;; Save as PDF
  (save-pdf  iris-spm "out/iris-spm.pdf" :width 2560 :height 1600)
  ;; Save as PNG
  (save iris-spm "out/iris-spm.png" :width 2560 :height 1600)

  ;; Airline dataset
  (def airline ($ [:year :passengers :month] (read-dataset "https://raw.github.com/liebke/incanter/master/data/airline_passengers.csv" :header true)))
  (def airline-spm (scatter-plot-matrix airline  :group-by :month :bins 20 :title "Airline Scatter Plot Matrix"))
  (view airline-spm)
  ;; Chick-weight dataset
  (view (scatter-plot-matrix (get-dataset :chick-weight) :group-by :Diet :bins 20 :title "Chick-weight Scatter Plot Matrix" ))

Usage: (set-alpha chart alpha)

Sets the alpha level (transparency) of the plot's foreground
returns the modified chart object.

References:
  http://www.jfree.org/jfreechart/api/javadoc/
  http://www.jfree.org/jfreechart/api/javadoc/org/jfree/chart/JFreeChart.html

No usage documentation available

Set the selected axis of the chart, returning the chart.
(Beware: the axis' label will replace axis label set previously on the chart.)

Arguments:
  chart - the JFreeChart object whose axis to change
  dimension - depends on the plot type for plots with mutliple axes
               f.ex. :x or :y for an XYPlot (x is the domain axis, y the range one)
  axis - the axis to set, an instance of ValueAxis

See also:
  log-axis

Note:
  Not applicable to DialPlot MeterPlot PiePlot MultiplePiePlot CompassPlot WaferMapPlot SpiderWebPlot

References:
  http://www.jfree.org/jfreechart/api/javadoc/
  http://www.jfree.org/jfreechart/api/javadoc/org/jfree/chart/axis/ValueAxis.html
  http://www.jfree.org/jfreechart/api/javadoc/org/jfree/chart/plot/XYPlot.html

Examples:

  (use '(incanter core charts))

  (view
    (doto (function-plot #(Math/pow 10 %) 0 5)
          (set-axis :x (log-axis :base 10, :label "log(x)"))))

Usage: (set-background-alpha chart alpha)

Sets the alpha level (transparency) of the plot's background
returns the modified chart object.

References:
  http://www.jfree.org/jfreechart/api/javadoc/
  http://www.jfree.org/jfreechart/api/javadoc/org/jfree/chart/JFreeChart.html

No usage documentation available

Examples:
  (use '(incanter core stats charts datasets))

  (doto (histogram (sample-normal 1000) :title (str :Test-Tittle))
    set-theme-bw
    view)


  (doto (histogram (sample-normal 1000))
    set-background-default
    (add-histogram (sample-normal 1000 :mean 1))
    view)


  (doto (scatter-plot :speed :dist :data (get-dataset :cars))
    set-theme-bw
    view)

  (doto (scatter-plot :speed :dist :data (get-dataset :cars))
    set-theme-bw
    (set-stroke :dash 5)
    (add-points (plus ($ :speed (get-dataset :cars)) 5) (plus ($ :dist (get-dataset :cars)) 10))
    view)

  (doto (scatter-plot :speed :dist :data (get-dataset :cars))
    set-background-default
    (set-stroke :dash 5)
    (add-function sin 0 25)
    view)


  (doto (xy-plot :speed :dist :data (get-dataset :cars) :legend true)
    set-background-default
    view)


  (doto (scatter-plot :speed :dist :data (get-dataset :cars))
    set-background-default
    view)


  (doto (box-plot (sample-gamma 1000 :shape 1 :scale 2)
                  :legend true)
    view set-background-default
    (add-box-plot (sample-gamma 1000 :shape 2 :scale 2))
    (add-box-plot (sample-gamma 1000 :shape 3 :scale 2)))


  (doto (bar-chart [:a :b :c] [10 20 30] :legend true)
    view
    set-background-default
    (add-categories [:a :b :c] [5 25 40]))


  (doto (line-chart [:a :b :c] [10 20 30] :legend true)
    view
    set-background-default
    (add-categories [:a :b :c] [5 25 40]))

  ;; time-series-plot
  (def epoch 0)
  (defn num-years-to-milliseconds [x]
    (* 365 24 60 60 1000 x))
  (def dates (map num-years-to-milliseconds (range 100)))
  (def chart1 (time-series-plot dates (range 100)))
  (def cw1 (view chart1))
  (add-lines chart1 dates (mult 1/2 (range 100)))

  (def chart2 (time-series-plot (take 10 dates) (mult 1/2 (range 10))))
  (def cw2 (view chart2))

Usage: (set-point-size chart point-size & {:keys [series dataset], :or {series :all, dataset 0}})

Set the point size of a scatter plot. Use series option to apply
point-size to only one series.

Usage: (set-stroke chart & options)

Examples:
  (use '(incanter core charts))

  (doto (line-chart [:a :b :c :d] [10 20 5 35])
    (set-stroke :width 4 :dash 5)
    view)

  (doto (line-chart [:a :b :c :d] [10 20 5 35])
    (add-categories [:a :b :c :d] [20 5 30 15])
    (set-stroke :width 4 :dash 5)
    (set-stroke :series 1 :width 2 :dash 10)
    view)


  (doto (function-plot sin -10 10 :step-size 0.1)
    (set-stroke :width 3 :dash 5)
    view)

  (doto (line-chart [:a :b :c :d] [10 20 5 35])
    (add-categories [:a :b :c :d] [20 5 30 15])
    (set-stroke :series 0 :width 4 :dash 5)
    (set-stroke :series 1 :width 4 :dash 5 :cap java.awt.BasicStroke/CAP_SQUARE))

Usage: (set-stroke-color chart color & options)

Examples:
  (use '(incanter core charts))

  (doto (line-chart [:a :b :c :d] [10 20 5 35])
    (set-stroke :width 4 :dash 5)
    (set-stroke-color java.awt.Color/blue)
    view)

  (doto (xy-plot [1 2 3] [4 5 6])
    (add-points [1 2 3] [4.1 5.1 6.1])
    (set-stroke-color java.awt.Color/black :series 0)
    (set-stroke-color java.awt.Color/red :series 1))

  (doto (function-plot sin -10 10 :step-size 0.1)
    (set-stroke :width 3 :dash 5)
    (set-stroke-color java.awt.Color/gray)
    view)

Usage: (set-theme chart theme)

Changes the chart theme.

Arguments:
  chart -- an Incanter/JFreeChart object
  theme -- either a keyword indicating one of the built-in themes, or a JFreeChart ChartTheme object.

Built-in Themes:
  :default
  :dark

Examples:

  (use '(incanter core charts))
  (def chart (function-plot sin -4 4))
  (view chart)
  ;; change the theme of chart to :dark
  (set-theme chart :dark)
  ;; change it back to the default
  (set-theme chart :default)

  ;; Example using JFreeTheme
  (use '(incanter core stats charts datasets))

  (import '(org.jfree.chart StandardChartTheme)
          '(org.jfree.chart.plot DefaultDrawingSupplier)
          '(java.awt Color))

  (def all-red-theme
    (doto
      (StandardChartTheme/createJFreeTheme)
      (.setDrawingSupplier
      (proxy [DefaultDrawingSupplier] []
        (getNextPaint [] Color/red)))))

  (def data (get-dataset :airline-passengers))

  (def chart (bar-chart :month :passengers :group-by :year :legend true :data data))

  (doto chart
    ;; has no effect
    (set-theme all-red-theme)
    view)


References:
  http://www.jfree.org/jfreechart/api/javadoc/org/jfree/chart/StandardChartTheme.html
  http://www.jfree.org/jfreechart/api/javadoc/org/jfree/chart/ChartTheme.html

No usage documentation available

Examples:
  (use '(incanter core stats charts datasets))

  (doto (histogram (sample-normal 1000))
    set-theme-bw
    view)


  (doto (histogram (sample-normal 1000))
    set-theme-bw
    (add-histogram (sample-normal 1000 :mean 1))
    view)


  (doto (scatter-plot :speed :dist :data (get-dataset :cars))
    set-theme-bw
    view)

  (doto (scatter-plot :speed :dist :data (get-dataset :cars))
    set-theme-bw
    (set-stroke :dash 5)
    (add-points (plus ($ :speed (get-dataset :cars)) 5) (plus ($ :dist (get-dataset :cars)) 10))
    view)

  (doto (scatter-plot :speed :dist :data (get-dataset :cars))
    set-theme-bw
    (set-stroke :dash 5)
    (add-function sin 0 25)
    view)


  (doto (xy-plot :speed :dist :data (get-dataset :cars))
    set-theme-bw
    view)


  (doto (scatter-plot :speed :dist :data (get-dataset :cars))
    set-theme-bw
    (add-lines :speed :dist :data (get-dataset :cars))
    view)


  (doto (box-plot (sample-gamma 1000 :shape 1 :scale 2)
                  :legend true)
    view
    (add-box-plot (sample-gamma 1000 :shape 2 :scale 2))
    (add-box-plot (sample-gamma 1000 :shape 3 :scale 2))
    set-theme-bw)


  (doto (bar-chart [:a :b :c] [10 20 30] :legend true)
    view
    set-theme-bw
    (add-categories [:a :b :c] [5 25 40]))


  (doto (line-chart [:a :b :c] [10 20 30] :legend true)
    view
    set-theme-bw
    (add-categories [:a :b :c] [5 25 40]))

Usage: (set-title chart title)

Sets the main title of the plot, returns the modified chart object.

References:
  http://www.jfree.org/jfreechart/api/javadoc/
  http://www.jfree.org/jfreechart/api/javadoc/org/jfree/chart/JFreeChart.html

Usage: (set-x-label chart label)

Sets the label of the x-axis, returns the modified chart object.

References:
  http://www.jfree.org/jfreechart/api/javadoc/
  http://www.jfree.org/jfreechart/api/javadoc/org/jfree/chart/JFreeChart.html

Usage: (set-x-range chart lower upper)

Sets the range of the x-axis on the given chart.

Examples:

  (use '(incanter core charts datasets))

  (def chart (xy-plot :speed :dist :data (get-dataset :cars)))
  (view chart)
  (set-x-range chart 10 20)

Usage: (set-y-label chart label)

Sets the label of the y-axis, returns the modified chart object.

References:
  http://www.jfree.org/jfreechart/api/javadoc/
  http://www.jfree.org/jfreechart/api/javadoc/org/jfree/chart/JFreeChart.html

Usage: (set-y-range chart lower upper)

Sets the range of the y-axis on the given chart.

Examples:

  (use '(incanter core charts datasets))

  (def chart (xy-plot :speed :dist :data (get-dataset :cars)))
  (view chart)
  (set-y-range chart 10 60)

Usage: (slider updater-fn slider-values)
       (slider updater-fn slider-values slider-label)

Examples:
  (use '(incanter core stats charts))

  (def pdf-chart (function-plot pdf-normal -3 3))
  (view pdf-chart)
  (add-function pdf-chart pdf-normal -3 3)

  (let [x (range -3 3 0.1)]
    (slider #(set-data pdf-chart [x (pdf-normal x :sd %)]) (range 0.1 10 0.1)))

  (let [x (range -3 3 0.1)]
    (slider #(set-data pdf-chart [x (pdf-normal x :sd %)]) (range 0.1 10 0.1) "sd"))

Usage: (sliders [& slider-bindings] body)

Creates one slider control for each of the given sequence bindings.
Each slider calls the given expression when manipulated.


Examples:
  (use '(incanter core stats charts))

  ;; manipulate a normal pdf
  (let [x (range -3 3 0.1)]
    (def pdf-chart (xy-plot))
    (view pdf-chart)
    (sliders [mean (range -3 3 0.1)
              stdev (range 0.1 10 0.1)]
      (set-data pdf-chart [x (pdf-normal x :mean mean :sd stdev)])))


  ;; manipulate a gamma pdf
  (let [x (range 0 20 0.1)]
    (def pdf-chart (xy-plot))
    (view pdf-chart)
    (sliders [scale (range 0.1 10 0.1)
              shape (range 0.1 10 0.1)]
             (set-data pdf-chart [x (pdf-gamma x :scale scale :shape shape)])))



  ;; find the start values of a non-linear model function
  (use '(incanter core charts datasets))
  ;; create model function used in the following data-sorcery post:
  ;; http://data-sorcery.org/2009/06/06/fitting-non-linear-models/

  (defn f [theta x]
    (let [[b1 b2 b3] theta]
      (div (exp (mult (minus b1) x)) (plus b2 (mult b3 x)))))

  (with-data (get-dataset :chwirut)
    (view $data)
    (def chart (scatter-plot ($ :x) ($ :y)))
    (view chart)
    (add-lines chart ($ :x) (f [0 0.01 0] ($ :x)))

    ;; manipulate the model line to find some good start values.
    ;; give the index of the line data (i.e. 1) to set-data.
    (let [x ($ :x)]
      (sliders [b1 (range 0 2 0.01)
                b2 (range 0.01 2 0.01)
                b3 (range 0 2 0.01)]
        (set-data chart [x (f [b1 b2 b3] x)] 1))))

Usage: (sliders* f [& slider-values])
       (sliders* f [& slider-values] [& slider-labels])

sliders*

Examples:
  (use '(incanter core stats charts))

  (let [x (range -3 3 0.1)]
    (do
      (def pdf-chart (xy-plot x (pdf-normal x :mean -3 :sd 0.1)))
      (view pdf-chart)
      (sliders* #(set-data pdf-chart [x (pdf-normal x :mean %1 :sd %2)])
               [(range -3 3 0.1) (range 0.1 10 0.1)]
               ["mean" "sd"])))

Usage: (stacked-area-chart categories values & options)

Returns a JFreeChart object representing an stacked-area-chart of the given data.
Use the 'view' function to display the chart, or the 'save' function
to write it to a file.

Arguments:
  categories -- a sequence of categories
  values -- a sequence of numeric values

Options:
  :title (default '') main title
  :x-label (default 'Categories')
  :y-label (default 'Value')
  :series-label
  :legend (default false) prints legend
  :vertical (default true) the orientation of the plot
  :group-by (default nil) -- a vector of values used to group the values into
                             series within each category.


See also:
  view and save

Examples:


  (use '(incanter core stats charts datasets))

  (with-data (get-dataset :co2)
    (view (stacked-area-chart :Type :uptake
                     :title "CO2 Uptake"
                     :group-by :Treatment
                     :x-label "Grass Types" :y-label "Uptake"
                    :legend true)))


  (def data (get-dataset :airline-passengers))
  (view (stacked-area-chart :year :passengers :group-by :month :legend true :data data))

  (with-data  (get-dataset :airline-passengers)
    (view (stacked-area-chart :month :passengers :group-by :year :legend true)))


  (def data (get-dataset :austres))
  (view data)
  (def plot (stacked-area-chart :year :population :group-by :quarter :legend true :data data))
  (view plot)
  (save plot "/tmp/austres_plot.png" :width 1000)
  (view "file:///tmp/austres_plot.png")


  (def seasons (mapcat identity (repeat 3 ["winter" "spring" "summer" "fall"])))
  (def years (mapcat identity (repeat 4 [2007 2008 2009])))
  (def values (sample-uniform 12 :integers true :max 100))
  (view (stacked-area-chart years values :group-by seasons :legend true))

  (view (stacked-area-chart ["a" "a" "b" "b" "c" "c" ] [10 20 30 10 40 20]
                   :legend true
                   :group-by ["I" "II" "I" "II" "I" "II"]))


References:
  http://www.jfree.org/jfreechart/api/javadoc/
  http://www.jfree.org/jfreechart/api/javadoc/org/jfree/chart/JFreeChart.html

Usage: (stacked-bar-chart categories values & options)

Returns a JFreeChart object representing an stacked-bar-chart of the given data.
Use the 'view' function to display the chart, or the 'save' function
to write it to a file.

Arguments:
  categories -- a sequence of categories
  values -- a sequence of numeric values

Options:
  :title (default '') main title
  :x-label (default 'Categories')
  :y-label (default 'Value')
  :series-label
  :legend (default false) prints legend
  :vertical (default true) the orientation of the plot
  :group-by (default nil) -- a vector of values used to group the values into
                             series within each category.


See also:
  view and save

Examples:


  (use '(incanter core stats charts datasets))

  (with-data (get-dataset :co2)
    (view (stacked-bar-chart :Type :uptake
                     :title "CO2 Uptake"
                     :group-by :Treatment
                     :x-label "Grass Types" :y-label "Uptake"
                    :legend true)))


  (def data (get-dataset :airline-passengers))
  (view (stacked-bar-chart :year :passengers :group-by :month :legend true :data data))

  (with-data  (get-dataset :airline-passengers)
    (view (stacked-bar-chart :month :passengers :group-by :year :legend true)))


  (def data (get-dataset :austres))
  (view data)
  (def plot (stacked-bar-chart :year :population :group-by :quarter :legend true :data data))
  (view plot)
  (save plot "/tmp/austres_plot.png" :width 1000)
  (view "file:///tmp/austres_plot.png")


  (def seasons (mapcat identity (repeat 3 ["winter" "spring" "summer" "fall"])))
  (def years (mapcat identity (repeat 4 [2007 2008 2009])))
  (def values (sample-uniform 12 :integers true :max 100))
  (view (stacked-bar-chart years values :group-by seasons :legend true))

  (view (stacked-bar-chart ["a" "b" "c"] [10 20 30]))
  (view (stacked-bar-chart ["a" "a" "b" "b" "c" "c" ] [10 20 30 10 40 20]
                   :legend true
                   :group-by ["I" "II" "I" "II" "I" "II"]))

  ;; add a series label
  (def plot (stacked-bar-chart ["a" "b" "c"] [10 20 30] :legend true :series-label "s1"))
  (view plot)
  (add-categories plot ["a" "b" "c"] [5 25 40] :series-label "s2")

  (view (stacked-bar-chart (sample "abcdefghij" :size 10 :replacement true)
                   (sample-uniform 10 :max 50) :legend true))



References:
  http://www.jfree.org/jfreechart/api/javadoc/
  http://www.jfree.org/jfreechart/api/javadoc/org/jfree/chart/JFreeChart.html

Usage: (time-series-plot x y & options)

Returns a JFreeChart object representing a time series plot of the given data.
Use the 'view' function to display the chart, or the 'save' function
to write it to a file. Sequence passed in for the x axis should be
number of milliseconds from the epoch (1 January 1970).

Options:
  :data (default nil) If the :data option is provided a dataset,
                      column names can be used instead of sequences
                      of data as arguments to xy-plot.
  :title (default '') main title
  :x-label (default x expression)
  :y-label (default y expression)
  :legend (default false) prints legend
  :series-label (default x expression)
  :group-by (default nil) -- a vector of values used to group the x and y values into series.

See also:
  view, save, add-points, add-lines

Examples:

  (use '(incanter core stats charts))
  (require '[clj-time.core :refer [date-time]])

  ;; plot numbers against years starting with 1900
  (def dates (map #(-> (date-time (+ 1900 %))
                       .getMillis)
                  (range 100)))
  (def y (range 100))
  (view (time-series-plot dates y
                          :x-label "Year"))

References:
  http://www.jfree.org/jfreechart/api/javadoc/
  http://www.jfree.org/jfreechart/api/javadoc/org/jfree/chart/JFreeChart.html

Usage: (trace-plot x & options)

Returns a trace-plot object, use the 'view' function to display it.

Options:
  :data (default nil) If the :data option is provided a dataset,
                      a column name can be used instead of a sequence
                      of data for argument x.
  :title (default 'Trace Plot') main title
  :x-label (default 'Iteration')
  :y-label (default 'Value')
  :series-label (default 'Value')

  Examples:
    (use '(incanter core datasets stats bayes charts))
    (def ols-data (to-matrix (get-dataset :survey)))
    (def x (sel ols-data (range 0 2313) (range 1 10)))
    (def y (sel ols-data (range 0 2313) 10))
    (def sample-params (sample-model-params 5000 (linear-model y x :intercept false)))
    (view (trace-plot (:var sample-params)))

    (view (trace-plot (sel (:coefs sample-params) :cols 0)))

Usage: (xy-plot)
       (xy-plot x y & options)

Returns a JFreeChart object representing a xy-plot of the given data.
Use the 'view' function to display the chart, or the 'save' function
to write it to a file.

Options:
  :data (default nil) If the :data option is provided a dataset,
                      column names can be used instead of sequences
                      of data as arguments to xy-plot.
  :title (default 'XY Plot') main title
  :x-label (default x expression)
  :y-label (default 'Frequency')
  :legend (default false) prints legend
  :series-label (default x expression)
  :group-by (default nil) -- a vector of values used to group the x and y values into series.
  :points (default false) includes point-markers
  :auto-sort (default true) sort data by x

See also:
  view, save, add-points, add-lines

Examples:

  (use '(incanter core stats charts))

  ;; plot the cosine function
  (def x (range -1 5 0.01))
  (def y (cos (mult 2 Math/PI x)))
  (view (xy-plot x y))

  ;; plot gamma pdf with different parameters
  (def x2 (range 0 20 0.1))
  (def gamma-plot (xy-plot x2 (pdf-gamma x2 :shape 1 :scale 2)
                             :legend true
                             :title "Gamma PDF"
                             :y-label "Density"))
  (view gamma-plot)
  (add-lines gamma-plot x2 (pdf-gamma x2 :shape 2 :scale 2))
  (add-lines gamma-plot x2 (pdf-gamma x2 :shape 3 :scale 2))
  (add-lines gamma-plot x2 (pdf-gamma x2 :shape 5 :scale 1))
  (add-lines gamma-plot x2 (pdf-gamma x2 :shape 9 :scale 0.5))

  ;; use :group-by option
  (use '(incanter core charts datasets))

  (with-data (get-dataset :chick-weight)
    (view (xy-plot :Time :weight :group-by :Chick)))


  ;; see INCANTER_HOME/examples/probability_plots.clj for more examples of plots

References:
  http://www.jfree.org/jfreechart/api/javadoc/
  http://www.jfree.org/jfreechart/api/javadoc/org/jfree/chart/JFreeChart.html