From e30889aa122b28610b26df2a483ffe69589ef5fe Mon Sep 17 00:00:00 2001 From: "Samuel S. Watson" Date: Tue, 8 Jan 2019 17:55:52 -0500 Subject: [PATCH 1/6] document @shorthands functions --- src/Plots.jl | 92 +---------------------------------------------- src/arg_desc.jl | 48 ++++++++++++------------- src/components.jl | 20 ++++++++++- src/utils.jl | 37 +++++++++++++++++++ 4 files changed, 81 insertions(+), 116 deletions(-) diff --git a/src/Plots.jl b/src/Plots.jl index 48669c7d..fb93c45f 100644 --- a/src/Plots.jl +++ b/src/Plots.jl @@ -186,97 +186,7 @@ include("backends/plotly.jl") include("backends/gr.jl") include("backends/web.jl") -# --------------------------------------------------------- - -@shorthands scatter -@shorthands bar -@shorthands barh -@shorthands histogram -@shorthands barhist -@shorthands stephist -@shorthands scatterhist -@shorthands histogram2d -@shorthands density -@shorthands heatmap -@shorthands plots_heatmap -@shorthands hexbin -@shorthands sticks -@shorthands hline -@shorthands vline -@shorthands hspan -@shorthands vspan -@shorthands ohlc -@shorthands contour -@shorthands contourf -@shorthands contour3d -@shorthands surface -@shorthands wireframe -@shorthands path3d -@shorthands scatter3d -@shorthands boxplot -@shorthands violin -@shorthands quiver -@shorthands curves - -"Plot a pie diagram" -pie(args...; kw...) = plot(args...; kw..., seriestype = :pie, aspect_ratio = :equal, grid=false, xticks=nothing, yticks=nothing) -pie!(args...; kw...) = plot!(args...; kw..., seriestype = :pie, aspect_ratio = :equal, grid=false, xticks=nothing, yticks=nothing) - -"Plot with seriestype :path3d" -plot3d(args...; kw...) = plot(args...; kw..., seriestype = :path3d) -plot3d!(args...; kw...) = plot!(args...; kw..., seriestype = :path3d) - -"Add title to an existing plot" -title!(s::AbstractString; kw...) = plot!(; title = s, kw...) - -"Add xlabel to an existing plot" -xlabel!(s::AbstractString; kw...) = plot!(; xlabel = s, kw...) - -"Add ylabel to an existing plot" -ylabel!(s::AbstractString; kw...) = plot!(; ylabel = s, kw...) - -"Set xlims for an existing plot" -xlims!(lims::Tuple{T,S}; kw...) where {T<:Real,S<:Real} = plot!(; xlims = lims, kw...) - -"Set ylims for an existing plot" -ylims!(lims::Tuple{T,S}; kw...) where {T<:Real,S<:Real} = plot!(; ylims = lims, kw...) - -"Set zlims for an existing plot" -zlims!(lims::Tuple{T,S}; kw...) where {T<:Real,S<:Real} = plot!(; zlims = lims, kw...) - -xlims!(xmin::Real, xmax::Real; kw...) = plot!(; xlims = (xmin,xmax), kw...) -ylims!(ymin::Real, ymax::Real; kw...) = plot!(; ylims = (ymin,ymax), kw...) -zlims!(zmin::Real, zmax::Real; kw...) = plot!(; zlims = (zmin,zmax), kw...) - - -"Set xticks for an existing plot" -xticks!(v::TicksArgs; kw...) where {T<:Real} = plot!(; xticks = v, kw...) - -"Set yticks for an existing plot" -yticks!(v::TicksArgs; kw...) where {T<:Real} = plot!(; yticks = v, kw...) - -xticks!( -ticks::AVec{T}, labels::AVec{S}; kw...) where {T<:Real,S<:AbstractString} = plot!(; xticks = (ticks,labels), kw...) -yticks!( -ticks::AVec{T}, labels::AVec{S}; kw...) where {T<:Real,S<:AbstractString} = plot!(; yticks = (ticks,labels), kw...) - -"Add annotations to an existing plot" -annotate!(anns...; kw...) = plot!(; annotation = anns, kw...) -annotate!(anns::AVec{T}; kw...) where {T<:Tuple} = plot!(; annotation = anns, kw...) - -"Flip the current plots' x axis" -xflip!(flip::Bool = true; kw...) = plot!(; xflip = flip, kw...) - -"Flip the current plots' y axis" -yflip!(flip::Bool = true; kw...) = plot!(; yflip = flip, kw...) - -"Specify x axis attributes for an existing plot" -xaxis!(args...; kw...) = plot!(; xaxis = args, kw...) - -"Specify x axis attributes for an existing plot" -yaxis!(args...; kw...) = plot!(; yaxis = args, kw...) -xgrid!(args...; kw...) = plot!(; xgrid = args, kw...) -ygrid!(args...; kw...) = plot!(; ygrid = args, kw...) +include("shorthands.jl") let PlotOrSubplot = Union{Plot, Subplot} global title!(plt::PlotOrSubplot, s::AbstractString; kw...) = plot!(plt; title = s, kw...) diff --git a/src/arg_desc.jl b/src/arg_desc.jl index 64ce5b93..6fe8f068 100644 --- a/src/arg_desc.jl +++ b/src/arg_desc.jl @@ -2,7 +2,7 @@ const _arg_desc = KW( # series args -:label => "String type. The label for a series, which appears in a legend. If empty, no legend entry is added.", +:label => "String type. The label for a series, which appears in a legend. If empty, no legend entry is added.", :seriescolor => "Color Type. The base color for this series. `:auto` (the default) will select a color from the subplot's `color_palette`, based on the order it was added to the subplot", :seriesalpha => "Number in [0,1]. The alpha/opacity override for the series. `nothing` (the default) means it will take the alpha value of the color.", :seriestype => "Symbol. This is the identifier of the type of visualization for this series. Choose from $(_allTypes) or any series recipes which are defined.", @@ -10,7 +10,7 @@ const _arg_desc = KW( :linewidth => "Number. Width of the line (in pixels)", :linecolor => "Color Type. Color of the line (for path and bar stroke). `:match` will take the value from `:seriescolor`, (though histogram/bar types use `:black` as a default).", :linealpha => "Number in [0,1]. The alpha/opacity override for the line. `nothing` (the default) means it will take the alpha value of linecolor.", -:fillrange => "Number or AbstractVector. Fills area from this to y for line-types, sets the base for bar/stick types, and similar for other types.", +:fillrange => "Number or AbstractVector. Fills area between fillrange and y for line-types, sets the base for bar/stick types, and similar for other types.", :fillcolor => "Color Type. Color of the filled area of path or bar types. `:match` will take the value from `:seriescolor`.", :fillalpha => "Number in [0,1]. The alpha/opacity override for the fill area. `nothing` (the default) means it will take the alpha value of fillcolor.", :markershape => "Symbol, Shape, or AbstractVector. Choose from $(_allMarkers).", @@ -21,7 +21,7 @@ const _arg_desc = KW( :markerstrokewidth => "Number. Width of the marker stroke (border. in pixels)", :markerstrokecolor => "Color Type. Color of the marker stroke (border). `:match` will take the value from `:foreground_color_subplot`.", :markerstrokealpha => "Number in [0,1]. The alpha/opacity override for the marker stroke (border). `nothing` (the default) means it will take the alpha value of markerstrokecolor.", -:bins => "Integer, NTuple{2,Integer}, AbstractVector or Symbol. Default is :auto (the Freedman-Diaconis rule). For histogram-types, defines the approximate number of bins to aim for, or the auto-binning algorithm to use (:sturges, :sqrt, :rice, :scott or :fd). For fine-grained control pass a Vector of break values, e.g. `range(min(x), stop = extrema(x), length = 25)`", +:bins => "Integer, NTuple{2,Integer}, AbstractVector or Symbol. Default is :auto (the Freedman-Diaconis rule). For histogram-types, defines the approximate number of bins to aim for, or the auto-binning algorithm to use (:sturges, :sqrt, :rice, :scott or :fd). For fine-grained control pass a Vector of break values, e.g. `range(minimum(x), stop = maximum(x), length = 25)`", :smooth => "Bool. Add a regression line?", :group => "AbstractVector. Data is split into a separate series, one for each unique value in `group`.", :x => "Various. Input data. First Dimension", @@ -29,13 +29,13 @@ const _arg_desc = KW( :z => "Various. Input data. Third Dimension. May be wrapped by a `Surface` for surface and heatmap types.", :marker_z => "AbstractVector, Function `f(x,y,z) -> z_value`, or Function `f(x,y) -> z_value`, or nothing. z-values for each series data point, which correspond to the color to be used from a markercolor gradient.", :line_z => "AbstractVector, Function `f(x,y,z) -> z_value`, or Function `f(x,y) -> z_value`, or nothing. z-values for each series line segment, which correspond to the color to be used from a linecolor gradient. Note that for N points, only the first N-1 values are used (one per line-segment).", -:fill_z => "Matrix{Float64} of the same size as z matrix, which specifies the color of the 3D surface; the default value is `nothing`.", -:levels => "Integer, NTuple{2,Integer}. Number of levels (or x-levels/y-levels) for a contour type.", +:fill_z => "Matrix{Float64} of the same size as z matrix, which specifies the color of the 3D surface; the default value is `nothing`.", +:levels => "Integer, NTuple{2,Integer}, or AbstractVector. Levels or number of levels (or x-levels/y-levels) for a contour type.", :orientation => "Symbol. Horizontal or vertical orientation for bar types. Values `:h`, `:hor`, `:horizontal` correspond to horizontal (sideways, anchored to y-axis), and `:v`, `:vert`, and `:vertical` correspond to vertical (the default).", :bar_position => "Symbol. Choose from `:overlay` (default), `:stack`. (warning: May not be implemented fully)", -:bar_width => "nothing or Number. Width of bars in data coordinates. When nothing, chooses based on x (or y when `orientation = :h`).", -:bar_edges => "Bool. Align bars to edges (true), or centers (the default)?", -:xerror => "AbstractVector or 2-Tuple of Vectors. x (horizontal) error relative to x-value. If 2-tuple of vectors, the first vector corresponds to the left error (and the second to the right)", +:bar_width => "nothing or Number. Width of bars in data coordinates. When nothing, chooses based on x (or y when `orientation = :h`).", +:bar_edges => "Bool. Align bars to edges (true), or centers (the default)?", +:xerror => "AbstractVector or 2-Tuple of Vectors. x (horizontal) error relative to x-value. If 2-tuple of vectors, the first vector corresponds to the left error (and the second to the right)", :yerror => "AbstractVector or 2-Tuple of Vectors. y (vertical) error relative to y-value. If 2-tuple of vectors, the first vector corresponds to the bottom error (and the second to the top)", :ribbon => "Number or AbstractVector. Creates a fillrange around the data points.", :quiver => "AbstractVector or 2-Tuple of vectors. The directional vectors U,V which specify velocity/gradient vectors for a quiver plot.", @@ -43,12 +43,12 @@ const _arg_desc = KW( :normalize => "Bool or Symbol. Histogram normalization mode. Possible values are: false/:none (no normalization, default), true/:pdf (normalize to a discrete Probability Density Function, where the total area of the bins is 1), :probability (bin heights sum to 1) and :density (the area of each bin, rather than the height, is equal to the counts - useful for uneven bin sizes).", :weights => "AbstractVector. Used in histogram types for weighted counts.", :contours => "Bool. Add contours to the side-grids of 3D plots? Used in surface/wireframe.", -:contour_labels => "Bool. Show labels at the contour lines?", +:contour_labels => "Bool. Show labels at the contour lines?", :match_dimensions => "Bool. For heatmap types... should the first dimension of a matrix (rows) correspond to the first dimension of the plot (x-axis)? The default is false, which matches the behavior of Matplotlib, Plotly, and others. Note: when passing a function for z, the function should still map `(x,y) -> z`.", :subplot => "Integer (subplot index) or Subplot object. The subplot that this series belongs to.", -:series_annotations => "AbstractVector of String or PlotText. These are annotations which are mapped to data points/positions.", -:primary => "Bool. Does this count as a 'real series'? For example, you could have a path (primary), and a scatter (secondary) as 2 separate series, maybe with different data (see sticks recipe for an example). The secondary series will get the same color, etc as the primary.", -:hover => "nothing or vector of strings. Text to display when hovering over each data point.", +:series_annotations => "AbstractVector of String or PlotText. These are annotations which are mapped to data points/positions.", +:primary => "Bool. Does this count as a 'real series'? For example, you could have a path (primary), and a scatter (secondary) as 2 separate series, maybe with different data (see sticks recipe for an example). The secondary series will get the same color, etc as the primary.", +:hover => "nothing or vector of strings. Text to display when hovering over each data point.", # plot args :plot_title => "String. Title for the whole plot (not the subplots) (Note: Not currently implemented)", @@ -63,11 +63,11 @@ const _arg_desc = KW( :link => "Symbol. How/whether to link axis limits between subplots. Values: `:none`, `:x` (x axes are linked by columns), `:y` (y axes are linked by rows), `:both` (x and y are linked), `:all` (every subplot is linked together regardless of layout position).", :overwrite_figure => "Bool. Should we reuse the same GUI window/figure when plotting (true) or open a new one (false).", :html_output_format => "Symbol. When writing html output, what is the format? `:png` and `:svg` are currently supported.", -:inset_subplots => "nothing or vector of 2-tuple (parent,bbox). optionally pass a vector of (parent,bbox) tuples which are the parent layout and the relative bounding box of inset subplots", -:dpi => "Number. Dots Per Inch of output figures", +:inset_subplots => "nothing or vector of 2-tuple (parent,bbox). optionally pass a vector of (parent,bbox) tuples which are the parent layout and the relative bounding box of inset subplots", +:dpi => "Number. Dots Per Inch of output figures", :thickness_scaling => "Number. Scale for the thickness of all line elements like lines, borders, axes, grid lines, ... defaults to 1.", -:display_type => "Symbol (`:auto`, `:gui`, or `:inline`). When supported, `display` will either open a GUI window or plot inline.", -:extra_kwargs => "KW (Dict{Symbol,Any}). Pass a map of extra keyword args which may be specific to a backend.", +:display_type => "Symbol (`:auto`, `:gui`, or `:inline`). When supported, `display` will either open a GUI window or plot inline.", +:extra_kwargs => "KW (Dict{Symbol,Any}). Pass a map of extra keyword args which may be specific to a backend.", :fontfamily => "String or Symbol. Default font family for title, legend entries, tick labels and guides", # subplot args @@ -98,7 +98,7 @@ const _arg_desc = KW( :legendfont => "Font. Font of legend items.", :annotations => "(x,y,text) tuple(s). Can be a single tuple or a list of them. Text can be String or PlotText (created with `text(args...)`) Add one-off text annotations at the x,y coordinates.", :projection => "Symbol or String. '3d' or 'polar'", -:aspect_ratio => "Symbol (:equal) or Number. Plot area is resized so that 1 y-unit is the same size as `apect_ratio` x-units.", +:aspect_ratio => "Symbol (:equal) or Number. Plot area is resized so that 1 y-unit is the same size as `aspect_ratio` x-units.", :margin => "Measure (multiply by `mm`, `px`, etc). Base for individual margins... not directly used. Specifies the extra padding around subplots.", :left_margin => "Measure (multiply by `mm`, `px`, etc) or `:match` (matches `:margin`). Specifies the extra padding to the left of the subplot.", :top_margin => "Measure (multiply by `mm`, `px`, etc) or `:match` (matches `:margin`). Specifies the extra padding on the top of the subplot.", @@ -110,14 +110,14 @@ const _arg_desc = KW( :camera => "NTuple{2, Real}. Sets the view angle (azimuthal, elevation) for 3D plots", # axis args -:guide => "String. Axis guide (label).", +:guide => "String. Axis guide (label).", :guide_position => "Symbol. Position of axis guides: :top, :bottom, :left or :right", -:lims => "NTuple{2,Number} or Symbol. Force axis limits. Only finite values are used (you can set only the right limit with `xlims = (-Inf, 2)` for example). `:round` widens the limit to the nearest round number ie. [0.1,3.6]=>[0.0,4.0]", -:ticks => "Vector of numbers (set the tick values), Tuple of (tickvalues, ticklabels), or `:auto`", -:scale => "Symbol. Scale of the axis: `:none`, `:ln`, `:log2`, `:log10`", -:rotation => "Number. Degrees rotation of tick labels.", -:flip => "Bool. Should we flip (reverse) the axis?", -:formatter => "Function, :scientific, :plain or :auto. A method which converts a number to a string for tick labeling.", +:lims => "NTuple{2,Number} or Symbol. Force axis limits. Only finite values are used (you can set only the right limit with `xlims = (-Inf, 2)` for example). `:round` widens the limit to the nearest round number ie. [0.1,3.6]=>[0.0,4.0]", +:ticks => "Vector of numbers (set the tick values), Tuple of (tickvalues, ticklabels), or `:auto`", +:scale => "Symbol. Scale of the axis: `:none`, `:ln`, `:log2`, `:log10`", +:rotation => "Number. Degrees rotation of tick labels.", +:flip => "Bool. Should we flip (reverse) the axis?", +:formatter => "Function, :scientific, :plain or :auto. A method which converts a number to a string for tick labeling.", :tickfontfamily => "String or Symbol. Font family of tick labels.", :tickfontsize => "Integer. Font pointsize of tick labels.", :tickfonthalign => "Symbol. Font horizontal alignment of tick labels: :hcenter, :left, :right or :center", diff --git a/src/components.jl b/src/components.jl index f1f27dc4..f338432c 100644 --- a/src/components.jl +++ b/src/components.jl @@ -256,7 +256,25 @@ mutable struct Font color::Colorant end -"Create a Font from a list of unordered features" +""" + font(args...) + +Create a Font from an unordered list of features. + +# Arguments + +- `family`: AbstractString. "serif" or "sans-serif" or "monospace" +- `pointsize`: Integer. Size of font in points +- `halign`: Symbol. Horizontal alignment (:hcenter, :left, or :right) +- `valign`: Symbol. Vertical aligment (:vcenter, :top, or :bottom) +- `rotation`: Real. Angle of rotation for text in degrees (use a non-integer type) +- `color`: Colorant or Symbol + +# Examples +```julia-repl +julia> text("sans-serif",8,:hcenter,45.0,:blue) +``` +""" function font(args...) # defaults diff --git a/src/utils.jl b/src/utils.jl index e0d26c81..a0bad5a8 100644 --- a/src/utils.jl +++ b/src/utils.jl @@ -1199,3 +1199,40 @@ end function construct_categorical_data(x::AbstractArray, axis::Axis) map(xi -> axis[:discrete_values][searchsortedfirst(axis[:continuous_values], xi)], x) end + +_fmt_paragraph(paragraph::AbstractString;kwargs...) = _fmt_paragraph(IOBuffer(),paragraph,0;kwargs...) + +function _fmt_paragraph(io::IOBuffer, + remaining_text::AbstractString, + column_count::Integer; + fillwidth=60, + leadingspaces=0) + + kwargs = (fillwidth = fillwidth, leadingspaces = leadingspaces) + + m = match(r"(.*?) (.*)",remaining_text) + if isa(m,Nothing) + if column_count + length(remaining_text) ≤ fillwidth + print(io,remaining_text) + String(take!(io)) + else + print(io,"\n"*" "^leadingspaces*remaining_text) + String(take!(io)) + end + else + if column_count + length(m[1]) ≤ fillwidth + print(io,"$(m[1]) ") + _fmt_paragraph(io,m[2],column_count + length(m[1]) + 1;kwargs...) + else + print(io,"\n"*" "^leadingspaces*"$(m[1]) ") + _fmt_paragraph(io,m[2],leadingspaces;kwargs...) + end + end +end + +function _document_argument(S::AbstractString) + _fmt_paragraph("`$S`: "*_arg_desc[Symbol(S)],leadingspaces = 6 + length(S)) +end + + + From 63cdf9f8e71fb831d953232990e7d96e9fb94d1d Mon Sep 17 00:00:00 2001 From: "Samuel S. Watson" Date: Tue, 8 Jan 2019 18:10:48 -0500 Subject: [PATCH 2/6] Add shorthands.jl --- src/shorthands.jl | 489 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 489 insertions(+) create mode 100644 src/shorthands.jl diff --git a/src/shorthands.jl b/src/shorthands.jl new file mode 100644 index 00000000..dc4af52d --- /dev/null +++ b/src/shorthands.jl @@ -0,0 +1,489 @@ +xydoc = """ +- `x`: AbstractVector of x values. +- `y`: AbstractVector of y values. +""" + +xyzdoc = """ +- `x`: x-coordinates. Either a vector of length `size(z,1)` or a rectangular + array with the same dimensions as `z`. `1:size(z,1)` by default. +- `y`: y-coordinates. Either a vector of length `size(z,2)` or a rectangular + array with the same dimensions as `z`. `1:size(z,2)` by default. +- `z`: Rectangular array of height values for the contour lines, or a function to + apply to `x` and `y` to obtain such an array. +""" + +""" + scatter(x,y) + scatter!(x,y) + +Make a scatter plot of y vs x. + +# Arguments +$xydoc + +# Examples +```julia-repl +julia> scatter([1,2,3],[4,5,6],markersize=[3,4,5],markercolor=[:red,:green,:blue]) +julia> scatter([(1,4),(2,5),(3,6)]) +``` +""" +@shorthands scatter + +""" + bar(x,y) + bar!(x,y) + +Make a bar plot of y vs x. + +# Arguments + +$xydoc +- $(_document_argument("bar_position")) +- $(_document_argument("bar_width")) +- $(_document_argument("bar_edges")) +- $(_document_argument("orientation")) + +# Examples +```julia-repl +julia> bar([1,2,3],[4,5,6],fillcolor=[:red,:green,:blue],fillalpha=[0.2,0.4,0.6]) +julia> bar([(1,4),(2,5),(3,6)]) +``` +""" +@shorthands bar + +@shorthands barh + +""" + histogram(x) + histogram!(x) + +Plot a histogram. + +# Arguments + +- `x`: AbstractVector of values to be binned +- $(_document_argument("bins")) +- `weights`: Vector of weights for the values in `x`, for weighted bin counts +- $(_document_argument("normalize")) +- $(_document_argument("bar_position")) +- $(_document_argument("bar_width")) +- $(_document_argument("bar_edges")) +- $(_document_argument("orientation")) + +# Example +```julia-repl +julia> histogram([1,2,1,1,4,3,8],bins=0:8) +``` +""" +@shorthands histogram + +""" + barhist(x) + barhist!(x) + +Make a histogram bar plot. See `histogram`. +""" +@shorthands barhist + +""" + stephist(x) + stephist(x) + +Make a histogram step plot (bin counts are represented using horizontal lines +instead of bars). See `histogram`. +""" +@shorthands stephist + +""" + scatterhist(x) + scatterhist!(x) + +Make a histogram scatter plot (bin counts are represented using points +instead of bars). See `histogram`. +""" +@shorthands scatterhist + +""" + histogram2d(x,y) + histogram2d!(x,y) + +Plot a two-dimensional histogram. + +# Arguments + +$xydoc +- `bins`: Number of bins (if an `Integer`) or bin edges (if an `AbtractVector`) +- `weights`: Vector of weights for the values in `x`. Each entry of x contributes + its weight to the height of its bin. + +# Example +```julia-repl +julia> histogram2d(randn(10_000),randn(10_000)) +``` +""" +@shorthands histogram2d + +""" + density(x) + density!(x) + +Make a line plot of a kernel density estimate of x + +# Arguments + +- `x`: AbstractVector of samples for probability density estimation + +# Example +```julia-repl +julia> using StatPlots +julia> density(randn(100_000)) +``` +""" +@shorthands density + +""" + heatmap(x,y,z) + heatmap!(x,y,z) + +Plot a heatmap of the rectangular array `z` + +# Arguments +$xyzdoc + + +# Example +```julia-repl +julia> heatmap(randn(10,10)) +``` +""" +@shorthands heatmap +@shorthands plots_heatmap + +""" + hexbin(x,y) + hexbin!(x,y) + +Make a hexagonal binning plot (a histogram of the observations `(x[i],y[i])` +with hexagonal bins) + +# Example +```julia-repl +julia> hexbin(randn(10_000), randn(10_000)) +``` +""" +@shorthands hexbin + +""" + sticks(x,y) + sticks!(x,y) + +Draw a stick plot of y vs x. + +# Arguments +$xydoc + +# Example +```julia-repl +julia> sticks(1:10) +``` +""" +@shorthands sticks + +""" + hline(y) + hline!(y) + +Draw horizontal lines at positions specified by the values in +the AbstractVector `y` + +# Example +```julia-repl +julia> hline([-1,0,2]) +``` +""" +@shorthands hline + +""" + vline(x) + vline!(x) + +Draw vertical lines at positions specified by the values in +the AbstractVector `x` + +# Example +```julia-repl +julia> vline([-1,0,2]) +``` +""" +@shorthands vline + +""" + hspan(y) + +Draw a rectangle between the horizontal line at position `y[1]` +and the horizontal line at position `y[2]`. If `length(y) ≥ 4`, +then further rectangles are drawn between `y[3]` and `y[4]`, +`y[5]` and `y[6]`, and so on. If `length(y)` is odd, then the +last entry of `y` is ignored. +# Example +```julia-repl +julia> hspan(1:6) +``` +""" +@shorthands hspan + +""" + vspan(x) + +Draw a rectangle between the vertical line at position `x[1]` +and the vertical line at position `x[2]`. If `length(x) ≥ 4`, +then further rectangles are drawn between `x[3]` and `x[4]`, +`x[5]` and `x[6]`, and so on. If `length(x)` is odd, then the +last entry of `x` is ignored. +# Example +```julia-repl +julia> vspan(1:6) +``` +""" +@shorthands vspan + +""" + ohlc(x,y::Vector{OHLC}) + ohlc!(x,y::Vector{OHLC}) + +Make open-high-low-close plot. Each entry of y is represented by a vertical +segment extending from the low value to the high value, with short horizontal +segments on the left and right indicating the open and close values, respectively. + +# Example +```julia-repl +julia> meanprices = cumsum(randn(100)) +julia> y = OHLC[(p+rand(),p+1,p-1,p+rand()) for p in meanprices] +julia> ohlc(y) +``` +""" +@shorthands ohlc + + +""" + contour(x,y,z) + contour!(x,y,z) + +Draw contour lines of the `Surface` z. + +# Arguments +$xyzdoc +- `levels`: Contour levels (if `AbstractVector`) or number of levels (if `Integer`) +- `fill`: Bool. Fill area between contours or draw contours only (false by default) + +# Example +```julia-repl +julia> contour(-20:20,-20:20,(x,y)->x^2+y^2) +``` +""" +@shorthands contour + +"An alias for `contour` with fill = true." +@shorthands contourf + + +@shorthands contour3d + +""" + surface(x,y,z) + surface!(x,y,z) + +Draw a 3D surface plot. + +# Arguments +$xyzdoc + +# Example +```julia-repl +julia> surface(1:10,1:10,randn(10,10)) +``` +""" +@shorthands surface + +""" + wireframe(x,y,z) + wireframe!(x,y,z) + +Draw a 3D wireframe plot. + +# Arguments +$xyzdoc + +# Example +```julia-repl +julia> wireframe(1:10,1:10,randn(10,10)) +``` +""" +@shorthands wireframe + +""" + path3d(x,y,z) + path3d!(x,y,z) + +Plot a 3D path from `(x[1],y[1],z[1])` to `(x[2],y[2],z[2])`, +..., to `(x[end],y[end],z[end])`. + +# Example +```julia-repl +julia> path3d([0,1,2,3],[0,1,4,9],[0,1,8,27]) +``` +""" +@shorthands path3d + +""" + scatter3d(x,y,z) + scatter3d!(x,y,z) + +Make a 3D scatter plot. + +# Example +```julia-repl +julia> scatter3d([0,1,2,3],[0,1,4,9],[0,1,8,27]) +``` +""" +@shorthands scatter3d + +""" + boxplot(x, y) + boxplot!(x, y) + +Make a box and whisker plot. + +# Arguments +$xydoc + +# Keyword arguments +- `notch`: Bool. Notch the box plot? (false) +- `range`: Real. Values more than range*IQR below the first quartile + or above the third quartile are shown as outliers (1.5) +- `outliers`: Bool. Show outliers? (true) +- `whisker_width`: Real or Symbol. Length of whiskers (:match) + +# Example +```julia-repl +julia> using StatPlots +julia> boxplot(repeat([1,2,3],outer=100),randn(300)) +``` +""" +@shorthands boxplot + +""" + violin(x,y,z) + violin!(x,y,z) + +Make a violin plot. + +# Example +```julia-repl +julia> violin(repeat([1,2,3],outer=100),randn(300)) +``` +""" +@shorthands violin + +""" + quiver(x,y,quiver=(u,v)) + quiver!(x,y,quiver=(u,v)) + +Make a quiver (vector field) plot. The `i`th vector extends +from `(x[i],y[i])` to `(x[i] + u[i], y[i] + v[i])`. + +# Example +```julia-repl +julia> quiver([1,2,3],[3,2,1],quiver=([1,1,1],[1,2,3])) +``` +""" +@shorthands quiver + +""" + curves(x,y) + curves!(x,y) + +Draw a Bezier curve from `(x[1],y[1])` to `(x[end],y[end])` +with control points `(x[2],y[2]), ..., (x[end-1],y[end]-1)` + +# Example +```julia-repl +julia> curves([1,2,3,4],[1,1,2,4]) +``` +""" +@shorthands curves + +"Plot a pie diagram" +pie(args...; kw...) = plot(args...; kw..., seriestype = :pie, aspect_ratio = :equal, grid=false, xticks=nothing, yticks=nothing) +pie!(args...; kw...) = plot!(args...; kw..., seriestype = :pie, aspect_ratio = :equal, grid=false, xticks=nothing, yticks=nothing) + +"Plot with seriestype :path3d" +plot3d(args...; kw...) = plot(args...; kw..., seriestype = :path3d) +plot3d!(args...; kw...) = plot!(args...; kw..., seriestype = :path3d) + +"Add title to an existing plot" +title!(s::AbstractString; kw...) = plot!(; title = s, kw...) + +"Add xlabel to an existing plot" +xlabel!(s::AbstractString; kw...) = plot!(; xlabel = s, kw...) + +"Add ylabel to an existing plot" +ylabel!(s::AbstractString; kw...) = plot!(; ylabel = s, kw...) + +"Set xlims for an existing plot" +xlims!(lims::Tuple{T,S}; kw...) where {T<:Real,S<:Real} = plot!(; xlims = lims, kw...) + +"Set ylims for an existing plot" +ylims!(lims::Tuple{T,S}; kw...) where {T<:Real,S<:Real} = plot!(; ylims = lims, kw...) + +"Set zlims for an existing plot" +zlims!(lims::Tuple{T,S}; kw...) where {T<:Real,S<:Real} = plot!(; zlims = lims, kw...) + +xlims!(xmin::Real, xmax::Real; kw...) = plot!(; xlims = (xmin,xmax), kw...) +ylims!(ymin::Real, ymax::Real; kw...) = plot!(; ylims = (ymin,ymax), kw...) +zlims!(zmin::Real, zmax::Real; kw...) = plot!(; zlims = (zmin,zmax), kw...) + + +"Set xticks for an existing plot" +xticks!(v::TicksArgs; kw...) where {T<:Real} = plot!(; xticks = v, kw...) + +"Set yticks for an existing plot" +yticks!(v::TicksArgs; kw...) where {T<:Real} = plot!(; yticks = v, kw...) + +xticks!( +ticks::AVec{T}, labels::AVec{S}; kw...) where {T<:Real,S<:AbstractString} = plot!(; xticks = (ticks,labels), kw...) +yticks!( +ticks::AVec{T}, labels::AVec{S}; kw...) where {T<:Real,S<:AbstractString} = plot!(; yticks = (ticks,labels), kw...) + +""" + annotate!(anns...) + +Add annotations to an existing plot. + +# Arguments + +- `anns`: An `AbstractVector` of tuples of the form (x,y,text). The text object + can be an String or PlotText + +# Example +```julia-repl +julia> plot(1:10) +julia> annotate!([(7,3,"(7,3)"),(3,7,text("hey", 14, :left, :top, :green))]) +``` +""" +annotate!(anns...; kw...) = plot!(; annotation = anns, kw...) +annotate!(anns::AVec{T}; kw...) where {T<:Tuple} = plot!(; annotation = anns, kw...) + +"Flip the current plots' x axis" +xflip!(flip::Bool = true; kw...) = plot!(; xflip = flip, kw...) + +"Flip the current plots' y axis" +yflip!(flip::Bool = true; kw...) = plot!(; yflip = flip, kw...) + +"Specify x axis attributes for an existing plot" +xaxis!(args...; kw...) = plot!(; xaxis = args, kw...) + +"Specify x axis attributes for an existing plot" +yaxis!(args...; kw...) = plot!(; yaxis = args, kw...) +xgrid!(args...; kw...) = plot!(; xgrid = args, kw...) +ygrid!(args...; kw...) = plot!(; ygrid = args, kw...) From dd28159564e788bd171905646acb35ab975e160c Mon Sep 17 00:00:00 2001 From: Iblis Lin Date: Thu, 10 Jan 2019 08:44:41 -0500 Subject: [PATCH 3/6] remove rand from example Co-Authored-By: sswatson --- src/shorthands.jl | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/shorthands.jl b/src/shorthands.jl index dc4af52d..7b216696 100644 --- a/src/shorthands.jl +++ b/src/shorthands.jl @@ -300,7 +300,8 @@ $xyzdoc # Example ```julia-repl -julia> surface(1:10,1:10,randn(10,10)) +julia> x = y = range(-3, 3, length = 100) +julia> surface(x, y, (x, y) -> sinc(norm([x, y]))) ``` """ @shorthands surface From 3765d5f549e0d694c798df166449479cc9400543 Mon Sep 17 00:00:00 2001 From: Iblis Lin Date: Thu, 10 Jan 2019 08:46:38 -0500 Subject: [PATCH 4/6] change contour example Co-Authored-By: sswatson --- src/shorthands.jl | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/src/shorthands.jl b/src/shorthands.jl index 7b216696..cb244bcd 100644 --- a/src/shorthands.jl +++ b/src/shorthands.jl @@ -278,7 +278,8 @@ $xyzdoc # Example ```julia-repl -julia> contour(-20:20,-20:20,(x,y)->x^2+y^2) +julia> x = y = range(-20, 20, length = 100) +julia> contour(x, y, (x, y) -> x^2 + y^2) ``` """ @shorthands contour From 017bed1a07b98ede2afc97164fd25e382972f3ed Mon Sep 17 00:00:00 2001 From: "Samuel S. Watson" Date: Wed, 16 Jan 2019 08:40:25 -0500 Subject: [PATCH 5/6] Remove xydoc and xyzdoc --- src/shorthands.jl | 40 ++-------------------------------------- 1 file changed, 2 insertions(+), 38 deletions(-) diff --git a/src/shorthands.jl b/src/shorthands.jl index cb244bcd..7c5d7003 100644 --- a/src/shorthands.jl +++ b/src/shorthands.jl @@ -1,26 +1,9 @@ -xydoc = """ -- `x`: AbstractVector of x values. -- `y`: AbstractVector of y values. -""" - -xyzdoc = """ -- `x`: x-coordinates. Either a vector of length `size(z,1)` or a rectangular - array with the same dimensions as `z`. `1:size(z,1)` by default. -- `y`: y-coordinates. Either a vector of length `size(z,2)` or a rectangular - array with the same dimensions as `z`. `1:size(z,2)` by default. -- `z`: Rectangular array of height values for the contour lines, or a function to - apply to `x` and `y` to obtain such an array. -""" - """ scatter(x,y) scatter!(x,y) Make a scatter plot of y vs x. -# Arguments -$xydoc - # Examples ```julia-repl julia> scatter([1,2,3],[4,5,6],markersize=[3,4,5],markercolor=[:red,:green,:blue]) @@ -37,7 +20,6 @@ Make a bar plot of y vs x. # Arguments -$xydoc - $(_document_argument("bar_position")) - $(_document_argument("bar_width")) - $(_document_argument("bar_edges")) @@ -111,7 +93,6 @@ Plot a two-dimensional histogram. # Arguments -$xydoc - `bins`: Number of bins (if an `Integer`) or bin edges (if an `AbtractVector`) - `weights`: Vector of weights for the values in `x`. Each entry of x contributes its weight to the height of its bin. @@ -127,7 +108,7 @@ julia> histogram2d(randn(10_000),randn(10_000)) density(x) density!(x) -Make a line plot of a kernel density estimate of x +Make a line plot of a kernel density estimate of x. # Arguments @@ -145,11 +126,7 @@ julia> density(randn(100_000)) heatmap(x,y,z) heatmap!(x,y,z) -Plot a heatmap of the rectangular array `z` - -# Arguments -$xyzdoc - +Plot a heatmap of the rectangular array `z`. # Example ```julia-repl @@ -179,9 +156,6 @@ julia> hexbin(randn(10_000), randn(10_000)) Draw a stick plot of y vs x. -# Arguments -$xydoc - # Example ```julia-repl julia> sticks(1:10) @@ -272,7 +246,6 @@ julia> ohlc(y) Draw contour lines of the `Surface` z. # Arguments -$xyzdoc - `levels`: Contour levels (if `AbstractVector`) or number of levels (if `Integer`) - `fill`: Bool. Fill area between contours or draw contours only (false by default) @@ -296,9 +269,6 @@ julia> contour(x, y, (x, y) -> x^2 + y^2) Draw a 3D surface plot. -# Arguments -$xyzdoc - # Example ```julia-repl julia> x = y = range(-3, 3, length = 100) @@ -313,9 +283,6 @@ julia> surface(x, y, (x, y) -> sinc(norm([x, y]))) Draw a 3D wireframe plot. -# Arguments -$xyzdoc - # Example ```julia-repl julia> wireframe(1:10,1:10,randn(10,10)) @@ -356,9 +323,6 @@ julia> scatter3d([0,1,2,3],[0,1,4,9],[0,1,8,27]) Make a box and whisker plot. -# Arguments -$xydoc - # Keyword arguments - `notch`: Bool. Notch the box plot? (false) - `range`: Real. Values more than range*IQR below the first quartile From f50862ac517ca2f3cfbfc538cbd98e3baa10c42b Mon Sep 17 00:00:00 2001 From: "Samuel S. Watson" Date: Wed, 16 Jan 2019 08:43:43 -0500 Subject: [PATCH 6/6] Remove blank lines --- src/utils.jl | 3 --- 1 file changed, 3 deletions(-) diff --git a/src/utils.jl b/src/utils.jl index a0bad5a8..7f582e81 100644 --- a/src/utils.jl +++ b/src/utils.jl @@ -1233,6 +1233,3 @@ end function _document_argument(S::AbstractString) _fmt_paragraph("`$S`: "*_arg_desc[Symbol(S)],leadingspaces = 6 + length(S)) end - - -