From c43b34b67fd0ef942dcc43dc859cb74a4bd89fb2 Mon Sep 17 00:00:00 2001 From: Thomas Breloff Date: Mon, 21 Sep 2015 16:49:45 -0400 Subject: [PATCH] auto-generated readme --- README.md | 183 +++++++++++++++---------------------- docs/example_generation.jl | 45 +++++++++ docs/readme_template.md | 55 ----------- src/args.jl | 10 +- 4 files changed, 121 insertions(+), 172 deletions(-) diff --git a/README.md b/README.md index 0bce60b6..96acbdeb 100644 --- a/README.md +++ b/README.md @@ -4,7 +4,12 @@ #### Author: Thomas Breloff (@tbreloff) -Plotting interface and wrapper for several plotting packages. +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. @@ -52,8 +57,8 @@ Do a plot in Gadfly, then save a png: # switch to Gadfly as a backend gadfly!() -# This will bring up a browser window with the plot. Add a semicolon to skip display. -plot(rand(10,2); marker = :rect, markersizes=[10,30]) +# This will bring up a browser window with the plot. Add a semicolon at the end to skip display. +plot(rand(10,2); marker = :rect, markersize = [10,30], style = :auto) # save it as a PNG savepng(Plots.IMG_DIR * "gadfly1.png") @@ -86,55 +91,33 @@ 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: + +- Vector-like (subtypes of AbstractArray{T,1}) +- Matrix-like (subtypes of AbstractArray{T,2}) +- Vectors of Vectors +- Functions +- Vectors of Functions +- (TODO) DataFrames with column symbols + +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 (TODO), a Symbol/Symbols in place of x/y will map to +the relevant column(s) and also automatically set the associated legend label. + +Here are some example usages... remember you can always use `plot!` to update an existing plot, and that, unless specified, you will update the `currentPlot()`. ```julia -# one line... x = 1:length(y) -plot(y::AVec; kw...) - -# one line (will assert length(x) == length(y)) -plot(x::AVec, y::AVec; kw...) - -# multiple lines (one per column of x), all sharing x = 1:size(y,1) -plot(y::AMat; kw...) - -# multiple lines (one per column of x), all sharing x (will assert length(x) == size(y,1)) -plot(x::AVec, y::AMat; kw...) - -# multiple lines (one per column of x/y... will assert size(x) == size(y)) -plot(x::AMat, y::AMat; kw...) - -# one line, map function for range [xmin,xmax] -plot(f::Function, xmin::Real, xmax::Real; kw...) - -# multiple lines, map functions for range [xmin,xmax] -plot(f::AVec{Function}, xmin::Real, xmax::Real; kw...) - -# parametric plot... x = fx(u), y = fy(u) -plot(fx::Function, fy::Function, umin::Real, umax::Real; kw...) - -# one line, y = f(x)... can swap x and f -plot(x::AVec, f::Function; kw...) - -# multiple lines, yᵢⱼ = f(xᵢⱼ)... can swap f and x -plot(x::AMat, f::Function; kw...) - -# multiple lines, yᵢⱼ = fⱼ(xᵢ) -plot(x::AVec, fs::AVec{Function}; kw...) - -# multiple lines, each with x = 1:length(y[i]) -plot(y::AVec{AVec}; kw...) - -# multiple lines, will assert length(x) == length(y[i]) -plot(x::AVec, y::AVec{AVec}; kw...) - -# multiple lines, will assert length(x[i]) == length(y[i]) -plot(x::AVec{AVec}, y::AVec{AVec}; kw...) - -# n lines, all empty (for updating plots) -plot(n::Integer; kw...) - -# TODO: DataFrames, categorical values +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, [rand(10), sin]) # plot 2 series, y = rand(10) for the first, y = sin(x) for the second... x = 1:10 for both ``` With `subplot`, create multiple plots at once, with flexible layout options: @@ -164,77 +147,61 @@ 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) ``` 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, :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 -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) -``` +Keyword | Default Value | Aliases | Applies To +-- | -- | -- | -- +args | Any[] | [:args,:argss] | Series +axis | left | [:axis,:axiss] | Series +color | auto | [:c,:color,:colors] | Series +fillto | nothing | [:area,:fill,:fillto,:filltos] | Series +group | nothing | [:g,:group,:groups] | Series +heatmap_c | (0.15,0.5) | [:heatmap_c,:heatmap_cs] | Series +kwargs | Any[] | [:kwargs,:kwargss] | Series +label | AUTO | [:lab,:label,:labels] | Series +linestyle | solid | [:linestyle,:linestyles,:ls,:s,:style] | Series +linetype | path | [:linetype,:linetypes,:lt,:t,:type] | Series +marker | none | [:m,:marker,:markers] | Series +markercolor | match | [:markercolor,:markercolors,:mc,:mcolor] | Series +markersize | 6 | [:markersize,:markersizes,:ms,:msize] | Series +nbins | 100 | [:nb,:nbin,:nbins,:nbinss] | Series +reg | false | [:reg,:regs] | Series +ribbon | nothing | [:r,:ribbon,:ribbons] | Series +width | 1 | [:linewidth,:w,:width,:widths] | Series +background_color | RGB{Float64}(0.1,0.1,0.1) | [:background,:background_color,:bg,:bg_color,:bgcolor] | Plot +legend | true | [:leg,:legend] | Plot +show | false | [:display,:show] | Plot +size | (800,600) | [:size,:windowsize,:wsize] | Plot +title | | [:title] | Plot +windowtitle | Plots.jl | [:windowtitle,:wtitle] | Plot +xlabel | | [:xlab,:xlabel] | Plot +xticks | true | [:xticks] | Plot +ylabel | | [:ylab,:ylabel] | Plot +yrightlabel | | [:y2lab,:y2label,:ylab2,:ylabel2,:ylabelright,:ylabr,:yrightlabel,:yrlab] | Plot +yticks | true | [:yticks] | Plot -Note that not every backend supports all options. -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 = (600,400) -pos = (0,0) -windowtitle = "Plots.jl" -screen = 1 -``` __Tip__: You can see the default value for a given argument with `plotDefault(arg::Symbol)`, and set the default value with `plotDefault!(arg::Symbol, value)` -__Tip__: 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) +__Tip__: When plotting multiple lines, you can set all series to use the same value, or pass in an array to cycle through values. Example: ```julia -# Note: The same width is applied to both lines, whereas -# each line gets different color and axis. -plot(rand(100,2); colors = [:red, RGB(.5,.5,0)], - axiss = [:left, :right], - width = 5) +plot(rand(100,4); color = [:red, RGB(0,0,1)], # 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 + 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: `supportedAxes()`, `supportedTypes()`, `supportedStyles()`, `supportedMarkers()`, `subplotSupported()` + ## TODO features: - [x] Plot vectors/matrices/functions diff --git a/docs/example_generation.jl b/docs/example_generation.jl index 275ebb12..7ab8cce7 100644 --- a/docs/example_generation.jl +++ b/docs/example_generation.jl @@ -187,6 +187,51 @@ function test_all_examples(pkgname::Symbol) 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 +# 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) + +const kwNotes = Dict( + ) + +function buildReadme() + readme = readall("$DOCDIR/readme_template.md") + + # build keyword arg table + kwtable = "Keyword | Default Value | Aliases | Applies To\n-- | -- | -- | --\n" + for d in (Plots._seriesDefaults, Plots._plotDefaults) + for k in sort(collect(keys(d))) + kwtable = string(kwtable, "$k | $(d[k]) | $(aliases(Plots._keyAliases, k)) | $(d==Plots._seriesDefaults ? "Series" : "Plot") \n") + end + end + readme = replace(readme, "[[KEYWORD_ARGS_TABLE]]", kwtable) + + readme_fn = Pkg.dir("Plots") * "/README.md" + f = open(readme_fn, "w") + write(f, readme) + close(f) +end + # run it! # note: generate separately so it's easy to comment out # @osx_only generate_markdown(:unicodeplots) diff --git a/docs/readme_template.md b/docs/readme_template.md index ce1dd6b9..82574c48 100644 --- a/docs/readme_template.md +++ b/docs/readme_template.md @@ -159,61 +159,6 @@ Some keyword arguments you can set: [[KEYWORD_ARGS_TABLE]] -[[REPLACE_START]] -``` -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 -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) -``` - -Note that not every backend supports all options. - -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 = (600,400) -pos = (0,0) -windowtitle = "Plots.jl" -screen = 1 -``` -[[REPLACE_END]] __Tip__: You can see the default value for a given argument with `plotDefault(arg::Symbol)`, and set the default value with `plotDefault!(arg::Symbol, value)` diff --git a/src/args.jl b/src/args.jl index 86abdf0a..af55ea90 100644 --- a/src/args.jl +++ b/src/args.jl @@ -175,6 +175,7 @@ const _keyAliases = Dict( :nb => :nbins, :nbin => :nbins, :fill => :fillto, + :area => :fillto, :g => :group, :r => :ribbon, :xlab => :xlabel, @@ -207,15 +208,6 @@ for arg in keys(_seriesDefaults) end -# function replaceAliases!(d::Dict) -# for (k,v) in d -# if haskey(_keyAliases, k) -# d[_keyAliases[k]] = v -# delete!(d, k) -# end -# end -# end - # -----------------------------------------------------------------------------