diff --git a/README.md b/README.md index 117f2064..0f630a44 100644 --- a/README.md +++ b/README.md @@ -7,27 +7,26 @@ #### Author: Thomas Breloff (@tbreloff) -Plots is a plotting interface and wrapper for several plotting packages. My goals with the package are: +Plots is a plotting API and toolset. My goals with the package are: -- **Simple**. Intuitive enough that someone coming from Matlab, Python, etc can immediately start generating complex plots without reading volumes of documentation. -- **Concise**. Less code means fewer mistakes and more efficient development and analysis. -- **Smart**. Defaults for the most common functionality, and high-level ways to override complex functionality. +- **Intuitive** Start generating complex plots without reading volumes of documentation. Commands should "just work". +- **Concise**. Less code means fewer mistakes and more efficient development/analysis. - **Flexible**. Produce your favorite plots from your favorite package, but quicker and simpler. - **Consistent**. Don't commit to one graphics package. Use the same code and access the strengths of all backends. +- **Lightweight**. Very few dependencies, since backends are loaded and initialized dynamically. -Use the preprocessing pipeline in Plots to fully describe your visualization before it calls the backend code. This maintains modularity and allows for efficient separation of front end code, algorithms, and backend graphics. New graphical backends can be added simply and with minimal required functionality. - -Please add wishlist items, bugs, or any other comments/questions to the issues list. +Use the preprocessing pipeline in Plots to fully describe your visualization before it calls the backend code. This maintains modularity and allows for efficient separation of front end code, algorithms, and backend graphics. New graphical backends can be added with minimal effort. Check out the [summary graphs](img/supported/supported.md) for the features that each backend supports. +Please add wishlist items, bugs, or any other comments/questions to the issues list. + ## Examples for each implemented backend: -- [Qwt.jl](docs/qwt_examples.md) -- [Gadfly.jl](docs/gadfly_examples.md) -- [UnicodePlots.jl](docs/unicodeplots_examples.md) +- [Gadfly.jl/Immerse.jl](docs/gadfly_examples.md) - [PyPlot.jl](docs/pyplot_examples.md) -- [Immerse.jl](docs/immerse_examples.md) +- [UnicodePlots.jl](docs/unicodeplots_examples.md) +- [Qwt.jl](docs/qwt_examples.md) - [Winston.jl](docs/winston_examples.md) ## Installation @@ -44,14 +43,14 @@ Pkg.checkout("Plots") Pkg.checkout("Plots", "dev") ``` -then get any plotting packages you need (obviously, you should get at least one backend): +then get any plotting packages you need (obviously, you should get at least one backend). ```julia Pkg.add("Gadfly") Pkg.add("Immerse") +Pkg.add("PyPlot") Pkg.add("UnicodePlots") -Pkg.add("PyPlot") # requires python and matplotlib -Pkg.clone("https://github.com/tbreloff/Qwt.jl.git") # requires pyqt and pyqwt +Pkg.clone("https://github.com/tbreloff/Qwt.jl.git") Pkg.add("Winston") ``` @@ -59,6 +58,7 @@ Pkg.add("Winston") 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 @@ -202,7 +202,7 @@ yaxis!(args...) = plot!(yaxis = args) annotate!(anns) = plot!(annotation = anns) ``` -Some keyword arguments you can set: +### Keyword arguments: Keyword | Default | Type | Aliases ---- | ---- | ---- | ---- @@ -218,12 +218,11 @@ Keyword | Default | Type | Aliases `:foreground_color` | `auto` | Plot | `:fg`, `:fg_color`, `:fgcolor`, `:foreground` `:grid` | `true` | Plot | `:group` | `nothing` | Series | `:g`, `:groups` -`:guidefont` | `Plots.Font("Helvetica",14,:hcenter,:vcenter,0.0,RGB{U8}(0.0,0.0,0.0))` | Plot | -`:heatmap_c` | `(0.15,0.5)` | Series | `:heatmap_cs` +`:guidefont` | `Plots.Font("Helvetica",11,:hcenter,:vcenter,0.0,RGB{U8}(0.0,0.0,0.0))` | Plot | `:label` | `AUTO` | Series | `:lab`, `:labels` `:layout` | `nothing` | Plot | `:legend` | `true` | Plot | `:leg` -`:legendfont` | `Plots.Font("Helvetica",9,:hcenter,:vcenter,0.0,RGB{U8}(0.0,0.0,0.0))` | Plot | +`:legendfont` | `Plots.Font("Helvetica",8,:hcenter,:vcenter,0.0,RGB{U8}(0.0,0.0,0.0))` | Plot | `:line` | `nothing` | Series | `:l` `:lineopacity` | `nothing` | Series | `:lineopacitys`, `:lo` `:linestyle` | `solid` | Series | `:linestyles`, `:ls`, `:s`, `:style` @@ -244,9 +243,9 @@ Keyword | Default | Type | Aliases `:nr` | `-1` | Plot | `:pos` | `(0,0)` | Plot | `:show` | `false` | Plot | `:display`, `:gui` -`:size` | `(600,400)` | Plot | `:windowsize`, `:wsize` +`:size` | `(500,300)` | Plot | `:windowsize`, `:wsize` `:smooth` | `false` | Series | `:reg`, `:regression`, `:smooths` -`:tickfont` | `Plots.Font("Helvetica",11,:hcenter,:vcenter,0.0,RGB{U8}(0.0,0.0,0.0))` | Plot | +`:tickfont` | `Plots.Font("Helvetica",8,:hcenter,:vcenter,0.0,RGB{U8}(0.0,0.0,0.0))` | Plot | `:title` | `` | Plot | `:windowtitle` | `Plots.jl` | Plot | `:wtitle` `:xaxis` | `nothing` | Plot | @@ -265,7 +264,7 @@ Keyword | Default | Type | Aliases `:z` | `nothing` | Series | `:zs` -Plot types: +### Plot types: Type | Desc | Aliases ---- | ---- | ---- @@ -285,7 +284,7 @@ Type | Desc | Aliases `:ohlc` | Open/High/Low/Close chart (expects y is AbstractVector{Plots.OHLC}) | -Line styles: +### Line styles: Type | Aliases ---- | ---- @@ -297,7 +296,7 @@ Type | Aliases `:dashdotdot` | `:ddd` -Markers: +### Markers: Type | Aliases ---- | ---- @@ -351,19 +350,28 @@ __Tip__: Not all features are supported for each backend, but you can see what's __Tip__: Call `gui()` to display the plot in a window. Interactivity depends on backend. Plotting at the REPL (without semicolon) implicitly calls `gui()`. +### Animations + +Animations are created in 3 steps (see example #2): +- Initialize an `Animation` object. +- Save each frame of the animation with `frame(anim)`. +- Convert the frames to an animated gif with `gif(anim, filename, fps=15)` + + ## TODO features: - [x] Plot vectors/matrices/functions - [x] Plot DataFrames +- [x] Histograms - [x] Grouping - [x] Annotations - [x] Scales - [x] Categorical Inputs (strings, etc... for hist, bar? or can split one series into multiple?) - [x] Custom markers +- [x] Animations +- [x] Subplots - [ ] Contours - [ ] Boxplots -- [x] Subplots -- [x] Histograms - [ ] 3D plotting - [ ] Scenes/Drawing - [ ] Graphs diff --git a/docs/pyplot_examples.md b/docs/pyplot_examples.md index 0926ca0e..e69de29b 100644 --- a/docs/pyplot_examples.md +++ b/docs/pyplot_examples.md @@ -1,235 +0,0 @@ -# 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`, `tickfont`, `guidefont`, `legendfont` -- 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` -- Supported values for marker: `:none`, `:auto`, `:rect`, `:ellipse`, `:diamond`, `:utriangle`, `:dtriangle`, `:cross`, `:xcross`, `:star5`, `:hexagon` -- Is `subplot`/`subplot!` supported? Yes - -### 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, adding data, and animations - -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}. Set, get, and push/append to series data, and easily build animations. - -Note: ImageMagick's `convert` or `ffmpeg` must be runnable from pwd to generate the animation. Use command `gif(anim, filename, fps=15)` to save the animation. - -```julia -p = plot([sin,cos],zeros(0),leg=false) -anim = Animation() -for x = linspace(0,10π,200) # /home/tom/.julia/v0.4/Plots/docs/example_generation.jl, line 43: - push!(p,x,Float64[sin(x),cos(x)]) # /home/tom/.julia/v0.4/Plots/docs/example_generation.jl, line 44: - frame(anim) -end -``` - -![](../img/pyplot/pyplot_example_2.gif) - -### - -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 50: - 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),xaxis=("XLABEL",(-5,30),0:2:20,:flip),background_color=RGB(0.2,0.2,0.2),leg=false) -title!("TITLE") -yaxis!("YLABEL",:log10) -``` - -![](../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,Shape])' -n = length(markers) -x = (linspace(0,10,n + 2))[2:end - 1] -y = repmat(reverse(x)',n,1) -scatter(x,y,m=(12,:auto),lab=map(string,markers),bg=:linen) -``` - -![](../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) - -### 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/pyplot/pyplot_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/pyplot/pyplot_example_17.png) - -### - - - -```julia -subplot!(fakedata(100,10)) -``` - -![](../img/pyplot/pyplot_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],text("this is #3",:left))) -annotate!([(5,y[5],text("this is #5",16,:red,:center)),(10,y[10],text("this is #10",:right,20,"courier"))]) -``` - -![](../img/pyplot/pyplot_example_20.png) - diff --git a/docs/readme_template.md b/docs/readme_template.md index 624c33e1..3e0c3d23 100644 --- a/docs/readme_template.md +++ b/docs/readme_template.md @@ -7,28 +7,26 @@ #### Author: Thomas Breloff (@tbreloff) -Plots is a plotting interface and wrapper for several plotting packages. My goals with the package are: +Plots is a plotting API and toolset. My goals with the package are: -- **Simple**. Intuitive enough that someone coming from Matlab, Python, etc can immediately start generating complex plots without reading volumes of documentation. -- **Concise**. Less code means fewer mistakes and more efficient development and analysis. -- **Smart**. Defaults for the most common functionality, and high-level ways to override complex functionality. +- **Intuitive** Start generating complex plots without reading volumes of documentation. Commands should "just work". +- **Concise**. Less code means fewer mistakes and more efficient development/analysis. - **Flexible**. Produce your favorite plots from your favorite package, but quicker and simpler. - **Consistent**. Don't commit to one graphics package. Use the same code and access the strengths of all backends. -- **Lightweight**. There are very few dependencies. Backends are loaded and initialized dynamically. +- **Lightweight**. Very few dependencies, since backends are loaded and initialized dynamically. -Use the preprocessing pipeline in Plots to fully describe your visualization before it calls the backend code. This maintains modularity and allows for efficient separation of front end code, algorithms, and backend graphics. New graphical backends can be added simply and with minimal required functionality. - -Please add wishlist items, bugs, or any other comments/questions to the issues list. +Use the preprocessing pipeline in Plots to fully describe your visualization before it calls the backend code. This maintains modularity and allows for efficient separation of front end code, algorithms, and backend graphics. New graphical backends can be added with minimal effort. Check out the [summary graphs](img/supported/supported.md) for the features that each backend supports. +Please add wishlist items, bugs, or any other comments/questions to the issues list. + ## Examples for each implemented backend: -- [Qwt.jl](docs/qwt_examples.md) -- [Gadfly.jl](docs/gadfly_examples.md) -- [UnicodePlots.jl](docs/unicodeplots_examples.md) +- [Gadfly.jl/Immerse.jl](docs/gadfly_examples.md) - [PyPlot.jl](docs/pyplot_examples.md) -- [Immerse.jl](docs/immerse_examples.md) +- [UnicodePlots.jl](docs/unicodeplots_examples.md) +- [Qwt.jl](docs/qwt_examples.md) - [Winston.jl](docs/winston_examples.md) ## Installation @@ -45,14 +43,14 @@ Pkg.checkout("Plots") Pkg.checkout("Plots", "dev") ``` -then get any plotting packages you need (obviously, you should get at least one backend): +then get any plotting packages you need (obviously, you should get at least one backend). ```julia Pkg.add("Gadfly") Pkg.add("Immerse") +Pkg.add("PyPlot") Pkg.add("UnicodePlots") -Pkg.add("PyPlot") # requires python and matplotlib -Pkg.clone("https://github.com/tbreloff/Qwt.jl.git") # requires pyqt and pyqwt +Pkg.clone("https://github.com/tbreloff/Qwt.jl.git") Pkg.add("Winston") ``` @@ -60,6 +58,7 @@ Pkg.add("Winston") 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 @@ -203,19 +202,19 @@ yaxis!(args...) = plot!(yaxis = args) annotate!(anns) = plot!(annotation = anns) ``` -Some keyword arguments you can set: +### Keyword arguments: [[KEYWORD_ARGS_TABLE]] -Plot types: +### Plot types: [[LINETYPES_TABLE]] -Line styles: +### Line styles: [[LINESTYLES_TABLE]] -Markers: +### Markers: [[MARKERS_TABLE]] @@ -249,19 +248,28 @@ __Tip__: Not all features are supported for each backend, but you can see what's __Tip__: Call `gui()` to display the plot in a window. Interactivity depends on backend. Plotting at the REPL (without semicolon) implicitly calls `gui()`. +### Animations + +Animations are created in 3 steps (see example #2): +- Initialize an `Animation` object. +- Save each frame of the animation with `frame(anim)`. +- Convert the frames to an animated gif with `gif(anim, filename, fps=15)` + + ## TODO features: - [x] Plot vectors/matrices/functions - [x] Plot DataFrames +- [x] Histograms - [x] Grouping - [x] Annotations - [x] Scales - [x] Categorical Inputs (strings, etc... for hist, bar? or can split one series into multiple?) - [x] Custom markers +- [x] Animations +- [x] Subplots - [ ] Contours - [ ] Boxplots -- [x] Subplots -- [x] Histograms - [ ] 3D plotting - [ ] Scenes/Drawing - [ ] Graphs diff --git a/img/supported/Plots.supportGraphArgs.png b/img/supported/Plots.supportGraphArgs.png index bec3f010..84eb7b43 100644 Binary files a/img/supported/Plots.supportGraphArgs.png and b/img/supported/Plots.supportGraphArgs.png differ diff --git a/img/supported/Plots.supportGraphAxes.png b/img/supported/Plots.supportGraphAxes.png index 7293a960..7e75b853 100644 Binary files a/img/supported/Plots.supportGraphAxes.png and b/img/supported/Plots.supportGraphAxes.png differ diff --git a/img/supported/Plots.supportGraphMarkers.png b/img/supported/Plots.supportGraphMarkers.png index 6e41ef35..d7ea9443 100644 Binary files a/img/supported/Plots.supportGraphMarkers.png and b/img/supported/Plots.supportGraphMarkers.png differ diff --git a/img/supported/Plots.supportGraphScales.png b/img/supported/Plots.supportGraphScales.png index f2348dab..6b9dae08 100644 Binary files a/img/supported/Plots.supportGraphScales.png and b/img/supported/Plots.supportGraphScales.png differ diff --git a/img/supported/Plots.supportGraphStyles.png b/img/supported/Plots.supportGraphStyles.png index 060edd7d..c2549c56 100644 Binary files a/img/supported/Plots.supportGraphStyles.png and b/img/supported/Plots.supportGraphStyles.png differ diff --git a/img/supported/Plots.supportGraphTypes.png b/img/supported/Plots.supportGraphTypes.png index 62e5b8e6..4d2f8b6d 100644 Binary files a/img/supported/Plots.supportGraphTypes.png and b/img/supported/Plots.supportGraphTypes.png differ