auto-generated readme
This commit is contained in:
Thomas Breloff
parent
3739c2881b
commit
c43b34b67f
183
README.md
183
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
|
||||
|
||||
@ -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)
|
||||
|
||||
@ -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)`
|
||||
|
||||
|
||||
10
src/args.jl
10
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
|
||||
|
||||
|
||||
# -----------------------------------------------------------------------------
|
||||
|
||||
|
||||
Loading…
x
Reference in New Issue
Block a user