Merge b7553c0 into 2ea9744

demo.md

@@ -5,16 +5,13 @@ graphics system for Julia. Though currently far from complete, some basics are
 up and running. This document will show some examples of what currently works
 while giving you a feel for the overall system.
 
-To begin, we need some data. The data Gadfly plots is always given in the form
+To begin, we need some data. The data Gadfly plots can be given in the form
 of a DataFrame. We'll pick and choose some examples from the RDatasets packages.
 
 Fisher's iris data set is a good starting point.
 
 ```julia
-load("Gadfly")
 using Gadfly
-
-load("RDatasets")
 using RDatasets
 
 iris = data("datasets", "iris")
@@ -34,34 +31,30 @@ grammar.
 Let's get to it.
 
 ```julia
-p = plot(iris, {:x => "Sepal.Length", :y => "Sepal.Width"}, Geom.point)
+p = plot(iris, x="SepalLength", y="SepalWidth", Geom.point)
 ```
 
-This produces a `Plot` object. We can turn it into a graphic by calling `render`
-on it, and this can then in turn be drawn on one or more backends.
+This produces a `Plot` object. It can be drawn on one or more backends using `draw`.
 
 ```julia
-g = render(p)
-
 img = SVG("iris_plot.svg", 6inch, 4inch)
-draw(img, g)
-finish(img)
+draw(img, p)
 ```
 
 Now we have the following charming little SVG image.
 
 ![Iris Plot 1](http://dcjones.github.com/gadfly/iris1.svg)
 
-For the rest of the demonstrations, we'll omit the `render` and `draw` calls for
+For the rest of the demonstrations, we'll omit the `draw` call for
 brevity.
 
-In this plot we've mapped the x aesthetic to the `Sepal.Length` column and the y
-aesthetic to the `Sepal.Width`. The last argument, `Geom.point`, is a geometry
+In this plot we've mapped the x aesthetic to the `SepalLength` column and the y
+aesthetic to the `SepalWidth`. The last argument, `Geom.point`, is a geometry
 element which takes bound aesthetics and render delightful figures. Adding other
 geometries produces layers, which may or may not result in a coherent plot.
 
 ```julia
