mantao/Plots.jl
1
0
Fork 0
Code Issues Pull Requests Projects Releases Wiki Activity

auto-generated readme

Browse Source
This commit is contained in:
Thomas Breloff 2015-09-21 16:49:45 -04:00
parent 3739c2881b
commit c43b34b67f
4 changed files with 121 additions and 172 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

183
README.md
View File

@ -4,7 +4,12 @@
#### Author: Thomas Breloff (@tbreloff) #### 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. 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 # switch to Gadfly as a backend
gadfly!() gadfly!()
# This will bring up a browser window with the plot. Add a semicolon to skip display. # 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, markersizes=[10,30]) plot(rand(10,2); marker = :rect, markersize = [10,30], style = :auto)
# save it as a PNG # save it as a PNG
savepng(Plots.IMG_DIR * "gadfly1.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. 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 ```julia
# one line... x = 1:length(y) plot() # empty plot object
plot(y::AVec; kw...) plot(4) # initialize with 4 empty series
plot(rand(10)) # plot 1 series... x = 1:10
# one line (will assert length(x) == length(y)) plot(rand(10,5)) # plot 5 series... x = 1:10
plot(x::AVec, y::AVec; kw...) plot(rand(10), rand(10)) # plot 1 series
plot(rand(10,5), rand(10)) # plot 5 series... y is the same for all
# multiple lines (one per column of x), all sharing x = 1:size(y,1) plot(sin, rand(10)) # y = sin(x)
plot(y::AMat; kw...) plot(rand(10), sin) # same... y = sin(x)
plot([sin,cos], 0:0.1:π) # plot 2 series, sin(x) and cos(x)
# multiple lines (one per column of x), all sharing x (will assert length(x) == size(y,1)) plot([sin,cos], 0, π) # plot sin and cos on the range [0, π]
plot(x::AVec, y::AMat; kw...) 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
# 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
``` ```
With `subplot`, create multiple plots at once, with flexible layout options: 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) 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)
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: Some keyword arguments you can set:
``` Keyword | Default Value | Aliases | Applies To
axis # :left or :right -- | -- | -- | --
color # can be a string ("red") or a symbol (:red) or a ColorsTypes.jl args | Any[] | [:args,:argss] | Series
# Colorant (RGB(1,0,0)) or :auto (which lets the package pick) axis | left | [:axis,:axiss] | Series
label # string or symbol, applies to that line, may go in a legend color | auto | [:c,:color,:colors] | Series
width # width of a line fillto | nothing | [:area,:fill,:fillto,:filltos] | Series
linetype # :line, :step, :stepinverted, :sticks, :scatter, :none, :heatmap, :hexbin, :hist, :bar group | nothing | [:g,:group,:groups] | Series
linestyle # :solid, :dash, :dot, :dashdot, :dashdotdot heatmap_c | (0.15,0.5) | [:heatmap_c,:heatmap_cs] | Series
marker # :none, :ellipse, :rect, :diamond, :utriangle, :dtriangle, kwargs | Any[] | [:kwargs,:kwargss] | Series
# :cross, :xcross, :star1, :star2, :hexagon label | AUTO | [:lab,:label,:labels] | Series
markercolor # same choices as `color`, or :match will set the color to be the same as `color` linestyle | solid | [:linestyle,:linestyles,:ls,:s,:style] | Series
markersize # size of the marker linetype | path | [:linetype,:linetypes,:lt,:t,:type] | Series
nbins # number of bins for heatmap/hexbin and histograms marker | none | [:m,:marker,:markers] | Series
heatmap_c # color cutoffs for Qwt heatmaps markercolor | match | [:markercolor,:markercolors,:mc,:mcolor] | Series
fillto # fillto value for area plots markersize | 6 | [:markersize,:markersizes,:ms,:msize] | Series
title # string or symbol, title of the plot nbins | 100 | [:nb,:nbin,:nbins,:nbinss] | Series
xlabel # string or symbol, label on the bottom (x) axis reg | false | [:reg,:regs] | Series
ylabel # string or symbol, label on the left (y) axis ribbon | nothing | [:r,:ribbon,:ribbons] | Series
yrightlabel # string or symbol, label on the right (y) axis width | 1 | [:linewidth,:w,:width,:widths] | Series
reg # true or false, add a regression line for each line background_color | RGB{Float64}(0.1,0.1,0.1) | [:background,:background_color,:bg,:bg_color,:bgcolor] | Plot
size # (Int,Int), resize the enclosing window legend | true | [:leg,:legend] | Plot
pos # (Int,Int), move the enclosing window to this position show | false | [:display,:show] | Plot
windowtitle # string or symbol, set the title of the enclosing windowtitle size | (800,600) | [:size,:windowsize,:wsize] | Plot
screen # Integer, move enclosing window to this screen number (for multiscreen desktops) 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__: 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. __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:
(yes I know it's not gramatically correct, but it's easy to use and implement)
```julia ```julia
# Note: The same width is applied to both lines, whereas plot(rand(100,4); color = [:red, RGB(0,0,1)], # lines 1 and 3 are red, lines 2 and 4 are blue
# each line gets different color and axis. axis = :auto, # lines 1 and 3 are on the left axis, lines 2 and 4 are on the right
plot(rand(100,2); colors = [:red, RGB(.5,.5,0)], width = 5) # all lines have a width of 5
axiss = [:left, :right],
width = 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: ## TODO features:
- [x] Plot vectors/matrices/functions - [x] Plot vectors/matrices/functions

45
docs/example_generation.jl
View File

@ -187,6 +187,51 @@ function test_all_examples(pkgname::Symbol)
plts plts
end 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! # run it!
# note: generate separately so it's easy to comment out # note: generate separately so it's easy to comment out
# @osx_only generate_markdown(:unicodeplots) # @osx_only generate_markdown(:unicodeplots)

55
docs/readme_template.md
View File

@ -159,61 +159,6 @@ Some keyword arguments you can set:
[[KEYWORD_ARGS_TABLE]] [[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)` __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)`

10
src/args.jl
View File

@ -175,6 +175,7 @@ const _keyAliases = Dict(
:nb => :nbins, :nb => :nbins,
:nbin => :nbins, :nbin => :nbins,
:fill => :fillto, :fill => :fillto,
:area => :fillto,
:g => :group, :g => :group,
:r => :ribbon, :r => :ribbon,
:xlab => :xlabel, :xlab => :xlabel,
@ -207,15 +208,6 @@ for arg in keys(_seriesDefaults)
end end
# function replaceAliases!(d::Dict)
# for (k,v) in d
# if haskey(_keyAliases, k)
# d[_keyAliases[k]] = v
# delete!(d, k)
# end
# end
# end
# ----------------------------------------------------------------------------- # -----------------------------------------------------------------------------