working on contours

.gitignore

@@ -1,3 +1,5 @@
 *.jl.cov
 *.jl.*.cov
 *.jl.mem
+.DS_Store
+examples/.ipynb_checkpoints/*

.travis.yml

@@ -4,9 +4,11 @@ os:
   - linux
   - osx
 julia:
+  - 0.3
   - 0.4
+  - nightly
 notifications:
-  email: false
+  email: true
 # uncomment the following lines to override the default test script
 script:
  - if [[ -a .git/shallow ]]; then git fetch --unshallow; fi

README.md

@@ -1,224 +1,379 @@
 # Plots
 
 [![Build Status](https://travis-ci.org/tbreloff/Plots.jl.svg?branch=master)](https://travis-ci.org/tbreloff/Plots.jl)
+[![Plots](http://pkg.julialang.org/badges/Plots_0.3.svg)](http://pkg.julialang.org/?pkg=Plots&ver=0.3)
+[![Plots](http://pkg.julialang.org/badges/Plots_0.4.svg)](http://pkg.julialang.org/?pkg=Plots&ver=0.4)
+[![Plots](http://pkg.julialang.org/badges/Plots_0.5.svg)](http://pkg.julialang.org/?pkg=Plots&ver=0.5)
 
-Plotting interface and wrapper for several plotting packages.
+#### Author: Thomas Breloff (@tbreloff)
+
+Plots is a plotting interface and wrapper for several plotting packages.  My goals with the package are:
+
+- Simple.  The interface should be intuitive enough that someone coming from Matlab, Python, etc can immediately start generating complex plots without reading volumes of documentation.
+- Automatic (if you want).  There should be smart defaults for the most common functionality, and simple, high-level ways to override complex functionality.
+- Flexible.  You should be able to produce your favorite plot in your favorite package, but quicker and simpler.
+- Consistent.  Don't commit to one graphics package.  One command will switch your backend, and the exact same plotting commands will work with a very different underlying backend.
 
 Please add wishlist items, bugs, or any other comments/questions to the issues list.
 
-## Examples
+Check out the [summary graphs](img/supported/supported.md) for the features that each backend supports.
+
+## Examples for each implemented backend:
 
 - [Qwt.jl](docs/qwt_examples.md)
 - [Gadfly.jl](docs/gadfly_examples.md)
+- [UnicodePlots.jl](docs/unicodeplots_examples.md)
+- [PyPlot.jl](docs/pyplot_examples.md)
+- [Immerse.jl](docs/immerse_examples.md)
+- [Winston.jl](docs/winston_examples.md)
 
 ## Installation
 
-First, clone the package, and get any plotting packages you need:
+First, add the package
 
+```julia
+Pkg.add("Plots")
+
+# if you want the latest features:
+Pkg.checkout("Plots")
+
+# or for the bleeding edge:
+Pkg.checkout("Plots", "dev")
 ```
-Pkg.clone("https://github.com/tbreloff/Plots.jl.git")
-Pkg.add("Gadfly")                                     # [optional]
-Pkg.clone("https://github.com/tbreloff/Qwt.jl.git")   # [optional] requires pyqt and pyqwt
+
+then get any plotting packages you need (obviously, you should get at least one backend):
+
+```julia
+Pkg.add("Gadfly")
+Pkg.add("Immerse")
+Pkg.add("UnicodePlots")
+Pkg.add("PyPlot")                                    # requires python and matplotlib
+Pkg.clone("https://github.com/tbreloff/Qwt.jl.git")  # requires pyqt and pyqwt
+Pkg.add("Winston")
 ```
 
 ## Use
 
-Load it in.  The underlying plotting backends are not imported until `plotter()` is called (which happens
-on your first call to `plot`).  This means that you don't need any backends to be installed when you call `using Plots`.
-For now, the default backend is Gadfly.
+Load it in.  The underlying plotting backends are not imported until `backend()` is called (which happens
+on your first call to `plot` or `subplot`).  This means that you don't need any backends to be installed when you call `using Plots`.
+Plots will try to figure out a good default backend for you automatically based on what backends are installed.
 
-```
+```julia
 using Plots
 ```
 
-Do a plot in Gadfly, then save a png:
+Do a plot in Gadfly (inspired by [this example](http://gadflyjl.org/geom_point.html)), then save a png:
 
-```
-plot(rand(10,2); marker = :rect)
-savepng(Plots.IMG_DIR * "gadfly1.png")
-```
+```julia
+gadfly()        # switch to Gadfly as a backend
+dataframes()    # turn on support for DataFrames inputs
 
-which saves:
+# load some data
+using RDatasets
+iris = dataset("datasets", "iris");
+
+# This will bring up a browser window with the plot. Add a semicolon at the end to skip display. 
+scatter(iris, :SepalLength, :SepalWidth, group=:Species, m=([:+ :d :s], 12))
+
+# save a png (equivalent to png("gadfly1.png") and savefig("gadfly1.png"))
+png("gadfly1")
+```
 
 ![gadfly_plt](img/gadfly1.png)
 
+See the examples pages for lots of examples of plots, and what those commands produce for each supported backend.  
+Also check out the [IJulia notebooks](examples) and see how it works interactively.
 
-Do a plot in Qwt, then save a png:
+## API
 
-```
-plotter!(:qwt)  # switches the backend to Qwt
-plot(rand(10,2); marker = :rect)
-savepng(Plots.IMG_DIR * "qwt1.png")
-```
+Call `backend(backend::Symbol)` or the shorthands (`gadfly()`, `qwt()`, `unicodeplots()`, etc) to set the current plotting backend.
+Subsequent commands are converted into the relevant plotting commands for that package:
 
-which saves:
-
-![qwt_plt](img/qwt1.png)
-
-
-
-## plot and plotter! interface (WIP)
-
-The main plot command.  Call `plotter!(:module)` to set the current plotting backend.
-Commands are converted into the relevant plotting commands for that package:
-
-```
-  plotter!(:gadfly)
-  plot(1:10)    # this effectively calls `y = 1:10; Gadfly.plot(x=1:length(y), y=y)`
-  plotter!(:qwt)
-  plot(1:10)    # this effectively calls `Qwt.plot(1:10)`
+```julia
+gadfly()
+plot(1:10)    # this effectively calls `y = 1:10; Gadfly.plot(x=1:length(y), y=y)`
+qwt()
+plot(1:10)    # this effectively calls `Qwt.plot(1:10)`
 ```
 
 Use `plot` to create a new plot object, and `plot!` to add to an existing one:
 
-```
-  plot(args...; kw...)                  # creates a new plot window, and sets it to be the `currentPlot`
-  plot!(args...; kw...)                 # adds to the `currentPlot`
-  plot!(plotobj, args...; kw...)        # adds to the plot `plotobj`
+```julia
+plot(args...; kw...)                  # creates a new plot window, and sets it to be the `current`
+plot!(args...; kw...)                 # adds to the `current`
+plot!(plotobj, args...; kw...)        # adds to the plot `plotobj`
 ```
 
 Now that you know which plot object you're updating (new, current, or other), I'll leave it off for simplicity.
-Here are some various args to supply, and the implicit mapping (AVec == AbstractVector and AMat == AbstractMatrix):
+There are many ways to pass in data to the plot functions... some examples:
 
-```
-  plot(y::AVec; kw...)                       # one line... x = 1:length(y)
-  plot(x::AVec, y::AVec; kw...)              # one line (will assert length(x) == length(y))
-  plot(y::AMat; kw...)                       # multiple lines (one per column of x), all sharing x = 1:size(y,1)
-  plot(x::AVec, y::AMat; kw...)              # multiple lines (one per column of x), all sharing x (will assert length(x) == size(y,1))
-  plot(x::AMat, y::AMat; kw...)              # multiple lines (one per column of x/y... will assert size(x) == size(y))
-  plot(x::AVec, f::Function; kw...)          # one line, y = f(x)
-  plot(x::AMat, f::Function; kw...)          # multiple lines, yᵢⱼ = f(xᵢⱼ)
-  plot(x::AVec, fs::AVec{Function}; kw...)   # multiple lines, yᵢⱼ = fⱼ(xᵢ)
-  plot(y::AVec{AVec}; kw...)                 # multiple lines, each with x = 1:length(y[i])
-  plot(x::AVec, y::AVec{AVec}; kw...)        # multiple lines, will assert length(x) == length(y[i])
-  plot(x::AVec{AVec}, y::AVec{AVec}; kw...)  # multiple lines, will assert length(x[i]) == length(y[i])
-  plot(n::Integer; kw...)                    # n lines, all empty (for updating plots)
+- Vector-like (subtypes of AbstractArray{T,1})
+- Matrix-like (subtypes of AbstractArray{T,2})
+- Vectors of Vectors
+- Functions
+- Vectors of Functions
+- DataFrames with column symbols (initialize with `dataframes()`)
 
-  # TODO: how do we handle NA values in dataframes?
-  plot(df::DataFrame; kw...)                 # one line per DataFrame column, labels == names(df)
-  plot(df::DataFrame, columns; kw...)        # one line per column, but on a subset of column names
+In general, you can pass in a `y` only, or an `x` and `y`, both of whatever type(s) you want, and Plots will slice up the data as needed.
+For matrices, data is split by columns.  For functions, data is mapped.  For DataFrames, a Symbol/Symbols in place of x/y will map to
+the relevant column(s).
+
+Here are some example usages... remember you can always use `plot!` to update an existing plot, and that, unless specified, you will update the `current()`.
+
+```julia
+plot()                                    # empty plot object
+plot(4)                                   # initialize with 4 empty series
+plot(rand(10))                            # plot 1 series... x = 1:10
+plot(rand(10,5))                          # plot 5 series... x = 1:10
+plot(rand(10), rand(10))                  # plot 1 series
+plot(rand(10,5), rand(10))                # plot 5 series... y is the same for all
+plot(sin, rand(10))                       # y = sin(x)
+plot(rand(10), sin)                       # same... y = sin(x)
+plot([sin,cos], 0:0.1:π)                  # plot 2 series, sin(x) and cos(x)
+plot([sin,cos], 0, π)                     # plot sin and cos on the range [0, π]
+plot(1:10, Any[rand(10), sin])            # plot 2 series, y = rand(10) for the first, y = sin(x) for the second... x = 1:10 for both
+plot(dataset("Ecdat", "Airline"), :Cost)  # plot from a DataFrame (call `dataframes()` first to import DataFrames and initialize)
 ```
 
-[TODO] You can swap out `plot` for `subplot`.  Each line will go into a separate plot.  Use the layout keyword:
+All plot methods accept a number of keyword arguments (see the tables below), which follow some rules:
+- Many arguments have aliases which are replaced during preprocessing.  `c` is the same as `color`, `m` is the same as `marker`, etc.  You can choose how verbose you'd like to be.  (see the tables below)
+- There are some special arguments (`xaxis`, `yaxis`, `line`, `marker`, `fill` and the aliases `l`, `m`, `f`) which magically set many related things at once.  (see the __Tip__ below)
+- If the argument is a "matrix-type", then each column will map to a series, cycling through columns if there are fewer columns than series.  Anything else will apply the argument value to every series.
+- Many arguments accept many different types... for example the `color` (also `markercolor`, `fillcolor`, etc) argument will accept strings or symbols with a color name, or any `Colors.Colorant`, or a `ColorScheme`, or a symbol representing a `ColorGradient`, or an AbstractVector of colors/symbols/etc...
 
+You can update certain plot settings after plot creation (not supported on all backends):
+
+```julia
+plot!(title = "New Title", xlabel = "New xlabel", ylabel = "New ylabel")
+plot!(xlims = (0, 5.5), ylims = (-2.2, 6), xticks = 0:0.5:10, yticks = [0,1,5,10])
+
+# using shorthands:
+xaxis!("mylabel", :log10, :flip)
 ```
-  y = rand(100,3)
-  subplot(y; layout=(2,2), kw...)           # creates 3 lines going into 3 separate plots, laid out on a 2x2 grid (last row is filled with plot #3)
-  subplot(y; layout=(1,3), kw...)           # again 3 plots, all in the same row
-  subplot(y; layout=[1,[2,3]])              # pass a nested Array to fully specify the layout.  here the first plot will take up the first row, 
-                                            # and the others will share the second row
+
+With `subplot`, create multiple plots at once, with flexible layout options:
+
+```julia
+y = rand(100,3)
+subplot(y; n = 3)             # create an automatic grid, and let it figure out the shape
+subplot(y; n = 3, nr = 1)     # create an automatic grid, but fix the number of rows
+subplot(y; n = 3, nc = 1)     # create an automatic grid, but fix the number of columns
+subplot(y; layout = [1, 2])   # explicit layout.  Lists the number of plots in each row
 ```
 
+__Tip__: You can call `subplot!(args...; kw...)` to add to an existing subplot.
+
+__Tip__: Calling `subplot!` on a `Plot` object, or `plot!` on a `Subplot` object will throw an error.
+
 Shorthands:
 
-```
-  scatter(args...; kw...)    = plot(args...; kw...,  linetype = :none, marker = :hexagon)
-  scatter!(args...; kw...)   = plot!(args...; kw..., linetype = :none, marker = :hexagon)
-  bar(args...; kw...)        = plot(args...; kw...,  linetype = :bar)
-  bar!(args...; kw...)       = plot!(args...; kw..., linetype = :bar)
-  histogram(args...; kw...)  = plot(args...; kw...,  linetype = :hist)
-  histogram!(args...; kw...) = plot!(args...; kw..., linetype = :hist)
-  heatmap(args...; kw...)    = plot(args...; kw...,  linetype = :heatmap)
-  heatmap!(args...; kw...)   = plot!(args...; kw..., linetype = :heatmap)
+```julia
+scatter(args...; kw...)    = plot(args...; kw...,  linetype = :scatter)
+scatter!(args...; kw...)   = plot!(args...; kw..., linetype = :scatter)
+bar(args...; kw...)        = plot(args...; kw...,  linetype = :bar)
+bar!(args...; kw...)       = plot!(args...; kw..., linetype = :bar)
+histogram(args...; kw...)  = plot(args...; kw...,  linetype = :hist)
+histogram!(args...; kw...) = plot!(args...; kw..., linetype = :hist)
+heatmap(args...; kw...)    = plot(args...; kw...,  linetype = :heatmap)
+heatmap!(args...; kw...)   = plot!(args...; kw..., linetype = :heatmap)
+sticks(args...; kw...)     = plot(args...; kw...,  linetype = :sticks, marker = :ellipse)
+sticks!(args...; kw...)    = plot!(args...; kw..., linetype = :sticks, marker = :ellipse)
+hline(args...; kw...)      = plot(args...; kw...,  linetype = :hline)
+hline!(args...; kw...)     = plot!(args...; kw..., linetype = :hline)
+vline(args...; kw...)      = plot(args...; kw...,  linetype = :vline)
+vline!(args...; kw...)     = plot!(args...; kw..., linetype = :vline)
+ohlc(args...; kw...)       = plot(args...; kw...,  linetype = :ohlc)
+ohlc!(args...; kw...)      = plot!(args...; kw..., linetype = :ohlc)
+
+title!(s::AbstractString)                 = plot!(title = s)
+xlabel!(s::AbstractString)                = plot!(xlabel = s)
+ylabel!(s::AbstractString)                = plot!(ylabel = s)
+xlims!{T<:Real,S<:Real}(lims::Tuple{T,S}) = plot!(xlims = lims)
+ylims!{T<:Real,S<:Real}(lims::Tuple{T,S}) = plot!(ylims = lims)
+xticks!{T<:Real}(v::AVec{T})              = plot!(xticks = v)
+yticks!{T<:Real}(v::AVec{T})              = plot!(yticks = v)
+xflip!(flip::Bool = true)                 = plot!(xflip = flip)
+yflip!(flip::Bool = true)                 = plot!(yflip = flip)
+xaxis!(args...)                           = plot!(xaxis = args)
+yaxis!(args...)                           = plot!(yaxis = args)
+annotate!(anns)                           = plot!(annotation = anns)
 ```
 
 Some keyword arguments you can set:
 
-```
-  axis            # :left or :right
-  color           # can be a string ("red") or a symbol (:red) or a ColorsTypes.jl Colorant (RGB(1,0,0)) or :auto (which lets the package pick)
-  label           # string or symbol, applies to that line, may go in a legend
-  width           # width of a line
-  linetype        # :line, :step, :stepinverted, :sticks, :dots, :none, :heatmap, :hexbin, :hist, :bar
-  linestyle       # :solid, :dash, :dot, :dashdot, :dashdotdot
-  marker          # :none, :ellipse, :rect, :diamond, :utriangle, :dtriangle, :cross, :xcross, :star1, :star2, :hexagon
-  markercolor     # same choices as `color`, or :match will set the color to be the same as `color`
-  markersize      # size of the marker
-  nbins           # number of bins for heatmap/hexbin and histograms
-  heatmap_c       # color cutoffs for Qwt heatmaps
-  fillto          # fillto value for area plots
-  title           # string or symbol, title of the plot
-  xlabel          # string or symbol, label on the bottom (x) axis
-  ylabel          # string or symbol, label on the left (y) axis
-  yrightlabel     # string or symbol, label on the right (y) axis
-  reg             # true or false, add a regression line for each line
-  size            # (Int,Int), resize the enclosing window
-  pos             # (Int,Int), move the enclosing window to this position
-  windowtitle     # string or symbol, set the title of the enclosing windowtitle
-  screen          # Integer, move enclosing window to this screen number (for multiscreen desktops)
-  show            # true or false, show the plot (in case you don't want the window to pop up right away)
-```
+Keyword | Default | Type | Aliases 
+---- | ---- | ---- | ----
+`:annotation` | `nothing` | Series | `:ann`, `:annotate`, `:annotations`, `:anns`  
+`:axis` | `left` | Series | `:axiss`  
+`:background_color` | `RGB{U8}(1.0,1.0,1.0)` | Plot | `:background`, `:bg`, `:bg_color`, `:bgcolor`  
+`:color` | `auto` | Series | `:c`, `:colors`  
+`:color_palette` | `auto` | Plot | `:palette`  
+`:fill` | `nothing` | Series | `:area`, `:f`  
+`:fillcolor` | `match` | Series | `:fc`, `:fcolor`, `:fillcolors`  
+`:fillrange` | `nothing` | Series | `:fillranges`, `:fillrng`  
+`:foreground_color` | `auto` | Plot | `:fg`, `:fg_color`, `:fgcolor`, `:foreground`  
+`:group` | `nothing` | Series | `:g`, `:groups`  
+`:heatmap_c` | `(0.15,0.5)` | Series | `:heatmap_cs`  
+`:label` | `AUTO` | Series | `:lab`, `:labels`  
+`:layout` | `nothing` | Plot |   
+`:legend` | `true` | Plot | `:leg`  
+`:line` | `nothing` | Series | `:l`  
+`:linestyle` | `solid` | Series | `:linestyles`, `:ls`, `:s`, `:style`  
+`:linetype` | `path` | Series | `:linetypes`, `:lt`, `:t`, `:type`  
+`:linewidth` | `1` | Series | `:linewidths`, `:lw`, `:w`, `:width`  
+`:marker` | `nothing` | Series | `:m`, `:mark`  
+`:markercolor` | `match` | Series | `:markercolors`, `:mc`, `:mcolor`  
+`:markershape` | `none` | Series | `:markershapes`, `:shape`  
+`:markersize` | `6` | Series | `:markersizes`, `:ms`, `:msize`  
+`:n` | `-1` | Plot |   
+`:nbins` | `100` | Series | `:nb`, `:nbin`, `:nbinss`  
+`:nc` | `-1` | Plot |   
+`:nr` | `-1` | Plot |   
+`:pos` | `(0,0)` | Plot |   
+`:reg` | `false` | Series | `:regression`, `:regs`  
+`:show` | `false` | Plot | `:display`, `:gui`  
+`:size` | `(600,400)` | Plot | `:windowsize`, `:wsize`  
+`:title` | `` | Plot |   
+`:windowtitle` | `Plots.jl` | Plot | `:wtitle`  
+`:xaxis` | `nothing` | Plot |   
+`:xflip` | `false` | Plot |   
+`:xlabel` | `` | Plot | `:xlab`  
+`:xlims` | `auto` | Plot | `:xlim`, `:xlimit`, `:xlimits`  
+`:xscale` | `identity` | Plot |   
+`:xticks` | `auto` | Plot | `:xtick`  
+`:yaxis` | `nothing` | Plot |   
+`:yflip` | `true` | Plot |   
+`:ylabel` | `` | Plot | `:ylab`  
+`:ylims` | `auto` | Plot | `:ylim`, `:ylimit`, `:ylimits`  
+`:yrightlabel` | `` | Plot | `:y2lab`, `:y2label`, `:ylab2`, `:ylabel2`, `:ylabelright`, `:ylabr`, `:yrlab`  
+`:yscale` | `identity` | Plot |   
+`:yticks` | `auto` | Plot | `:ytick`  
+`:z` | `nothing` | Series | `:zs`  
 
-If you don't include a keyword argument, these are the defaults:
-  
-```
-  axis = :left
-  color = :auto
-  label = automatically generated (y1, y2, ...., or y1 (R), y2 (R) for the right axis)
-  width = 1
-  linetype = :line
-  linestype = :solid
-  marker = :none
-  markercolor = :match
-  markersize = 3
-  nbins = 100
-  heatmap_c = (0.15, 0.5)
-  fillto = nothing
-  title = ""
-  xlabel = ""
-  ylabel = ""
-  yrightlabel = ""
-  reg = false
-  size = (800,600)
-  pos = (0,0)
-  windowtitle = ""
-  screen = 1
-  show = true
-```
 
-When plotting multiple lines, you can give every line the same trait by using the singular, or add an "s" to pluralize.
-  (yes I know it's not gramatically correct, but it's easy to use and implement)
+Plot types:
+
+Type | Desc | Aliases
+---- | ---- | ----
+`:none` | No line | `:n`, `:no`  
+`:line` | Lines with sorted x-axis | `:l`  
+`:path` | Lines | `:p`  
+`:steppre` | Step plot (vertical then horizontal) | `:stepinv`, `:stepinverted`, `:stepsinv`, `:stepsinverted`  
+`:steppost` | Step plot (horizontal then vertical) | `:stair`, `:stairs`, `:step`, `:steps`  
+`:sticks` | Vertical lines | `:stem`, `:stems`  
+`:scatter` | Points, no lines | `:dots`  
+`:heatmap` | Colored regions by density |   
+`:hexbin` | Similar to heatmap |   
+`:hist` | Histogram (doesn't use x) | `:histogram`  
+`:bar` | Bar plot (centered on x values) |   
+`:hline` | Horizontal line (doesn't use x) |   
+`:vline` | Vertical line (doesn't use x) |   
+`:ohlc` | Open/High/Low/Close chart (expects y is AbstractVector{Plots.OHLC}) |   
+
+
+Line styles:
+
+Type | Aliases
+---- | ----
+`:auto` | `:a`  
+`:solid` | `:s`  
+`:dash` | `:d`  
+`:dot` |   
+`:dashdot` | `:dd`  
+`:dashdotdot` | `:ddd`  
+
+
+Markers:
+
+Type | Aliases
+---- | ----
+`:none` | `:n`, `:no`  
+`:auto` | `:a`  
+`:ellipse` | `:c`, `:circle`  
+`:rect` | `:r`, `:sq`, `:square`  
+`:diamond` | `:d`  
+`:utriangle` | `:^`, `:uptri`, `:uptriangle`, `:ut`, `:utri`  
+`:dtriangle` | `:V`, `:downtri`, `:downtriangle`, `:dt`, `:dtri`, `:v`  
+`:cross` | `:+`, `:plus`  
+`:xcross` | `:X`, `:x`  
+`:star1` | `:s`, `:star`  
+`:star2` | `:s2`  
+`:hexagon` | `:h`, `:hex`  
+`:octagon` | `:o`, `:oct`  
+
+
+
+__Tip__: You can see the default value for a given argument with `default(arg::Symbol)`, and set the default value with `default(arg::Symbol, value)` or `default(; kw...)`.  For example set the default window size and whether we should show a legend with `default(size=(600,400), leg=false)`.
+
+__Tip__: There are some helper arguments you can set:  `xaxis`, `yaxis`, `line`, `marker`, `fill`.  These go through special preprocessing to extract values into individual arguments.  The order doesn't matter, and if you pass a single value it's equivalent to wrapping it in a Tuple.  Examples:
 
 ```
-  plot(rand(100,2); colors = [:red, RGB(.5,.5,0)], axiss = [:left, :right], width = 5)  # note the width=5 is applied to both lines
+plot(y, xaxis = ("mylabel", :log, :flip, (-1,1)))   # this sets the `xlabel`, `xscale`, `xflip`, and `xlims` arguments automatically
+plot(y, line = (:bar, :blue, :dot, 10))             # this sets the `linetype`, `color`, `linestyle`, and `linewidth` arguments automatically
+plot(y, marker = (:rect, :red, 10))                 # this sets the `markershape`, `markercolor`, and `markersize` arguments automatically
+plot(y, fill = (:green, 10))                        # this sets the `fillcolor` and `fillrange` arguments automatically
+                                                    # Note: `fillrange` can be:
+                                                              a number (fill to horizontal line)
+                                                              a vector of numbers (different for each data point)
+                                                              a tuple of vectors (fill a band)
 ```
 
-# TODO
+__Tip__: When plotting multiple lines, you can set all series to use the same value, or pass in a matrix to cycle through values.  Example:
+
+```julia
+plot(rand(100,4); color = [:red RGB(0,0,1)],     # (Matrix) lines 1 and 3 are red, lines 2 and 4 are blue
+                  axis = :auto,                  # lines 1 and 3 are on the left axis, lines 2 and 4 are on the right
+                  markershape = [:rect, :star1]  # (Vector) ALL lines are passed the vector [:rect, :star1]
+                  width = 5)                     # all lines have a width of 5
+```
+
+__Tip__: Not all features are supported for each backend, but you can see what's supported by calling the functions: `supportedArgs()`, `supportedAxes()`, `supportedTypes()`, `supportedStyles()`, `supportedMarkers()`, `subplotSupported()`
+
+__Tip__: Call `gui()` to display the plot in a window.  Interactivity depends on backend.  Plotting at the REPL (without semicolon) implicitly calls `gui()`.
+
+## TODO features:
 
 - [x] Plot vectors/matrices/functions
-- [ ] Plot DataFrames
-- [ ] Subplots
-- [ ] Histograms
+- [x] Plot DataFrames
+- [x] Grouping
+- [x] Annotations
+- [x] Scales
+- [x] Categorical Inputs (strings, etc... for hist, bar? or can split one series into multiple?)
+- [ ] Custom markers
+- [ ] Special plots (boxplot, ohlc?)
+- [x] Subplots
+- [x] Histograms
 - [ ] 3D plotting
 - [ ] Scenes/Drawing
 - [ ] Graphs
 - [ ] Interactivity (GUIs)
+
+## TODO backends:
+
 - [x] Gadfly.jl
-- [ ] PyPlot.jl
-- [ ] Winston.jl
-- [ ] Gaston.jl
-- [ ] GLPlot.jl
+- [x] Immerse.jl
+- [x] PyPlot.jl
+- [x] UnicodePlots.jl
 - [x] Qwt.jl
+- [x] Winston.jl
+- [ ] GLPlot.jl
 - [ ] Bokeh.jl
+- [ ] Vega.jl
+- [ ] Gaston.jl
 - [ ] Plotly.jl
 - [ ] GoogleCharts.jl
-- [ ] Vega.jl
 - [ ] PLplot.jl
 - [ ] TextPlots.jl
 - [ ] ASCIIPlots.jl
 - [ ] Sparklines.jl
-- [ ] UnicodePlots.jl
 - [ ] Hinton.jl
 - [ ] ImageTerm.jl
 - [ ] GraphViz.jl
 - [ ] TikzGraphs.jl
 - [ ] GraphLayout.jl
 
-# Backends
+## More information on backends (both supported and unsupported)
 
 See the wiki at: https://github.com/JuliaPlot/juliaplot_docs/wiki
 
-# Author
-
-Thomas Breloff (@tbreloff)
 

REQUIRE

@@ -1,4 +1,5 @@
-julia 0.4-
+julia 0.3
 
 Colors
-FactCheck
+Reexport
+Compat

docs/example_generation.jl

@@ -3,100 +3,160 @@ module PlotExamples
 
 using Plots
 using Colors
+using Compat
 
 const DOCDIR = Pkg.dir("Plots") * "/docs"
 const IMGDIR = Pkg.dir("Plots") * "/img"
 
-doc"""
+"""
 Holds all data needed for a documentation example... header, description, and plotting expression (Expr)
 """
 type PlotExample
-  header::String
-  desc::String
+  header::@compat(AbstractString)
+  desc::@compat(AbstractString)
   exprs::Vector{Expr}
 end
 
 
+function fakedata(sz...)
+  y = zeros(sz...)
+  for r in 2:size(y,1)
+    y[r,:] = 0.9 * y[r-1,:] + randn(size(y,2))'
+  end
+  y
+end
+
+
 # the examples we'll run for each
 const examples = PlotExample[
   PlotExample("Lines",
-              "A simple line plot of the 3 columns.",
-              [:(plot(rand(100,3)))]),
+              "A simple line plot of the columns.",
+              [:(plot(fakedata(50,5), w=3))]),
   PlotExample("Functions",
-              "Plot multiple functions",
+              "Plot multiple functions.  You can also put the function first, or use the form `plot(f, xmin, xmax)` where f is a Function or AbstractVector{Function}.",
               [:(plot(0:0.01:4π, [sin,cos]))]),
+  PlotExample("",
+              "Or make a parametric plot (i.e. plot: (fx(u), fy(u))) with plot(fx, fy, umin, umax).",
+              [:(plot(sin, x->sin(2x), 0, 2π, line=4, leg=false, fill=(0,:orange)))]),
+  PlotExample("Colors",
+              "Access predefined palettes (or build your own with the `colorscheme` method).  Line/marker colors are auto-generated from the plot's palette, unless overridden.  Set the `z` argument to turn on series gradients.",
+              [:(y = rand(100)), :(plot(0:10:100,rand(11,4),lab="lines",w=3, palette=:grays, fill=(0.5,:auto))), :(scatter!(y, z=abs(y-.5), m=(10,:heat), lab="grad"))]),
   PlotExample("Global",
-              "Change the guides/background without a separate call.",
-              [:(plot(rand(10); title="TITLE", xlabel="XLABEL", ylabel="YLABEL", background_color = RGB(0.5,0.5,0.5)))]),
+              "Change the guides/background/limits/ticks.  Convenience args `xaxis` and `yaxis` allow you to pass a tuple or value which will be mapped to the relevant args automatically.  The `xaxis` below will be replaced with `xlabel` and `xlims` args automatically during the preprocessing step. You can also use shorthand functions: `title!`, `xaxis!`, `yaxis!`, `xlabel!`, `ylabel!`, `xlims!`, `ylims!`, `xticks!`, `yticks!`",
+              [:(plot(rand(20,3), title="TITLE", xaxis=("XLABEL",(-5,30),0:2:20,:flip), yaxis=("YLABEL",:log10), background_color = RGB(0.2,0.2,0.2), leg=false))]),
   PlotExample("Two-axis",
-              "Use the `axis` or `axiss` arguments.\n\nNote: This is only supported with Qwt right now",
-              [:(plot(Vector[randn(100), randn(100)*100]; axiss = [:left,:right]))]),
-  PlotExample("Vectors w/ pluralized args",
-              "Plot multiple series with different numbers of points.  Mix arguments that apply to all series (singular... see `marker`) with arguments unique to each series (pluralized... see `colors`).",
-              [:(plot(Vector[rand(10), rand(20)]; marker=:ellipse, markersize=8, colors=[:red,:blue]))]),
+              "Use the `axis` arguments.\n\nNote: Currently only supported with Qwt and PyPlot",
+              [:(plot(Vector[randn(100), randn(100)*100]; axis = [:l :r], ylabel="LEFT", yrightlabel="RIGHT"))]),
+  PlotExample("Arguments",
+              "Plot multiple series with different numbers of points.  Mix arguments that apply to all series (marker/markersize) with arguments unique to each series (colors).  Special arguments `line`, `marker`, and `fill` will automatically figure out what arguments to set (for example, we are setting the `linestyle`, `linewidth`, and `color` arguments with `line`.)  Note that we pass a matrix of colors, and this applies the colors to each series.",
+              [:(plot(Vector[rand(10), rand(20)]; marker=(:ellipse,8), line=(:dot,3,[:black :orange])))]),
   PlotExample("Build plot in pieces",
               "Start with a base plot...",
-              [:(plot(rand(100)/3; reg=true, fillto=0))]),
+              [:(plot(rand(100)/3, reg=true, fill=(0,:green)))]),
   PlotExample("",
               "and add to it later.",
-              [:(scatter!(rand(100); markersize=6, color=:blue))]),
+              [:(scatter!(rand(100), markersize=6, c=:orange))]),
   PlotExample("Heatmaps",
               "",
-              [:(heatmap(randn(10000),randn(10000); nbins=200))]),
-  PlotExample("Lots of line types",
-              "Options: (:line, :step, :stepinverted, :sticks, :dots, :none, :heatmap, :hexbin, :hist, :bar)  \nNote: some may not work with all backends",
-              [:(plot(rand(20,4); linetypes=[:line, :step, :sticks, :dots]))]),
+              [:(heatmap(randn(10000),randn(10000), nbins=100))]),
+  PlotExample("Line types",
+              "",
+              [:(types = intersect(supportedTypes(), [:line, :path, :steppre, :steppost, :sticks, :scatter])'),
+                  :(n = length(types)),
+                  :(x = Vector[sort(rand(20)) for i in 1:n]),
+                  :(y = rand(20,n)),
+                  :(plot(x, y, line=(types,3), lab=map(string,types), ms=15))]),
+  PlotExample("Line styles",
+              "",
+              [:(styles = setdiff(supportedStyles(), [:auto])'), :(plot(cumsum(randn(20,length(styles)),1); style=:auto, label=map(string,styles), w=5))]),
+  PlotExample("Marker types",
+              "",
+              [:(markers = setdiff(supportedMarkers(), [:none,:auto])'), :(scatter(0.5:9.5, [fill(i-0.5,10) for i=length(markers):-1:1]; marker=:auto, label=map(string,markers), ms=12))]),
   PlotExample("Bar",
               "x is the midpoint of the bar. (todo: allow passing of edges instead of midpoints)",
-              [:(bar(randn(1000)))]),
+              [:(bar(randn(999)))]),
   PlotExample("Histogram",
-              "note: fillto isn't supported on all backends",
-              [:(histogram(randn(1000); nbins=50, fillto=20))]),
+              "",
+              [:(histogram(randn(1000), nbins=50))]),
   PlotExample("Subplots",
               """
                 subplot and subplot! are distinct commands which create many plots and add series to them in a circular fashion.
                 You can define the layout with keyword params... either set the number of plots `n` (and optionally number of rows `nr` or 
-                number of columns `nc`), or you can set the layout directly with `layout`.  
-
-                Note: Gadfly is not very friendly here, and although you can create a plot and save a PNG, I haven't been able to actually display it.
+                number of columns `nc`), or you can set the layout directly with `layout`.
               """,
-              [:(subplot(randn(100,5); layout=[1,1,3], linetypes=[:line,:hist,:dots,:step,:bar], nbins=10, legend=false))]),
+              [:(subplot(randn(100,5), layout=[1,1,3], t=[:line :hist :scatter :step :bar], nbins=10, leg=false))]),
   PlotExample("Adding to subplots",
               "Note here the automatic grid layout, as well as the order in which new series are added to the plots.",
-              [:(subplot(randn(100,5); n=4))]),
+              [:(subplot(fakedata(100,10), n=4, palette=[:grays :blues :heat :lightrainbow], bg=[:orange :pink :darkblue :black]))]),
   PlotExample("",
               "",
-              [:(subplot!(randn(100,3)))]),
-
+              [:(subplot!(fakedata(100,10)))]),
+  PlotExample("Open/High/Low/Close",
+              "Create an OHLC chart.  Pass in a vector of OHLC objects as your `y` argument.  Adjust the tick width with arg `markersize`.",
+              [:(n=20), :(hgt=rand(n)+1), :(bot=randn(n)), :(openpct=rand(n)), :(closepct=rand(n)), :(y = [OHLC(openpct[i]*hgt[i]+bot[i], bot[i]+hgt[i], bot[i], closepct[i]*hgt[i]+bot[i]) for i in 1:n]), :(ohlc(y; markersize=8))]),
+  PlotExample("Annotations",
+              "Currently only text annotations are supported.  Pass in a tuple or vector-of-tuples: (x,y,text).  `annotate!(ann)` is shorthand for `plot!(; annotation=ann)`",
+              [
+                :(y = rand(10)),
+                :(plot(y, ann=(3,y[3],"this is #3"))),
+                :(annotate!([(5,y[5],"this is #5"),(9,y[10],"this is #10")]))
+              ]),
   
 ]
 
 
+function createStringOfMarkDownCodeValues(arr, prefix = "")
+  string("`", prefix, join(arr, "`, `$prefix"), "`")
+end
+createStringOfMarkDownSymbols(arr) = isempty(arr) ? "" : createStringOfMarkDownCodeValues(arr, ":")
+
+
 function generate_markdown(pkgname::Symbol)
 
-  # set up the plotter, and don't show the plots by default
-  plotter!(pkgname)
-  plotDefault!(:show, false)
+  # set up the backend, and don't show the plots by default
+  pkg = backend(pkgname)
+  # default(:show, false)
+
+  # mkdir if necessary
+  try
+    mkdir("$IMGDIR/$pkgname")
+  end
 
   # open the markdown file
   md = open("$DOCDIR/$(pkgname)_examples.md", "w")
 
+  write(md, "# Examples for backend: $pkgname\n\n")
+  write(md, "- Supported arguments: $(createStringOfMarkDownCodeValues(supportedArgs(pkg)))\n")
+  write(md, "- Supported values for axis: $(createStringOfMarkDownSymbols(supportedAxes(pkg)))\n")
+  write(md, "- Supported values for linetype: $(createStringOfMarkDownSymbols(supportedTypes(pkg)))\n")
+  write(md, "- Supported values for linestyle: $(createStringOfMarkDownSymbols(supportedStyles(pkg)))\n")
+  write(md, "- Supported values for marker: $(createStringOfMarkDownSymbols(supportedMarkers(pkg)))\n")
+  write(md, "- Is `subplot`/`subplot!` supported? $(subplotSupported(pkg) ? "Yes" : "No")\n\n")
+
+  write(md, "### Initialize\n\n```julia\nusing Plots\n$(pkgname)()\n```\n\n")
+
+
   for (i,example) in enumerate(examples)
 
     try
 
+      # we want to always produce consistent results
+      srand(1234)
+
       # run the code
       map(eval, example.exprs)
 
       # save the png
       imgname = "$(pkgname)_example_$i.png"
-      savepng("$IMGDIR/$imgname")
+
+      # NOTE: uncomment this to overwrite the images as well
+      png("$IMGDIR/$pkgname/$imgname")
 
       # write out the header, description, code block, and image link
       write(md, "### $(example.header)\n\n")
       write(md, "$(example.desc)\n\n")
       write(md, "```julia\n$(join(map(string, example.exprs), "\n"))\n```\n\n")
-      write(md, "![](../img/$imgname)\n\n")
+      write(md, "![](../img/$pkgname/$imgname)\n\n")
 
     catch ex
       # TODO: put error info into markdown?
@@ -110,8 +170,142 @@ function generate_markdown(pkgname::Symbol)
 
 end
 
+
+# make and display one plot
+function test_examples(pkgname::Symbol, idx::Int; debug = true)
+  Plots._debugMode.on = debug
+  println("Testing plot: $pkgname:$idx:$(examples[idx].header)")
+  backend(pkgname)
+  backend()
+  map(eval, examples[idx].exprs)
+  plt = current()
+  gui(plt)
+  plt
+end
+
+# generate all plots and create a dict mapping idx --> plt
+function test_examples(pkgname::Symbol; debug = false)
+  Plots._debugMode.on = debug
+  plts = Dict()
+  for i in 1:length(examples)
+    # if examples[i].header == "Subplots" && !subplotSupported()
+    #   break
+    # end
+
+    try
+      plt = test_examples(pkgname, i, debug=debug)
+      plts[i] = plt
+    catch ex
+      # TODO: put error info into markdown?
+      warn("Example $pkgname:$i:$(examples[i].header) failed with: $ex")
+    end
+  end
+  plts
+end
+
+# axis            # :left or :right
+# color           # can be a string ("red") or a symbol (:red) or a ColorsTypes.jl 
+#                 #   Colorant (RGB(1,0,0)) or :auto (which lets the package pick)
+# label           # string or symbol, applies to that line, may go in a legend
+# width           # width of a line
+# linetype        # :line, :step, :stepinverted, :sticks, :scatter, :none, :heatmap, :hexbin, :hist, :bar
+# linestyle       # :solid, :dash, :dot, :dashdot, :dashdotdot
+# marker          # :none, :ellipse, :rect, :diamond, :utriangle, :dtriangle,
+#                 #   :cross, :xcross, :star1, :star2, :hexagon
+# markercolor     # same choices as `color`, or :match will set the color to be the same as `color`
+# markersize      # size of the marker
+# nbins           # number of bins for heatmap/hexbin and histograms
+# heatmap_c       # color cutoffs for Qwt heatmaps
+# fill          # fill value for area plots
+# title           # string or symbol, title of the plot
+# xlabel          # string or symbol, label on the bottom (x) axis
+# ylabel          # string or symbol, label on the left (y) axis
+# yrightlabel     # string or symbol, label on the right (y) axis
+# reg             # true or false, add a regression line for each line
+# size            # (Int,Int), resize the enclosing window
+# pos             # (Int,Int), move the enclosing window to this position
+# windowtitle     # string or symbol, set the title of the enclosing windowtitle
+# screen          # Integer, move enclosing window to this screen number (for multiscreen desktops)
+
+
+
+@compat const _ltdesc = Dict(
+    :none => "No line",
+    :line => "Lines with sorted x-axis",
+    :path => "Lines",
+    :steppre => "Step plot (vertical then horizontal)",
+    :steppost => "Step plot (horizontal then vertical)",
+    :sticks => "Vertical lines",
+    :scatter => "Points, no lines",
+    :heatmap => "Colored regions by density",
+    :hexbin => "Similar to heatmap",
+    :hist => "Histogram (doesn't use x)",
+    :bar => "Bar plot (centered on x values)",
+    :hline => "Horizontal line (doesn't use x)",
+    :vline => "Vertical line (doesn't use x)",
+    :ohlc => "Open/High/Low/Close chart (expects y is AbstractVector{Plots.OHLC})",
+  )
+
+function buildReadme()
+  readme = readall("$DOCDIR/readme_template.md")
+
+  # build keyword arg table
+  table = "Keyword | Default | Type | Aliases \n---- | ---- | ---- | ----\n"
+  allseries = merge(Plots._seriesDefaults, @compat(Dict(:line=>nothing, :marker=>nothing, :fill=>nothing)))
+  allplots = merge(Plots._plotDefaults, @compat(Dict(:xaxis=>nothing, :yaxis=>nothing)))
+  alldefs = merge(allseries, allplots)
+  for k in Plots.sortedkeys(alldefs)
+  # for d in (Plots._seriesDefaults, Plots._plotDefaults)
+  #   for k in Plots.sortedkeys(d)
+    aliasstr = createStringOfMarkDownSymbols(aliases(Plots._keyAliases, k))
+    table = string(table, "`:$k` | `$(alldefs[k])` | $(haskey(allseries,k) ? "Series" : "Plot") | $aliasstr  \n")
+    # end
+  end
+  readme = replace(readme, "[[KEYWORD_ARGS_TABLE]]", table)
+
+  # build linetypes table
+  table = "Type | Desc | Aliases\n---- | ---- | ----\n"
+  for lt in Plots._allTypes
+    aliasstr = createStringOfMarkDownSymbols(aliases(Plots._typeAliases, lt))
+    table = string(table, "`:$lt` | $(_ltdesc[lt]) | $aliasstr  \n")
+  end
+  readme = replace(readme, "[[LINETYPES_TABLE]]", table)
+
+  # build linestyles table
+  table = "Type | Aliases\n---- | ----\n"
+  for s in Plots._allStyles
+    aliasstr = createStringOfMarkDownSymbols(aliases(Plots._styleAliases, s))
+    table = string(table, "`:$s` | $aliasstr  \n")
+  end
+  readme = replace(readme, "[[LINESTYLES_TABLE]]", table)
+
+  # build markers table
+  table = "Type | Aliases\n---- | ----\n"
+  for s in Plots._allMarkers
+    aliasstr = createStringOfMarkDownSymbols(aliases(Plots._markerAliases, s))
+    table = string(table, "`:$s` | $aliasstr  \n")
+  end
+  readme = replace(readme, "[[MARKERS_TABLE]]", table)
+
+  readme_fn = Pkg.dir("Plots") * "/README.md"
+  f = open(readme_fn, "w")
+  write(f, readme)
+  close(f)
+
+  gadfly()
+  Plots.dumpSupportGraphs()
+end
+
+default(size=(600,400))
+
 # run it!
-map(generate_markdown, (:qwt, :gadfly))
+# note: generate separately so it's easy to comment out
+# @osx_only generate_markdown(:unicodeplots)
+# generate_markdown(:qwt)
+# generate_markdown(:gadfly)
+# generate_markdown(:pyplot)
+# generate_markdown(:immerse)
+# generate_markdown(:winston)
 
 
 end # module

docs/gadfly_examples.md

@@ -1,148 +1,239 @@
-### Lines
+# Examples for backend: gadfly
 
-A simple line plot of the 3 columns.
+- Supported arguments: `annotation`, `background_color`, `color`, `color_palette`, `fillrange`, `fillcolor`, `group`, `label`, `layout`, `legend`, `linestyle`, `linetype`, `linewidth`, `markershape`, `markercolor`, `markersize`, `n`, `nbins`, `nc`, `nr`, `reg`, `show`, `size`, `title`, `windowtitle`, `x`, `xlabel`, `xlims`, `xticks`, `y`, `ylabel`, `ylims`, `yticks`, `xscale`, `yscale`, `xflip`, `yflip`, `z`
+- Supported values for axis: `:auto`, `:left`
+- Supported values for linetype: `:none`, `:line`, `:path`, `:steppost`, `:sticks`, `:scatter`, `:heatmap`, `:hexbin`, `:hist`, `:bar`, `:hline`, `:vline`, `:ohlc`
+- Supported values for linestyle: `:auto`, `:solid`, `:dash`, `:dot`, `:dashdot`, `:dashdotdot`
+- Supported values for marker: `:none`, `:auto`, `:rect`, `:ellipse`, `:diamond`, `:utriangle`, `:dtriangle`, `:cross`, `:xcross`, `:star1`, `:star2`, `:hexagon`, `:octagon`
+- Is `subplot`/`subplot!` supported? Yes
+
+### Initialize
 
 ```julia
-plot(rand(100,3))
+using Plots
+gadfly()
 ```
 
-![](../img/gadfly_example_1.png)
+### Lines
+
+A simple line plot of the columns.
+
+```julia
+plot(fakedata(50,5),w=3)
+```
+
+![](../img/gadfly/gadfly_example_1.png)
 
 ### Functions
 
-Plot multiple functions
+Plot multiple functions.  You can also put the function first, or use the form `plot(f, xmin, xmax)` where f is a Function or AbstractVector{Function}.
 
 ```julia
 plot(0:0.01:4π,[sin,cos])
 ```
 
-![](../img/gadfly_example_2.png)
+![](../img/gadfly/gadfly_example_2.png)
+
+### 
+
+Or make a parametric plot (i.e. plot: (fx(u), fy(u))) with plot(fx, fy, umin, umax).
+
+```julia
+plot(sin,(x->begin  # /home/tom/.julia/v0.4/Plots/docs/example_generation.jl, line 40:
+            sin(2x)
+        end),0,2π,line=4,leg=false,fill=(0,:orange))
+```
+
+![](../img/gadfly/gadfly_example_3.png)
+
+### Colors
+
+Access predefined palettes (or build your own with the `colorscheme` method).  Line/marker colors are auto-generated from the plot's palette, unless overridden.  Set the `z` argument to turn on series gradients.
+
+```julia
+y = rand(100)
+plot(0:10:100,rand(11,4),lab="lines",w=3,palette=:grays,fill=(0.5,:auto))
+scatter!(y,z=abs(y - 0.5),m=(10,:heat),lab="grad")
+```
+
+![](../img/gadfly/gadfly_example_4.png)
 
 ### Global
 
-Change the guides/background without a separate call.
+Change the guides/background/limits/ticks.  Convenience args `xaxis` and `yaxis` allow you to pass a tuple or value which will be mapped to the relevant args automatically.  The `xaxis` below will be replaced with `xlabel` and `xlims` args automatically during the preprocessing step. You can also use shorthand functions: `title!`, `xaxis!`, `yaxis!`, `xlabel!`, `ylabel!`, `xlims!`, `ylims!`, `xticks!`, `yticks!`
 
 ```julia
-plot(rand(10); title="TITLE",xlabel="XLABEL",ylabel="YLABEL",background_color=RGB(0.5,0.5,0.5))
+plot(rand(20,3),title="TITLE",xaxis=("XLABEL",(-5,30),0:2:20,:flip),yaxis=("YLABEL",:log10),background_color=RGB(0.2,0.2,0.2),leg=false)
 ```
 
-![](../img/gadfly_example_3.png)
+![](../img/gadfly/gadfly_example_5.png)
 
 ### Two-axis
 
-Use the `axis` or `axiss` arguments.
+Use the `axis` arguments.
 
-Note: This is only supported with Qwt right now
+Note: Currently only supported with Qwt and PyPlot
 
 ```julia
-plot(Vector[randn(100),randn(100) * 100]; axiss=[:left,:right])
+plot(Vector[randn(100),randn(100) * 100]; axis=[:l :r],ylabel="LEFT",yrightlabel="RIGHT")
 ```
 
-![](../img/gadfly_example_4.png)
+![](../img/gadfly/gadfly_example_6.png)
 
-### Vectors w/ pluralized args
+### Arguments
 
-Plot multiple series with different numbers of points.  Mix arguments that apply to all series (singular... see `marker`) with arguments unique to each series (pluralized... see `colors`).
+Plot multiple series with different numbers of points.  Mix arguments that apply to all series (marker/markersize) with arguments unique to each series (colors).  Special arguments `line`, `marker`, and `fill` will automatically figure out what arguments to set (for example, we are setting the `linestyle`, `linewidth`, and `color` arguments with `line`.)  Note that we pass a matrix of colors, and this applies the colors to each series.
 
 ```julia
-plot(Vector[rand(10),rand(20)]; marker=:ellipse,markersize=8,colors=[:red,:blue])
+plot(Vector[rand(10),rand(20)]; marker=(:ellipse,8),line=(:dot,3,[:black :orange]))
 ```
 
-![](../img/gadfly_example_5.png)
+![](../img/gadfly/gadfly_example_7.png)
 
 ### Build plot in pieces
 
 Start with a base plot...
 
 ```julia
-plot(rand(100) / 3; reg=true,fillto=0)
+plot(rand(100) / 3,reg=true,fill=(0,:green))
 ```
 
-![](../img/gadfly_example_6.png)
+![](../img/gadfly/gadfly_example_8.png)
 
 ### 
 
 and add to it later.
 
 ```julia
-scatter!(rand(100); markersize=6,color=:blue)
+scatter!(rand(100),markersize=6,c=:orange)
 ```
 
-![](../img/gadfly_example_7.png)
+![](../img/gadfly/gadfly_example_9.png)
 
 ### Heatmaps
 
 
 
 ```julia
-heatmap(randn(10000),randn(10000); nbins=200)
+heatmap(randn(10000),randn(10000),nbins=100)
 ```
 
-![](../img/gadfly_example_8.png)
+![](../img/gadfly/gadfly_example_10.png)
+
+### Line types
 
-### Lots of line types
 
-Options: (:line, :step, :stepinverted, :sticks, :dots, :none, :heatmap, :hexbin, :hist, :bar)  
-Note: some may not work with all backends
 
 ```julia
-plot(rand(20,4); linetypes=[:line,:step,:sticks,:dots])
+types = intersect(supportedTypes(),[:line,:path,:steppre,:steppost,:sticks,:scatter])'
+n = length(types)
+x = Vector[sort(rand(20)) for i = 1:n]
+y = rand(20,n)
+plot(x,y,line=(types,3),lab=map(string,types),ms=15)
 ```
 
-![](../img/gadfly_example_9.png)
+![](../img/gadfly/gadfly_example_11.png)
+
+### Line styles
+
+
+
+```julia
+styles = setdiff(supportedStyles(),[:auto])'
+plot(cumsum(randn(20,length(styles)),1); style=:auto,label=map(string,styles),w=5)
+```
+
+![](../img/gadfly/gadfly_example_12.png)
+
+### Marker types
+
+
+
+```julia
+markers = setdiff(supportedMarkers(),[:none,:auto])'
+scatter(0.5:9.5,[fill(i - 0.5,10) for i = length(markers):-1:1]; marker=:auto,label=map(string,markers),ms=12)
+```
+
+![](../img/gadfly/gadfly_example_13.png)
 
 ### Bar
 
 x is the midpoint of the bar. (todo: allow passing of edges instead of midpoints)
 
 ```julia
-bar(randn(1000))
+bar(randn(999))
 ```
 
-![](../img/gadfly_example_10.png)
+![](../img/gadfly/gadfly_example_14.png)
 
 ### Histogram
 
-note: fillto isn't supported on all backends
+
 
 ```julia
-histogram(randn(1000); nbins=50,fillto=20)
+histogram(randn(1000),nbins=50)
 ```
 
-![](../img/gadfly_example_11.png)
+![](../img/gadfly/gadfly_example_15.png)
 
 ### Subplots
 
   subplot and subplot! are distinct commands which create many plots and add series to them in a circular fashion.
   You can define the layout with keyword params... either set the number of plots `n` (and optionally number of rows `nr` or 
-  number of columns `nc`), or you can set the layout directly with `layout`.  
-
-  Note: Gadfly is not very friendly here, and although you can create a plot and save a PNG, I haven't been able to actually display it.
+  number of columns `nc`), or you can set the layout directly with `layout`.
 
 
 ```julia
-subplot(randn(100,5); layout=[1,1,3],linetypes=[:line,:hist,:dots,:step,:bar],nbins=10,legend=false)
+subplot(randn(100,5),layout=[1,1,3],t=[:line :hist :scatter :step :bar],nbins=10,leg=false)
 ```
 
-![](../img/gadfly_example_12.png)
+![](../img/gadfly/gadfly_example_16.png)
 
 ### Adding to subplots
 
 Note here the automatic grid layout, as well as the order in which new series are added to the plots.
 
 ```julia
-subplot(randn(100,5); n=4)
+subplot(fakedata(100,10),n=4,palette=[:grays :blues :heat :lightrainbow],bg=[:orange :pink :darkblue :black])
 ```
 
-![](../img/gadfly_example_13.png)
+![](../img/gadfly/gadfly_example_17.png)
 
 ### 
 
 
 
 ```julia
-subplot!(randn(100,3))
+subplot!(fakedata(100,10))
 ```
 
-![](../img/gadfly_example_14.png)
+![](../img/gadfly/gadfly_example_18.png)
+
+### Open/High/Low/Close
+
+Create an OHLC chart.  Pass in a vector of OHLC objects as your `y` argument.  Adjust the tick width with arg `markersize`.
+
+```julia
+n = 20
+hgt = rand(n) + 1
+bot = randn(n)
+openpct = rand(n)
+closepct = rand(n)
+y = [OHLC(openpct[i] * hgt[i] + bot[i],bot[i] + hgt[i],bot[i],closepct[i] * hgt[i] + bot[i]) for i = 1:n]
+ohlc(y; markersize=8)
+```
+
+![](../img/gadfly/gadfly_example_19.png)
+
+### Annotations
+
+Currently only text annotations are supported.  Pass in a tuple or vector-of-tuples: (x,y,text).  `annotate!(ann)` is shorthand for `plot!(; annotation=ann)`
+
+```julia
+y = rand(10)
+plot(y,ann=(3,y[3],"this is #3"))
+annotate!([(5,y[5],"this is #5"),(9,y[10],"this is #10")])
+```
+
+![](../img/gadfly/gadfly_example_20.png)
 

docs/immerse_examples.md

@@ -0,0 +1,239 @@
+# Examples for backend: immerse
+
+- Supported arguments: `annotation`, `background_color`, `color`, `color_palette`, `fillrange`, `fillcolor`, `group`, `label`, `layout`, `legend`, `linestyle`, `linetype`, `linewidth`, `markershape`, `markercolor`, `markersize`, `n`, `nbins`, `nc`, `nr`, `reg`, `show`, `size`, `title`, `windowtitle`, `x`, `xlabel`, `xlims`, `xticks`, `y`, `ylabel`, `ylims`, `yticks`, `xscale`, `yscale`, `xflip`, `yflip`, `z`
+- Supported values for axis: `:auto`, `:left`
+- Supported values for linetype: `:none`, `:line`, `:path`, `:steppost`, `:sticks`, `:scatter`, `:heatmap`, `:hexbin`, `:hist`, `:bar`, `:hline`, `:vline`, `:ohlc`
+- Supported values for linestyle: `:auto`, `:solid`, `:dash`, `:dot`, `:dashdot`, `:dashdotdot`
+- Supported values for marker: `:none`, `:auto`, `:rect`, `:ellipse`, `:diamond`, `:utriangle`, `:dtriangle`, `:cross`, `:xcross`, `:star1`, `:star2`, `:hexagon`, `:octagon`
+- Is `subplot`/`subplot!` supported? Yes
+
+### Initialize
+
+```julia
+using Plots
+immerse()
+```
+
+### Lines
+
+A simple line plot of the columns.
+
+```julia
+plot(fakedata(50,5),w=3)
+```
+
+![](../img/immerse/immerse_example_1.png)
+
+### Functions
+
+Plot multiple functions.  You can also put the function first, or use the form `plot(f, xmin, xmax)` where f is a Function or AbstractVector{Function}.
+
+```julia
+plot(0:0.01:4π,[sin,cos])
+```
+
+![](../img/immerse/immerse_example_2.png)
+
+### 
+
+Or make a parametric plot (i.e. plot: (fx(u), fy(u))) with plot(fx, fy, umin, umax).
+
+```julia
+plot(sin,(x->begin  # /home/tom/.julia/v0.4/Plots/docs/example_generation.jl, line 40:
+            sin(2x)
+        end),0,2π,line=4,leg=false,fill=(0,:orange))
+```
+
+![](../img/immerse/immerse_example_3.png)
+
+### Colors
+
+Access predefined palettes (or build your own with the `colorscheme` method).  Line/marker colors are auto-generated from the plot's palette, unless overridden.  Set the `z` argument to turn on series gradients.
+
+```julia
+y = rand(100)
+plot(0:10:100,rand(11,4),lab="lines",w=3,palette=:grays,fill=(0.5,:auto))
+scatter!(y,z=abs(y - 0.5),m=(10,:heat),lab="grad")
+```
+
+![](../img/immerse/immerse_example_4.png)
+
+### Global
+
+Change the guides/background/limits/ticks.  Convenience args `xaxis` and `yaxis` allow you to pass a tuple or value which will be mapped to the relevant args automatically.  The `xaxis` below will be replaced with `xlabel` and `xlims` args automatically during the preprocessing step. You can also use shorthand functions: `title!`, `xaxis!`, `yaxis!`, `xlabel!`, `ylabel!`, `xlims!`, `ylims!`, `xticks!`, `yticks!`
+
+```julia
+plot(rand(20,3),title="TITLE",xaxis=("XLABEL",(-5,30),0:2:20,:flip),yaxis=("YLABEL",:log10),background_color=RGB(0.2,0.2,0.2),leg=false)
+```
+
+![](../img/immerse/immerse_example_5.png)
+
+### Two-axis
+
+Use the `axis` arguments.
+
+Note: Currently only supported with Qwt and PyPlot
+
+```julia
+plot(Vector[randn(100),randn(100) * 100]; axis=[:l :r],ylabel="LEFT",yrightlabel="RIGHT")
+```
+
+![](../img/immerse/immerse_example_6.png)
+
+### Arguments
+
+Plot multiple series with different numbers of points.  Mix arguments that apply to all series (marker/markersize) with arguments unique to each series (colors).  Special arguments `line`, `marker`, and `fill` will automatically figure out what arguments to set (for example, we are setting the `linestyle`, `linewidth`, and `color` arguments with `line`.)  Note that we pass a matrix of colors, and this applies the colors to each series.
+
+```julia
+plot(Vector[rand(10),rand(20)]; marker=(:ellipse,8),line=(:dot,3,[:black :orange]))
+```
+
+![](../img/immerse/immerse_example_7.png)
+
+### Build plot in pieces
+
+Start with a base plot...
+
+```julia
+plot(rand(100) / 3,reg=true,fill=(0,:green))
+```
+
+![](../img/immerse/immerse_example_8.png)
+
+### 
+
+and add to it later.
+
+```julia
+scatter!(rand(100),markersize=6,c=:orange)
+```
+
+![](../img/immerse/immerse_example_9.png)
+
+### Heatmaps
+
+
+
+```julia
+heatmap(randn(10000),randn(10000),nbins=100)
+```
+
+![](../img/immerse/immerse_example_10.png)
+
+### Line types
+
+
+
+```julia
+types = intersect(supportedTypes(),[:line,:path,:steppre,:steppost,:sticks,:scatter])'
+n = length(types)
+x = Vector[sort(rand(20)) for i = 1:n]
+y = rand(20,n)
+plot(x,y,line=(types,3),lab=map(string,types),ms=15)
+```
+
+![](../img/immerse/immerse_example_11.png)
+
+### Line styles
+
+
+
+```julia
+styles = setdiff(supportedStyles(),[:auto])'
+plot(cumsum(randn(20,length(styles)),1); style=:auto,label=map(string,styles),w=5)
+```
+
+![](../img/immerse/immerse_example_12.png)
+
+### Marker types
+
+
+
+```julia
+markers = setdiff(supportedMarkers(),[:none,:auto])'
+scatter(0.5:9.5,[fill(i - 0.5,10) for i = length(markers):-1:1]; marker=:auto,label=map(string,markers),ms=12)
+```
+
+![](../img/immerse/immerse_example_13.png)
+
+### Bar
+
+x is the midpoint of the bar. (todo: allow passing of edges instead of midpoints)
+
+```julia
+bar(randn(999))
+```
+
+![](../img/immerse/immerse_example_14.png)
+
+### Histogram
+
+
+
+```julia
+histogram(randn(1000),nbins=50)
+```
+
+![](../img/immerse/immerse_example_15.png)
+
+### Subplots
+
+  subplot and subplot! are distinct commands which create many plots and add series to them in a circular fashion.
+  You can define the layout with keyword params... either set the number of plots `n` (and optionally number of rows `nr` or 
+  number of columns `nc`), or you can set the layout directly with `layout`.
+
+
+```julia
+subplot(randn(100,5),layout=[1,1,3],t=[:line :hist :scatter :step :bar],nbins=10,leg=false)
+```
+
+![](../img/immerse/immerse_example_16.png)
+
+### Adding to subplots
+
+Note here the automatic grid layout, as well as the order in which new series are added to the plots.
+
+```julia
+subplot(fakedata(100,10),n=4,palette=[:grays :blues :heat :lightrainbow],bg=[:orange :pink :darkblue :black])
+```
+
+![](../img/immerse/immerse_example_17.png)
+
+### 
+
+
+
+```julia
+subplot!(fakedata(100,10))
+```
+
+![](../img/immerse/immerse_example_18.png)
+
+### Open/High/Low/Close
+
+Create an OHLC chart.  Pass in a vector of OHLC objects as your `y` argument.  Adjust the tick width with arg `markersize`.
+
+```julia
+n = 20
+hgt = rand(n) + 1
+bot = randn(n)
+openpct = rand(n)
+closepct = rand(n)
+y = [OHLC(openpct[i] * hgt[i] + bot[i],bot[i] + hgt[i],bot[i],closepct[i] * hgt[i] + bot[i]) for i = 1:n]
+ohlc(y; markersize=8)
+```
+
+![](../img/immerse/immerse_example_19.png)
+
+### Annotations
+
+Currently only text annotations are supported.  Pass in a tuple or vector-of-tuples: (x,y,text).  `annotate!(ann)` is shorthand for `plot!(; annotation=ann)`
+
+```julia
+y = rand(10)
+plot(y,ann=(3,y[3],"this is #3"))
+annotate!([(5,y[5],"this is #5"),(9,y[10],"this is #10")])
+```
+
+![](../img/immerse/immerse_example_20.png)
+

docs/pyplot_examples.md

@@ -0,0 +1,190 @@
+# Examples for backend: pyplot
+
+- Supported arguments: `annotation`, `axis`, `background_color`, `color`, `color_palette`, `fillrange`, `fillcolor`, `foreground_color`, `group`, `label`, `layout`, `legend`, `linestyle`, `linetype`, `linewidth`, `markershape`, `markercolor`, `markersize`, `n`, `nbins`, `nc`, `nr`, `show`, `size`, `title`, `windowtitle`, `x`, `xlabel`, `xlims`, `xticks`, `y`, `ylabel`, `ylims`, `yrightlabel`, `yticks`, `xscale`, `yscale`, `xflip`, `yflip`, `z`
+- Supported values for axis: `:auto`, `:left`, `:right`
+- Supported values for linetype: `:none`, `:line`, `:path`, `:step`, `:stepinverted`, `:sticks`, `:scatter`, `:heatmap`, `:hexbin`, `:hist`, `:bar`, `:hline`, `:vline`
+- Supported values for linestyle: `:auto`, `:solid`, `:dash`, `:dot`, `:dashdot`
+- Supported values for marker: `:none`, `:auto`, `:rect`, `:ellipse`, `:diamond`, `:utriangle`, `:dtriangle`, `:cross`, `:xcross`, `:star1`, `:hexagon`
+- Is `subplot`/`subplot!` supported? No
+
+### Initialize
+
+```julia
+using Plots
+pyplot()
+```
+
+### Lines
+
+A simple line plot of the columns.
+
+```julia
+plot(fakedata(50,5),w=3)
+```
+
+![](../img/pyplot/pyplot_example_1.png)
+
+### Functions
+
+Plot multiple functions.  You can also put the function first, or use the form `plot(f, xmin, xmax)` where f is a Function or AbstractVector{Function}.
+
+```julia
+plot(0:0.01:4π,[sin,cos])
+```
+
+![](../img/pyplot/pyplot_example_2.png)
+
+### 
+
+Or make a parametric plot (i.e. plot: (fx(u), fy(u))) with plot(fx, fy, umin, umax).
+
+```julia
+plot(sin,(x->begin  # /home/tom/.julia/v0.4/Plots/docs/example_generation.jl, line 40:
+            sin(2x)
+        end),0,2π,line=4,leg=false,fill=(0,:orange))
+```
+
+![](../img/pyplot/pyplot_example_3.png)
+
+### Colors
+
+Access predefined palettes (or build your own with the `colorscheme` method).  Line/marker colors are auto-generated from the plot's palette, unless overridden.  Set the `z` argument to turn on series gradients.
+
+```julia
+y = rand(100)
+plot(0:10:100,rand(11,4),lab="lines",w=3,palette=:grays,fill=(0.5,:auto))
+scatter!(y,z=abs(y - 0.5),m=(10,:heat),lab="grad")
+```
+
+![](../img/pyplot/pyplot_example_4.png)
+
+### Global
+
+Change the guides/background/limits/ticks.  Convenience args `xaxis` and `yaxis` allow you to pass a tuple or value which will be mapped to the relevant args automatically.  The `xaxis` below will be replaced with `xlabel` and `xlims` args automatically during the preprocessing step. You can also use shorthand functions: `title!`, `xaxis!`, `yaxis!`, `xlabel!`, `ylabel!`, `xlims!`, `ylims!`, `xticks!`, `yticks!`
+
+```julia
+plot(rand(20,3),title="TITLE",xaxis=("XLABEL",(-5,30),0:2:20,:flip),yaxis=("YLABEL",:log10),background_color=RGB(0.2,0.2,0.2),leg=false)
+```
+
+![](../img/pyplot/pyplot_example_5.png)
+
+### Two-axis
+
+Use the `axis` arguments.
+
+Note: Currently only supported with Qwt and PyPlot
+
+```julia
+plot(Vector[randn(100),randn(100) * 100]; axis=[:l :r],ylabel="LEFT",yrightlabel="RIGHT")
+```
+
+![](../img/pyplot/pyplot_example_6.png)
+
+### Arguments
+
+Plot multiple series with different numbers of points.  Mix arguments that apply to all series (marker/markersize) with arguments unique to each series (colors).  Special arguments `line`, `marker`, and `fill` will automatically figure out what arguments to set (for example, we are setting the `linestyle`, `linewidth`, and `color` arguments with `line`.)  Note that we pass a matrix of colors, and this applies the colors to each series.
+
+```julia
+plot(Vector[rand(10),rand(20)]; marker=(:ellipse,8),line=(:dot,3,[:black :orange]))
+```
+
+![](../img/pyplot/pyplot_example_7.png)
+
+### Build plot in pieces
+
+Start with a base plot...
+
+```julia
+plot(rand(100) / 3,reg=true,fill=(0,:green))
+```
+
+![](../img/pyplot/pyplot_example_8.png)
+
+### 
+
+and add to it later.
+
+```julia
+scatter!(rand(100),markersize=6,c=:orange)
+```
+
+![](../img/pyplot/pyplot_example_9.png)
+
+### Heatmaps
+
+
+
+```julia
+heatmap(randn(10000),randn(10000),nbins=100)
+```
+
+![](../img/pyplot/pyplot_example_10.png)
+
+### Line types
+
+
+
+```julia
+types = intersect(supportedTypes(),[:line,:path,:steppre,:steppost,:sticks,:scatter])'
+n = length(types)
+x = Vector[sort(rand(20)) for i = 1:n]
+y = rand(20,n)
+plot(x,y,line=(types,3),lab=map(string,types),ms=15)
+```
+
+![](../img/pyplot/pyplot_example_11.png)
+
+### Line styles
+
+
+
+```julia
+styles = setdiff(supportedStyles(),[:auto])'
+plot(cumsum(randn(20,length(styles)),1); style=:auto,label=map(string,styles),w=5)
+```
+
+![](../img/pyplot/pyplot_example_12.png)
+
+### Marker types
+
+
+
+```julia
+markers = setdiff(supportedMarkers(),[:none,:auto])'
+scatter(0.5:9.5,[fill(i - 0.5,10) for i = length(markers):-1:1]; marker=:auto,label=map(string,markers),ms=12)
+```
+
+![](../img/pyplot/pyplot_example_13.png)
+
+### Bar
+
+x is the midpoint of the bar. (todo: allow passing of edges instead of midpoints)
+
+```julia
+bar(randn(999))
+```
+
+![](../img/pyplot/pyplot_example_14.png)
+
+### Histogram
+
+
+
+```julia
+histogram(randn(1000),nbins=50)
+```
+
+![](../img/pyplot/pyplot_example_15.png)
+
+### Annotations
+
+Currently only text annotations are supported.  Pass in a tuple or vector-of-tuples: (x,y,text).  `annotate!(ann)` is shorthand for `plot!(; annotation=ann)`
+
+```julia
+y = rand(10)
+plot(y,ann=(3,y[3],"this is #3"))
+annotate!([(5,y[5],"this is #5"),(9,y[10],"this is #10")])
+```
+
+![](../img/pyplot/pyplot_example_20.png)
+

docs/qwt_examples.md

@@ -1,148 +1,223 @@
-### Lines
+# Examples for backend: qwt
 
-A simple line plot of the 3 columns.
+- Supported arguments: `annotation`, `axis`, `background_color`, `color`, `color_palette`, `fillrange`, `fillcolor`, `foreground_color`, `group`, `heatmap_c`, `label`, `layout`, `legend`, `linestyle`, `linetype`, `linewidth`, `markershape`, `markercolor`, `markersize`, `n`, `nbins`, `nc`, `nr`, `pos`, `reg`, `show`, `size`, `title`, `windowtitle`, `x`, `xlabel`, `xlims`, `xticks`, `y`, `ylabel`, `ylims`, `yrightlabel`, `yticks`, `xscale`, `yscale`
+- Supported values for axis: `:auto`, `:left`, `:right`
+- Supported values for linetype: `:none`, `:line`, `:path`, `:steppre`, `:steppost`, `:sticks`, `:scatter`, `:heatmap`, `:hexbin`, `:hist`, `:bar`, `:hline`, `:vline`
+- Supported values for linestyle: `:auto`, `:solid`, `:dash`, `:dot`, `:dashdot`, `:dashdotdot`
+- Supported values for marker: `:none`, `:auto`, `:rect`, `:ellipse`, `:diamond`, `:utriangle`, `:dtriangle`, `:cross`, `:xcross`, `:star1`, `:star2`, `:hexagon`
+- Is `subplot`/`subplot!` supported? Yes
+
+### Initialize
 
 ```julia
-plot(rand(100,3))
+using Plots
+qwt()
 ```
 
-![](../img/qwt_example_1.png)
+### Lines
+
+A simple line plot of the columns.
+
+```julia
+plot(fakedata(50,5),w=3)
+```
+
+![](../img/qwt/qwt_example_1.png)
 
 ### Functions
 
-Plot multiple functions
+Plot multiple functions.  You can also put the function first, or use the form `plot(f, xmin, xmax)` where f is a Function or AbstractVector{Function}.
 
 ```julia
 plot(0:0.01:4π,[sin,cos])
 ```
 
-![](../img/qwt_example_2.png)
+![](../img/qwt/qwt_example_2.png)
+
+### 
+
+Or make a parametric plot (i.e. plot: (fx(u), fy(u))) with plot(fx, fy, umin, umax).
+
+```julia
+plot(sin,(x->begin  # /home/tom/.julia/v0.4/Plots/docs/example_generation.jl, line 40:
+            sin(2x)
+        end),0,2π,line=4,leg=false,fill=(0,:orange))
+```
+
+![](../img/qwt/qwt_example_3.png)
+
+### Colors
+
+Access predefined palettes (or build your own with the `colorscheme` method).  Line/marker colors are auto-generated from the plot's palette, unless overridden.  Set the `z` argument to turn on series gradients.
+
+```julia
+y = rand(100)
+plot(0:10:100,rand(11,4),lab="lines",w=3,palette=:grays,fill=(0.5,:auto))
+scatter!(y,z=abs(y - 0.5),m=(10,:heat),lab="grad")
+```
+
+![](../img/qwt/qwt_example_4.png)
 
 ### Global
 
-Change the guides/background without a separate call.
+Change the guides/background/limits/ticks.  Convenience args `xaxis` and `yaxis` allow you to pass a tuple or value which will be mapped to the relevant args automatically.  The `xaxis` below will be replaced with `xlabel` and `xlims` args automatically during the preprocessing step. You can also use shorthand functions: `title!`, `xaxis!`, `yaxis!`, `xlabel!`, `ylabel!`, `xlims!`, `ylims!`, `xticks!`, `yticks!`
 
 ```julia
-plot(rand(10); title="TITLE",xlabel="XLABEL",ylabel="YLABEL",background_color=RGB(0.5,0.5,0.5))
+plot(rand(20,3),title="TITLE",xaxis=("XLABEL",(-5,30),0:2:20,:flip),yaxis=("YLABEL",:log10),background_color=RGB(0.2,0.2,0.2),leg=false)
 ```
 
-![](../img/qwt_example_3.png)
+![](../img/qwt/qwt_example_5.png)
 
 ### Two-axis
 
-Use the `axis` or `axiss` arguments.
+Use the `axis` arguments.
 
-Note: This is only supported with Qwt right now
+Note: Currently only supported with Qwt and PyPlot
 
 ```julia
-plot(Vector[randn(100),randn(100) * 100]; axiss=[:left,:right])
+plot(Vector[randn(100),randn(100) * 100]; axis=[:l :r],ylabel="LEFT",yrightlabel="RIGHT")
 ```
 
-![](../img/qwt_example_4.png)
+![](../img/qwt/qwt_example_6.png)
 
-### Vectors w/ pluralized args
+### Arguments
 
-Plot multiple series with different numbers of points.  Mix arguments that apply to all series (singular... see `marker`) with arguments unique to each series (pluralized... see `colors`).
+Plot multiple series with different numbers of points.  Mix arguments that apply to all series (marker/markersize) with arguments unique to each series (colors).  Special arguments `line`, `marker`, and `fill` will automatically figure out what arguments to set (for example, we are setting the `linestyle`, `linewidth`, and `color` arguments with `line`.)  Note that we pass a matrix of colors, and this applies the colors to each series.
 
 ```julia
-plot(Vector[rand(10),rand(20)]; marker=:ellipse,markersize=8,colors=[:red,:blue])
+plot(Vector[rand(10),rand(20)]; marker=(:ellipse,8),line=(:dot,3,[:black :orange]))
 ```
 
-![](../img/qwt_example_5.png)
+![](../img/qwt/qwt_example_7.png)
 
 ### Build plot in pieces
 
 Start with a base plot...
 
 ```julia
-plot(rand(100) / 3; reg=true,fillto=0)
+plot(rand(100) / 3,reg=true,fill=(0,:green))
 ```
 
-![](../img/qwt_example_6.png)
+![](../img/qwt/qwt_example_8.png)
 
 ### 
 
 and add to it later.
 
 ```julia
-scatter!(rand(100); markersize=6,color=:blue)
+scatter!(rand(100),markersize=6,c=:orange)
 ```
 
-![](../img/qwt_example_7.png)
+![](../img/qwt/qwt_example_9.png)
 
 ### Heatmaps
 
 
 
 ```julia
-heatmap(randn(10000),randn(10000); nbins=200)
+heatmap(randn(10000),randn(10000),nbins=100)
 ```
 
-![](../img/qwt_example_8.png)
+![](../img/qwt/qwt_example_10.png)
+
+### Line types
 
-### Lots of line types
 
-Options: (:line, :step, :stepinverted, :sticks, :dots, :none, :heatmap, :hexbin, :hist, :bar)  
-Note: some may not work with all backends
 
 ```julia
-plot(rand(20,4); linetypes=[:line,:step,:sticks,:dots])
+types = intersect(supportedTypes(),[:line,:path,:steppre,:steppost,:sticks,:scatter])'
+n = length(types)
+x = Vector[sort(rand(20)) for i = 1:n]
+y = rand(20,n)
+plot(x,y,line=(types,3),lab=map(string,types),ms=15)
 ```
 
-![](../img/qwt_example_9.png)
+![](../img/qwt/qwt_example_11.png)
+
+### Line styles
+
+
+
+```julia
+styles = setdiff(supportedStyles(),[:auto])'
+plot(cumsum(randn(20,length(styles)),1); style=:auto,label=map(string,styles),w=5)
+```
+
+![](../img/qwt/qwt_example_12.png)
+
+### Marker types
+
+
+
+```julia
+markers = setdiff(supportedMarkers(),[:none,:auto])'
+scatter(0.5:9.5,[fill(i - 0.5,10) for i = length(markers):-1:1]; marker=:auto,label=map(string,markers),ms=12)
+```
+
+![](../img/qwt/qwt_example_13.png)
 
 ### Bar
 
 x is the midpoint of the bar. (todo: allow passing of edges instead of midpoints)
 
 ```julia
-bar(randn(1000))
+bar(randn(999))
 ```
 
-![](../img/qwt_example_10.png)
+![](../img/qwt/qwt_example_14.png)
 
 ### Histogram
 
-note: fillto isn't supported on all backends
+
 
 ```julia
-histogram(randn(1000); nbins=50,fillto=20)
+histogram(randn(1000),nbins=50)
 ```
 
-![](../img/qwt_example_11.png)
+![](../img/qwt/qwt_example_15.png)
 
 ### Subplots
 
   subplot and subplot! are distinct commands which create many plots and add series to them in a circular fashion.
   You can define the layout with keyword params... either set the number of plots `n` (and optionally number of rows `nr` or 
-  number of columns `nc`), or you can set the layout directly with `layout`.  
-
-  Note: Gadfly is not very friendly here, and although you can create a plot and save a PNG, I haven't been able to actually display it.
+  number of columns `nc`), or you can set the layout directly with `layout`.
 
 
 ```julia
-subplot(randn(100,5); layout=[1,1,3],linetypes=[:line,:hist,:dots,:step,:bar],nbins=10,legend=false)
+subplot(randn(100,5),layout=[1,1,3],t=[:line :hist :scatter :step :bar],nbins=10,leg=false)
 ```
 
-![](../img/qwt_example_12.png)
+![](../img/qwt/qwt_example_16.png)
 
 ### Adding to subplots
 
 Note here the automatic grid layout, as well as the order in which new series are added to the plots.
 
 ```julia
-subplot(randn(100,5); n=4)
+subplot(fakedata(100,10),n=4,palette=[:grays :blues :heat :lightrainbow],bg=[:orange :pink :darkblue :black])
 ```
 
-![](../img/qwt_example_13.png)
+![](../img/qwt/qwt_example_17.png)
 
 ### 
 
 
 
 ```julia
-subplot!(randn(100,3))
+subplot!(fakedata(100,10))
 ```
 
-![](../img/qwt_example_14.png)
+![](../img/qwt/qwt_example_18.png)
+
+### Annotations
+
+Currently only text annotations are supported.  Pass in a tuple or vector-of-tuples: (x,y,text).  `annotate!(ann)` is shorthand for `plot!(; annotation=ann)`
+
+```julia
+y = rand(10)
+plot(y,ann=(3,y[3],"this is #3"))
+annotate!([(5,y[5],"this is #5"),(9,y[10],"this is #10")])
+```
+
+![](../img/qwt/qwt_example_20.png)
 

docs/readme_template.md

@@ -0,0 +1,292 @@
+# Plots
+
+[![Build Status](https://travis-ci.org/tbreloff/Plots.jl.svg?branch=master)](https://travis-ci.org/tbreloff/Plots.jl)
+[![Plots](http://pkg.julialang.org/badges/Plots_0.3.svg)](http://pkg.julialang.org/?pkg=Plots&ver=0.3)
+[![Plots](http://pkg.julialang.org/badges/Plots_0.4.svg)](http://pkg.julialang.org/?pkg=Plots&ver=0.4)
+[![Plots](http://pkg.julialang.org/badges/Plots_0.5.svg)](http://pkg.julialang.org/?pkg=Plots&ver=0.5)
+
+#### Author: Thomas Breloff (@tbreloff)
+
+Plots is a plotting interface and wrapper for several plotting packages.  My goals with the package are:
+
+- Simple.  The interface should be intuitive enough that someone coming from Matlab, Python, etc can immediately start generating complex plots without reading volumes of documentation.
+- Automatic (if you want).  There should be smart defaults for the most common functionality, and simple, high-level ways to override complex functionality.
+- Flexible.  You should be able to produce your favorite plot in your favorite package, but quicker and simpler.
+- Consistent.  Don't commit to one graphics package.  One command will switch your backend, and the exact same plotting commands will work with a very different underlying backend.
+
+Please add wishlist items, bugs, or any other comments/questions to the issues list.
+
+Check out the [summary graphs](img/supported/supported.md) for the features that each backend supports.
+
+## Examples for each implemented backend:
+
+- [Qwt.jl](docs/qwt_examples.md)
+- [Gadfly.jl](docs/gadfly_examples.md)
+- [UnicodePlots.jl](docs/unicodeplots_examples.md)
+- [PyPlot.jl](docs/pyplot_examples.md)
+- [Immerse.jl](docs/immerse_examples.md)
+- [Winston.jl](docs/winston_examples.md)
+
+## Installation
+
+First, add the package
+
+```julia
+Pkg.add("Plots")
+
+# if you want the latest features:
+Pkg.checkout("Plots")
+
+# or for the bleeding edge:
+Pkg.checkout("Plots", "dev")
+```
+
+then get any plotting packages you need (obviously, you should get at least one backend):
+
+```julia
+Pkg.add("Gadfly")
+Pkg.add("Immerse")
+Pkg.add("UnicodePlots")
+Pkg.add("PyPlot")                                    # requires python and matplotlib
+Pkg.clone("https://github.com/tbreloff/Qwt.jl.git")  # requires pyqt and pyqwt
+Pkg.add("Winston")
+```
+
+## Use
+
+Load it in.  The underlying plotting backends are not imported until `backend()` is called (which happens
+on your first call to `plot` or `subplot`).  This means that you don't need any backends to be installed when you call `using Plots`.
+Plots will try to figure out a good default backend for you automatically based on what backends are installed.
+
+```julia
+using Plots
+```
+
+Do a plot in Gadfly (inspired by [this example](http://gadflyjl.org/geom_point.html)), then save a png:
+
+```julia
+gadfly()        # switch to Gadfly as a backend
+dataframes()    # turn on support for DataFrames inputs
+
+# load some data
+using RDatasets
+iris = dataset("datasets", "iris");
+
+# This will bring up a browser window with the plot. Add a semicolon at the end to skip display. 
+scatter(iris, :SepalLength, :SepalWidth, group=:Species, m=([:+ :d :s], 12))
+
+# save a png (equivalent to png("gadfly1.png") and savefig("gadfly1.png"))
+png("gadfly1")
+```
+
+![gadfly_plt](img/gadfly1.png)
+
+See the examples pages for lots of examples of plots, and what those commands produce for each supported backend.  
+Also check out the [IJulia notebooks](examples) and see how it works interactively.
+
+## API
+
+Call `backend(backend::Symbol)` or the shorthands (`gadfly()`, `qwt()`, `unicodeplots()`, etc) to set the current plotting backend.
+Subsequent commands are converted into the relevant plotting commands for that package:
+
+```julia
+gadfly()
+plot(1:10)    # this effectively calls `y = 1:10; Gadfly.plot(x=1:length(y), y=y)`
+qwt()
+plot(1:10)    # this effectively calls `Qwt.plot(1:10)`
+```
+
+Use `plot` to create a new plot object, and `plot!` to add to an existing one:
+
+```julia
+plot(args...; kw...)                  # creates a new plot window, and sets it to be the `current`
+plot!(args...; kw...)                 # adds to the `current`
+plot!(plotobj, args...; kw...)        # adds to the plot `plotobj`
+```
+
+Now that you know which plot object you're updating (new, current, or other), I'll leave it off for simplicity.
+There are many ways to pass in data to the plot functions... some examples:
+
+- Vector-like (subtypes of AbstractArray{T,1})
+- Matrix-like (subtypes of AbstractArray{T,2})
+- Vectors of Vectors
+- Functions
+- Vectors of Functions
+- DataFrames with column symbols (initialize with `dataframes()`)
+
+In general, you can pass in a `y` only, or an `x` and `y`, both of whatever type(s) you want, and Plots will slice up the data as needed.
+For matrices, data is split by columns.  For functions, data is mapped.  For DataFrames, a Symbol/Symbols in place of x/y will map to
+the relevant column(s).
+
+Here are some example usages... remember you can always use `plot!` to update an existing plot, and that, unless specified, you will update the `current()`.
+
+```julia
+plot()                                    # empty plot object
+plot(4)                                   # initialize with 4 empty series
+plot(rand(10))                            # plot 1 series... x = 1:10
+plot(rand(10,5))                          # plot 5 series... x = 1:10
+plot(rand(10), rand(10))                  # plot 1 series
+plot(rand(10,5), rand(10))                # plot 5 series... y is the same for all
+plot(sin, rand(10))                       # y = sin(x)
+plot(rand(10), sin)                       # same... y = sin(x)
+plot([sin,cos], 0:0.1:π)                  # plot 2 series, sin(x) and cos(x)
+plot([sin,cos], 0, π)                     # plot sin and cos on the range [0, π]
+plot(1:10, Any[rand(10), sin])            # plot 2 series, y = rand(10) for the first, y = sin(x) for the second... x = 1:10 for both
+plot(dataset("Ecdat", "Airline"), :Cost)  # plot from a DataFrame (call `dataframes()` first to import DataFrames and initialize)
+```
+
+All plot methods accept a number of keyword arguments (see the tables below), which follow some rules:
+- Many arguments have aliases which are replaced during preprocessing.  `c` is the same as `color`, `m` is the same as `marker`, etc.  You can choose how verbose you'd like to be.  (see the tables below)
+- There are some special arguments (`xaxis`, `yaxis`, `line`, `marker`, `fill` and the aliases `l`, `m`, `f`) which magically set many related things at once.  (see the __Tip__ below)
+- If the argument is a "matrix-type", then each column will map to a series, cycling through columns if there are fewer columns than series.  Anything else will apply the argument value to every series.
+- Many arguments accept many different types... for example the `color` (also `markercolor`, `fillcolor`, etc) argument will accept strings or symbols with a color name, or any `Colors.Colorant`, or a `ColorScheme`, or a symbol representing a `ColorGradient`, or an AbstractVector of colors/symbols/etc...
+
+You can update certain plot settings after plot creation (not supported on all backends):
+
+```julia
+plot!(title = "New Title", xlabel = "New xlabel", ylabel = "New ylabel")
+plot!(xlims = (0, 5.5), ylims = (-2.2, 6), xticks = 0:0.5:10, yticks = [0,1,5,10])
+
+# using shorthands:
+xaxis!("mylabel", :log10, :flip)
+```
+
+With `subplot`, create multiple plots at once, with flexible layout options:
+
+```julia
+y = rand(100,3)
+subplot(y; n = 3)             # create an automatic grid, and let it figure out the shape
+subplot(y; n = 3, nr = 1)     # create an automatic grid, but fix the number of rows
+subplot(y; n = 3, nc = 1)     # create an automatic grid, but fix the number of columns
+subplot(y; layout = [1, 2])   # explicit layout.  Lists the number of plots in each row
+```
+
+__Tip__: You can call `subplot!(args...; kw...)` to add to an existing subplot.
+
+__Tip__: Calling `subplot!` on a `Plot` object, or `plot!` on a `Subplot` object will throw an error.
+
+Shorthands:
+
+```julia
+scatter(args...; kw...)    = plot(args...; kw...,  linetype = :scatter)
+scatter!(args...; kw...)   = plot!(args...; kw..., linetype = :scatter)
+bar(args...; kw...)        = plot(args...; kw...,  linetype = :bar)
+bar!(args...; kw...)       = plot!(args...; kw..., linetype = :bar)
+histogram(args...; kw...)  = plot(args...; kw...,  linetype = :hist)
+histogram!(args...; kw...) = plot!(args...; kw..., linetype = :hist)
+heatmap(args...; kw...)    = plot(args...; kw...,  linetype = :heatmap)
+heatmap!(args...; kw...)   = plot!(args...; kw..., linetype = :heatmap)
+sticks(args...; kw...)     = plot(args...; kw...,  linetype = :sticks, marker = :ellipse)
+sticks!(args...; kw...)    = plot!(args...; kw..., linetype = :sticks, marker = :ellipse)
+hline(args...; kw...)      = plot(args...; kw...,  linetype = :hline)
+hline!(args...; kw...)     = plot!(args...; kw..., linetype = :hline)
+vline(args...; kw...)      = plot(args...; kw...,  linetype = :vline)
+vline!(args...; kw...)     = plot!(args...; kw..., linetype = :vline)
+ohlc(args...; kw...)       = plot(args...; kw...,  linetype = :ohlc)
+ohlc!(args...; kw...)      = plot!(args...; kw..., linetype = :ohlc)
+
+title!(s::AbstractString)                 = plot!(title = s)
+xlabel!(s::AbstractString)                = plot!(xlabel = s)
+ylabel!(s::AbstractString)                = plot!(ylabel = s)
+xlims!{T<:Real,S<:Real}(lims::Tuple{T,S}) = plot!(xlims = lims)
+ylims!{T<:Real,S<:Real}(lims::Tuple{T,S}) = plot!(ylims = lims)
+xticks!{T<:Real}(v::AVec{T})              = plot!(xticks = v)
+yticks!{T<:Real}(v::AVec{T})              = plot!(yticks = v)
+xflip!(flip::Bool = true)                 = plot!(xflip = flip)
+yflip!(flip::Bool = true)                 = plot!(yflip = flip)
+xaxis!(args...)                           = plot!(xaxis = args)
+yaxis!(args...)                           = plot!(yaxis = args)
+annotate!(anns)                           = plot!(annotation = anns)
+```
+
+Some keyword arguments you can set:
+
+[[KEYWORD_ARGS_TABLE]]
+
+Plot types:
+
+[[LINETYPES_TABLE]]
+
+Line styles:
+
+[[LINESTYLES_TABLE]]
+
+Markers:
+
+[[MARKERS_TABLE]]
+
+
+__Tip__: You can see the default value for a given argument with `default(arg::Symbol)`, and set the default value with `default(arg::Symbol, value)` or `default(; kw...)`.  For example set the default window size and whether we should show a legend with `default(size=(600,400), leg=false)`.
+
+__Tip__: There are some helper arguments you can set:  `xaxis`, `yaxis`, `line`, `marker`, `fill`.  These go through special preprocessing to extract values into individual arguments.  The order doesn't matter, and if you pass a single value it's equivalent to wrapping it in a Tuple.  Examples:
+
+```
+plot(y, xaxis = ("mylabel", :log, :flip, (-1,1)))   # this sets the `xlabel`, `xscale`, `xflip`, and `xlims` arguments automatically
+plot(y, line = (:bar, :blue, :dot, 10))             # this sets the `linetype`, `color`, `linestyle`, and `linewidth` arguments automatically
+plot(y, marker = (:rect, :red, 10))                 # this sets the `markershape`, `markercolor`, and `markersize` arguments automatically
+plot(y, fill = (:green, 10))                        # this sets the `fillcolor` and `fillrange` arguments automatically
+                                                    # Note: `fillrange` can be:
+                                                              a number (fill to horizontal line)
+                                                              a vector of numbers (different for each data point)
+                                                              a tuple of vectors (fill a band)
+```
+
+__Tip__: When plotting multiple lines, you can set all series to use the same value, or pass in a matrix to cycle through values.  Example:
+
+```julia
+plot(rand(100,4); color = [:red RGB(0,0,1)],     # (Matrix) lines 1 and 3 are red, lines 2 and 4 are blue
+                  axis = :auto,                  # lines 1 and 3 are on the left axis, lines 2 and 4 are on the right
+                  markershape = [:rect, :star1]  # (Vector) ALL lines are passed the vector [:rect, :star1]
+                  width = 5)                     # all lines have a width of 5
+```
+
+__Tip__: Not all features are supported for each backend, but you can see what's supported by calling the functions: `supportedArgs()`, `supportedAxes()`, `supportedTypes()`, `supportedStyles()`, `supportedMarkers()`, `subplotSupported()`
+
+__Tip__: Call `gui()` to display the plot in a window.  Interactivity depends on backend.  Plotting at the REPL (without semicolon) implicitly calls `gui()`.
+
+## TODO features:
+
+- [x] Plot vectors/matrices/functions
+- [x] Plot DataFrames
+- [x] Grouping
+- [x] Annotations
+- [x] Scales
+- [x] Categorical Inputs (strings, etc... for hist, bar? or can split one series into multiple?)
+- [ ] Custom markers
+- [ ] Special plots (boxplot, ohlc?)
+- [x] Subplots
+- [x] Histograms
+- [ ] 3D plotting
+- [ ] Scenes/Drawing
+- [ ] Graphs
+- [ ] Interactivity (GUIs)
+
+## TODO backends:
+
+- [x] Gadfly.jl
+- [x] Immerse.jl
+- [x] PyPlot.jl
+- [x] UnicodePlots.jl
+- [x] Qwt.jl
+- [x] Winston.jl
+- [ ] GLPlot.jl
+- [ ] Bokeh.jl
+- [ ] Vega.jl
+- [ ] Gaston.jl
+- [ ] Plotly.jl
+- [ ] GoogleCharts.jl
+- [ ] PLplot.jl
+- [ ] TextPlots.jl
+- [ ] ASCIIPlots.jl
+- [ ] Sparklines.jl
+- [ ] Hinton.jl
+- [ ] ImageTerm.jl
+- [ ] GraphViz.jl
+- [ ] TikzGraphs.jl
+- [ ] GraphLayout.jl
+
+## More information on backends (both supported and unsupported)
+
+See the wiki at: https://github.com/JuliaPlot/juliaplot_docs/wiki
+
+

docs/unicodeplots_examples.md

@@ -0,0 +1,211 @@
+# Examples for backend: unicodeplots
+
+- Supported arguments: `args`, `axis`, `color`, `kwargs`, `label`, `legend`, `linestyle`, `linetype`, `marker`, `markercolor`, `markersize`, `nbins`, `size`, `title`, `width`, `windowtitle`, `xlabel`, `ylabel`, `yrightlabel`
+- Supported values for axis: `:auto`, `:left`
+- Supported values for linetype: `:none`, `:line`, `:step`, `:sticks`, `:scatter`, `:heatmap`, `:hexbin`, `:hist`, `:bar`
+- Supported values for linestyle: `:auto`, `:solid`
+- Supported values for marker: `:none`, `:auto`, `:ellipse`
+- Is `subplot`/`subplot!` supported? Yes
+
+### Initialize
+
+```julia
+using Plots
+unicodeplots()
+```
+
+### Lines
+
+A simple line plot of the 3 columns.
+
+```julia
+plot(rand(100,3))
+```
+
+![](../img/unicodeplots/unicodeplots_example_1.png)
+
+### Functions
+
+Plot multiple functions.  You can also put the function first.
+
+```julia
+plot(0:0.01:4π,[sin,cos])
+```
+
+![](../img/unicodeplots/unicodeplots_example_2.png)
+
+### 
+
+You can also call it with plot(f, xmin, xmax).
+
+```julia
+plot([sin,cos],0,4π)
+```
+
+![](../img/unicodeplots/unicodeplots_example_3.png)
+
+### 
+
+Or make a parametric plot (i.e. plot: (fx(u), fy(u))) with plot(fx, fy, umin, umax).
+
+```julia
+plot(sin,(x->begin  # /home/tom/.julia/v0.4/Plots/docs/example_generation.jl, line 33:
+            sin(2x)
+        end),0,2π)
+```
+
+![](../img/unicodeplots/unicodeplots_example_4.png)
+
+### Global
+
+Change the guides/background without a separate call.
+
+```julia
+plot(rand(10); title="TITLE",xlabel="XLABEL",ylabel="YLABEL",background_color=RGB(0.5,0.5,0.5))
+```
+
+![](../img/unicodeplots/unicodeplots_example_5.png)
+
+### Two-axis
+
+Use the `axis` or `axiss` arguments.
+
+Note: Currently only supported with Qwt and PyPlot
+
+```julia
+plot(Vector[randn(100),randn(100) * 100]; axiss=[:left,:right],ylabel="LEFT",yrightlabel="RIGHT")
+```
+
+![](../img/unicodeplots/unicodeplots_example_6.png)
+
+### Vectors w/ pluralized args
+
+Plot multiple series with different numbers of points.  Mix arguments that apply to all series (singular... see `marker`) with arguments unique to each series (pluralized... see `colors`).
+
+```julia
+plot(Vector[rand(10),rand(20)]; marker=:ellipse,markersize=8,colors=[:red,:blue])
+```
+
+![](../img/unicodeplots/unicodeplots_example_7.png)
+
+### Build plot in pieces
+
+Start with a base plot...
+
+```julia
+plot(rand(100) / 3; reg=true,fillto=0)
+```
+
+![](../img/unicodeplots/unicodeplots_example_8.png)
+
+### 
+
+and add to it later.
+
+```julia
+scatter!(rand(100); markersize=6,color=:blue)
+```
+
+![](../img/unicodeplots/unicodeplots_example_9.png)
+
+### Heatmaps
+
+
+
+```julia
+heatmap(randn(10000),randn(10000); nbins=100)
+```
+
+![](../img/unicodeplots/unicodeplots_example_10.png)
+
+### Suported line types
+
+All options: (:line, :orderedline, :step, :stepinverted, :sticks, :scatter, :none, :heatmap, :hexbin, :hist, :bar)
+
+```julia
+types = intersect(supportedTypes(),[:line,:step,:stepinverted,:sticks,:scatter])
+n = length(types)
+x = Vector[sort(rand(20)) for i = 1:n]
+y = rand(20,n)
+plot(x,y; linetypes=types,labels=map(string,types))
+```
+
+![](../img/unicodeplots/unicodeplots_example_11.png)
+
+### Supported line styles
+
+All options: (:solid, :dash, :dot, :dashdot, :dashdotdot)
+
+```julia
+styles = setdiff(supportedStyles(),[:auto])
+plot(rand(20,length(styles)); linestyle=:auto,labels=map(string,styles))
+```
+
+![](../img/unicodeplots/unicodeplots_example_12.png)
+
+### Supported marker types
+
+All options: (:none, :auto, :ellipse, :rect, :diamond, :utriangle, :dtriangle, :cross, :xcross, :star1, :star2, :hexagon)
+
+```julia
+markers = setdiff(supportedMarkers(),[:none,:auto])
+plot([fill(i,10) for i = 1:length(markers)]; marker=:auto,labels=map(string,markers),markersize=10)
+```
+
+![](../img/unicodeplots/unicodeplots_example_13.png)
+
+### Bar
+
+x is the midpoint of the bar. (todo: allow passing of edges instead of midpoints)
+
+```julia
+bar(randn(1000))
+```
+
+![](../img/unicodeplots/unicodeplots_example_14.png)
+
+### Histogram
+
+note: fillto isn't supported on all backends
+
+```julia
+histogram(randn(1000); nbins=50,fillto=20)
+```
+
+![](../img/unicodeplots/unicodeplots_example_15.png)
+
+### Subplots
+
+  subplot and subplot! are distinct commands which create many plots and add series to them in a circular fashion.
+  You can define the layout with keyword params... either set the number of plots `n` (and optionally number of rows `nr` or 
+  number of columns `nc`), or you can set the layout directly with `layout`.  
+
+  Note: Gadfly is not very friendly here, and although you can create a plot and save a PNG, I haven't been able to actually display it.
+
+
+```julia
+subplot(randn(100,5); layout=[1,1,3],linetypes=[:line,:hist,:scatter,:step,:bar],nbins=10,legend=false)
+```
+
+![](../img/unicodeplots/unicodeplots_example_16.png)
+
+### Adding to subplots
+
+Note here the automatic grid layout, as well as the order in which new series are added to the plots.
+
+```julia
+subplot(randn(100,5); n=4)
+```
+
+![](../img/unicodeplots/unicodeplots_example_17.png)
+
+### 
+
+
+
+```julia
+subplot!(randn(100,3))
+```
+
+![](../img/unicodeplots/unicodeplots_example_18.png)
+

docs/winston_examples.md

@@ -0,0 +1,180 @@
+# Examples for backend: winston
+
+- Supported arguments: `annotation`, `color`, `color_palette`, `fillrange`, `fillcolor`, `group`, `label`, `legend`, `linestyle`, `linetype`, `linewidth`, `markershape`, `markercolor`, `markersize`, `nbins`, `reg`, `show`, `size`, `title`, `windowtitle`, `x`, `xlabel`, `xlims`, `y`, `ylabel`, `ylims`, `xscale`, `yscale`
+- Supported values for axis: `:auto`, `:left`
+- Supported values for linetype: `:none`, `:line`, `:path`, `:sticks`, `:scatter`, `:hist`, `:bar`
+- Supported values for linestyle: `:auto`, `:solid`, `:dash`, `:dot`, `:dashdot`
+- Supported values for marker: `:none`, `:auto`, `:rect`, `:ellipse`, `:diamond`, `:utriangle`, `:dtriangle`, `:cross`, `:xcross`, `:star1`
+- Is `subplot`/`subplot!` supported? No
+
+### Initialize
+
+```julia
+using Plots
+winston()
+```
+
+### Lines
+
+A simple line plot of the columns.
+
+```julia
+plot(fakedata(50,5),w=3)
+```
+
+![](../img/winston/winston_example_1.png)
+
+### Functions
+
+Plot multiple functions.  You can also put the function first, or use the form `plot(f, xmin, xmax)` where f is a Function or AbstractVector{Function}.
+
+```julia
+plot(0:0.01:4π,[sin,cos])
+```
+
+![](../img/winston/winston_example_2.png)
+
+### 
+
+Or make a parametric plot (i.e. plot: (fx(u), fy(u))) with plot(fx, fy, umin, umax).
+
+```julia
+plot(sin,(x->begin  # /home/tom/.julia/v0.4/Plots/docs/example_generation.jl, line 39:
+            sin(2x)
+        end),0,2π,line=4,leg=false,fill=(0,:orange))
+```
+
+![](../img/winston/winston_example_3.png)
+
+### Colors
+
+Access predefined palettes (or build your own with the `colorscheme` method).  Line/marker colors are auto-generated from the plot's palette, unless overridden.  Set the `z` argument to turn on series gradients.
+
+```julia
+y = rand(100)
+plot(0:10:100,rand(11,4),lab="lines",w=3,palette=:grays,fill=(0.5,:auto))
+scatter!(y,z=abs(y - 0.5),m=(10,:heat),lab="grad")
+```
+
+![](../img/winston/winston_example_4.png)
+
+### Global
+
+Change the guides/background/limits/ticks.  Convenience args `xaxis` and `yaxis` allow you to pass a tuple or value which will be mapped to the relevant args automatically.  The `xaxis` below will be replaced with `xlabel` and `xlims` args automatically during the preprocessing step. You can also use shorthand functions: `title!`, `xaxis!`, `yaxis!`, `xlabel!`, `ylabel!`, `xlims!`, `ylims!`, `xticks!`, `yticks!`
+
+```julia
+plot(rand(20,3),title="TITLE",xaxis=("XLABEL",(-5,30),0:2:20,:flip),yaxis=("YLABEL",:log10),background_color=RGB(0.2,0.2,0.2),leg=false)
+```
+
+![](../img/winston/winston_example_5.png)
+
+### Two-axis
+
+Use the `axis` arguments.
+
+Note: Currently only supported with Qwt and PyPlot
+
+```julia
+plot(Vector[randn(100),randn(100) * 100]; axis=[:l :r],ylabel="LEFT",yrightlabel="RIGHT")
+```
+
+![](../img/winston/winston_example_6.png)
+
+### Arguments
+
+Plot multiple series with different numbers of points.  Mix arguments that apply to all series (marker/markersize) with arguments unique to each series (colors).  Special arguments `line`, `marker`, and `fill` will automatically figure out what arguments to set (for example, we are setting the `linestyle`, `linewidth`, and `color` arguments with `line`.)  Note that we pass a matrix of colors, and this applies the colors to each series.
+
+```julia
+plot(Vector[rand(10),rand(20)]; marker=(:ellipse,8),line=(:dot,3,[:black :orange]))
+```
+
+![](../img/winston/winston_example_7.png)
+
+### Build plot in pieces
+
+Start with a base plot...
+
+```julia
+plot(rand(100) / 3,reg=true,fill=(0,:green))
+```
+
+![](../img/winston/winston_example_8.png)
+
+### 
+
+and add to it later.
+
+```julia
+scatter!(rand(100),markersize=6,c=:orange)
+```
+
+![](../img/winston/winston_example_9.png)
+
+### Line types
+
+
+
+```julia
+types = intersect(supportedTypes(),[:line,:path,:steppre,:steppost,:sticks,:scatter])'
+n = length(types)
+x = Vector[sort(rand(20)) for i = 1:n]
+y = rand(20,n)
+plot(x,y,line=(types,3),lab=map(string,types),ms=15)
+```
+
+![](../img/winston/winston_example_11.png)
+
+### Line styles
+
+
+
+```julia
+styles = setdiff(supportedStyles(),[:auto])'
+plot(cumsum(randn(20,length(styles)),1); style=:auto,label=map(string,styles),w=5)
+```
+
+![](../img/winston/winston_example_12.png)
+
+### Marker types
+
+
+
+```julia
+markers = setdiff(supportedMarkers(),[:none,:auto])'
+scatter(0.5:9.5,[fill(i - 0.5,10) for i = length(markers):-1:1]; marker=:auto,label=map(string,markers),ms=12)
+```
+
+![](../img/winston/winston_example_13.png)
+
+### Bar
+
+x is the midpoint of the bar. (todo: allow passing of edges instead of midpoints)
+
+```julia
+bar(randn(999))
+```
+
+![](../img/winston/winston_example_14.png)
+
+### Histogram
+
+
+
+```julia
+histogram(randn(1000),nbins=50)
+```
+
+![](../img/winston/winston_example_15.png)
+
+### Annotations
+
+Currently only text annotations are supported.  Pass in a tuple or vector-of-tuples: (x,y,text).  `annotate!(ann)` is shorthand for `plot!(; annotation=ann)`
+
+```julia
+y = rand(10)
+plot(y,ann=(3,y[3],"this is #3"))
+annotate!([(5,y[5],"this is #5"),(9,y[10],"this is #10")])
+```
+
+![](../img/winston/winston_example_20.png)
+