-p = plot(iris, {:x => "Sepal.Length", :y => "Sepal.Width"},
+p = plot(iris, x="SepalLength", y="SepalWidth",
          Geom.point, Geom.line)
 ```
 
@@ -75,7 +68,7 @@ furiously". It is valid grammar, but not particularly meaningful.
 Let's do add something meaningful by mapping the color aesthetic.
 
 ```julia
-p = plot(iris, {:x => "Sepal.Length", :y => "Sepal.Width", :color => "Species"},
+p = plot(iris, x="SepalLength", y="SepalWidth", color="Species",
          Geom.point)
 ```
 
@@ -95,7 +88,7 @@ useful.
 
 ```julia
 mammals = data("MASS", "mammals")
-p = plot(mammals, {:x => "body", :y => "brain"}, Geom.point)
+p = plot(mammals, x="body", y="brain", Geom.point)
 ```
 
 ![Mammal Plot 1](http://dcjones.github.com/gadfly/mammals1.svg)
@@ -104,7 +97,7 @@ This is no good, the whales are ruining things for us. Putting both axis on a
 log-scale clears things up.
 
 ```julia
-p = plot(mammals, {:x => "body", :y => "brain"},
+p = plot(mammals, x="body", y="brain",
          Geom.point, Scale.x_log10, Scale.y_log10)
 ```
 
@@ -118,14 +111,12 @@ crack at the latter using some fuel efficiency data.
 ```julia
 gasoline = data("Ecdat", "Gasoline")
 
-p = plot(gasoline, {:x => "year", :y => "lgaspcar", :color => "country"},
+p = plot(gasoline, x="year", y="lgaspcar", color="country",
          Geom.point, Geom.line)
 
 # Make this image wider so the axis labels fit
-g = render(p)
 img = SVG("gasoline_plot.svg", 9inch, 4inch)
-draw(img, g)
-finish(img)
+draw(img, p)
 ```
 
 ![Gasoline Plot 1](http://dcjones.github.com/gadfly/gasoline1.svg)
@@ -134,7 +125,7 @@ We could have added `Scale.x_discrete` explicitly, but this is detected and the
 right default is chosen. This is the case with most of elements in the grammar:
 we've omitted `Scale.x_continuous` and `Scale.y_continuous` in the previous
 plots, as well as `Coord.cartesian`, and guide elements such as
-`Guide.color_key`, `Guide.x_ticks`, `Guide.XLabel`, and so on. As much as
+`Guide.colorkey`, `Guide.xticks`, `Guide.xlabel`, and so on. As much as
 possible the system tries to fill in the gaps with reasonable defaults.
 
 ### Rendering
@@ -149,14 +140,12 @@ Building graphics declaratively let's you do some fun things. Like stick two
 plots together:
 
 ```julia
-fig1a = render(plot(iris, {:x => "Sepal.Length", :y => "Sepal.Width"},
-                    Geom.point))
-fig1b = render(plot(iris, {:x => "Sepal.Width"}, Geom.bar))
+fig1a = plot(iris, x="SepalLength", y="SepalWidth", Geom.point)
+fig1b = plot(iris, x="SepalWidth", Geom.bar)
 fig1 = hstack(fig1a, fig1b)
 
 img = SVG("fig1.svg", 9inch, 4inch)
 draw(img, fig1)
-finish(img)
 ```
 
 ![Fig1](http://dcjones.github.com/gadfly/fig1.svg)

doc/dev_pipeline.md

@@ -24,9 +24,9 @@ p = plot(df,
 		 Geom.bar)
 ```
 
-actually get turned into following plot?
+actually get turned into the following plot?
 
-```{.julia hide="true"}
+```{.julia hide="true" results="block"}
 df = dataset("ggplot2", "diamonds")
 p = plot(df,
          x = :Price, color = :Cut,
@@ -43,7 +43,7 @@ The specification of each layer has
 - a **data source** (e.g. `dataset("ggplot2", "diamonds")`)
 - a **geometry** to represent the layer's data (e.g. point, line, etc.)
 - **mappings** to associate aesthetics of the geometry with elements of the data source (e.g.  `:color => :Cut`)
-- layer-wise **statistics** (optional) to be applied to the layer's data 
+- layer-wise **statistics** (optional) to be applied to the layer's data
 
 All layers of a plot share the same
 

doc/geom_bar.md

@@ -7,7 +7,7 @@ order: 1003
 
 Draw bar plots. This geometry works on pre-summarized data such as counts. To
 draw histograms from a series of observations, add `Stat.histogram` to the plot,
-or use the conevient geometry `Geom.histogram`.
+or use the convenient geometry `Geom.histogram`.
 
 # Aesthetics
 

doc/geom_boxplot.md

@@ -23,7 +23,7 @@ Aesthetics used directly:
   * `upper_fence`
   * `outliers`
 
-With default statistic `Stat.boxplot`, only the following aesthetics need b
+With default statistic `Stat.boxplot`, only the following aesthetics need to be
 defined:
 
   * `x` (optional): Group categorically on the X-axis.

doc/geom_errorbar.md

@@ -5,7 +5,7 @@ part: Geometry
 order: 1002
 ...
 
-Draw an vertical and/or horizontal error bars.
+Draw vertical and/or horizontal error bars.
 
 # Aesthetics
 

doc/geom_hexbin.md

@@ -31,10 +31,7 @@ Gadfly.set_default_plot_size(14cm, 8cm)
 ```
 
 ```julia
-X = rand(MultivariateNormal([0.0, 0.0], [1.0 0.5; 0.5 1.0]), 10000)
-```
-
-```julia
+X = rand(MultivariateNormal([0.0, 0.0], [1.0 0.5; 0.5 1.0]), 10000);
 plot(x=X[1,:], y=X[2,:], Geom.hexbin)
 ```
 

doc/geom_histogram.md

@@ -21,7 +21,7 @@ Draw histograms. An alias for `Geom.bar` with `Stat.histogram`.
   * `orientation`: Either `:vertical` (default) or `:horizontal`. If
     `:horizontal`, then the required aesthetic is `y` instead of `x`.
   * `bincount`: Number of bins to use. If unspecified, an optimization method
-    be used to deterimine a reasonable value.
+    is used to determine a reasonable value.
   * `minbincount`: Set a lower limit when automatically choosing a bin count.
   * `maxbincount`: Set an upper limit when automatically choosing a bin count.
   * `density`: If true, use density rather that counts.

doc/geom_label.md

@@ -18,10 +18,6 @@ overlap, and hides any that would overlap.
 
 # Arguments
 
-```{.julia execute="false"}
-Geom.label(;hide_overlaps=true)
-```
-
   * `position`: One of `:dynamic`, `:left`, `:right`, `:above`, `:below`,
     `:centered`. If `:dynamic` is used, label positions will be adjusted to
     avoid overaps. Otherwise, labels will be statically positioned left, right,

doc/geom_path.md

@@ -32,6 +32,6 @@ plot(x=cumsum(xjumps),y=cumsum(yjumps),Geom.path())
 Here's a spiral:
 
 ```julia
-t = [0:0.2:8pi]
+t = 0:0.2:8pi
 plot(x=t.*cos(t), y=t.*sin(t), Geom.path)
 ```

doc/geom_rectbin.md

@@ -22,8 +22,8 @@ Or
   * x
   * y
 
-In the former case, an rectangles defined by `x_min`, `x_max`, `y_min`, `y_max`
-are drawn, in the latter, equal sizes sequares are centered at `x` and `y`
+In the former case, rectangles defined by `x_min`, `x_max`, `y_min`, `y_max`
+are drawn, in the latter, equal sizes squares are centered at `x` and `y`
 positions.
 
 # See Also

doc/geom_ribbon.md

@@ -5,7 +5,7 @@ part: Geometry
 order: 1014
 ...
 
-Draw a ribbon bounded above and below by `ymin` and `ymin`, respectively.
+Draw a ribbon bounded above and below by `ymin` and `ymax`, respectively.
 
 # Aesthetics
 

doc/geom_subplot_grid.md

@@ -5,16 +5,16 @@ part: Geometry
 order: 1011
 ...
 
-Draw multiple subplots in a grid orginized by one or two categorial vectors.
+Draw multiple subplots in a grid organized by one or two categorial vectors.
 
 
 # Aesthetics
 
   * `xgroup` (optional): Arrange subplots on the X-axis by categorial data.
   * `ygroup` (optional): Arrange subplots on the Y-axis by categorial data.
-  * `free_y_axis` (optional): Whether the y-axis scales can differ across 
+  * `free_y_axis` (optional): Whether the y-axis scales can differ across
   the subplots. Defaults to `false`. If `true`, scales are set appropriately for individual subplots.
-  * `free_x_axis` (optional): Whether the x-axis scales can differ across 
+  * `free_x_axis` (optional): Whether the x-axis scales can differ across
   the subplots. Defaults to `false`. If `true`, scales are set appropriately for individual subplots.
 
 

doc/index.md

@@ -130,7 +130,7 @@ plot(data::AbstractDataFrame, elements::Element...; mapping...)
 The [RDatasets](https://github.com/johnmyleswhite/RDatasets.jl) package collects
 example data sets from R packages. We'll use that here to generate some example
 plots on realistic data sets. An example data set is loaded into a data frame
-usinge the `data` function.
+using the `dataset` function.
 
 
 ```julia

doc/scale_color_continuous.md

@@ -0,0 +1,72 @@
+---
+title: color_continuous
+author: David Chudzicki
+part: Scale
+order: 2008
+...
+
+Create a continuous color scale that the plot will use.
+
+# Arguments
+
+  * `minvalue` (optional): the data value corresponding to the bottom of the color scale (will be based on the range of the data if not specified).
+  * `maxvalue` (optional): the data value corresponding to the top of the color scale (will be based on the range of the data if not specified).
+  * `colormap`: A function defined on the interval from 0 to 1 that returns a ```Color``` (as from the ```Colors``` package).
+
+# Variations
+
+```color_continuous``` and ```color_continuous_gradient``` are two names for the same thing.
+
+A number of transformed continuous scales are provided.
+
+  * `Scale.color_continuous` (scale without any transformation).
+  * `Scale.color_log10`
+  * `Scale.color_log2`
+  * `Scale.color_log`
+  * `Scale.color_asinh`
+  * `Scale.color_sqrt`
+
+# Aesthetics Acted On
+
+`color`
+
+# Examples
+
+```{.julia hide="true" results="none"}
+using Gadfly
+
+srand(1234)
+```
+
+```julia
+# The data are all between 0 and 1, but the color scale goes from -1 to 1.
+# For example, you might do this to force a consistent color scale between plots.
+plot(x=rand(12), y=rand(12), color=rand(12),
+     Scale.color_continuous(minvalue=-1, maxvalue=1))
+```
+
+Define a custom color scale for a grid:
+
+```julia
+using Colors
+x = repeat(collect(1:10), inner=[10])
+y = repeat(collect(1:10), outer=[10])
+plot(x=x, y=y, color=x+y, Geom.rectbin,
+     Scale.color_continuous(colormap=p->RGB(0,p,0)))
+```
+
+Or we can use ```lab_gradient``` to construct a color gradient between 2 or more colors:
+
+```julia
+plot(x=x, y=y, color=x+y, Geom.rectbin,
+     Scale.color_continuous(colormap=Scale.lab_gradient(colorant"green",
+                                                        colorant"white",
+                                                        colorant"red")))
+```
+
+We can also start the color scale somewhere other than the bottom of the data range using ```minvalue```:
+
+```julia
+plot(x=x, y=y, color=x+y, Geom.rectbin,
+     Scale.color_continuous(colormap=p->RGB(0,p,0), minvalue=-20))
+```