(defmacro add-categories
"
  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

"
  ([chart categories values & options]
    `(let [opts# ~(if options (apply assoc {} options) {})
           group-by# (:group-by opts#) 
           series-lab# (or (:series-label opts#) 
			   (if group-by#
			     (format "%s, %s (0)" '~categories '~values) 
			     (format "%s, %s" '~categories '~values)))
	   args# (concat [~chart ~categories ~values] 
			 (apply concat (seq (apply assoc opts# [:series-label series-lab#]))))]
       (apply add-categories* args#))))