recipetype(s, args...)

Use this function to refer to type recipes by their symbol, without taking a dependency.

Example

import RecipesBase: recipetype
recipetype(:groupedbar, 1:10, rand(10, 2))

instead of

import StatsPlots: GroupedBar
GroupedBar((1:10, rand(10, 2)))

@layout mat

Generate the subplots layout from a matrix of symbols (where subplots can span multiple rows or columns). Precise sizing can be achieved with curly brackets, otherwise the free space is equally split between the plot areas of subplots. You can use the _ character (underscore) to ignore plots in the layout (blank plots).

Examples

julia> @layout [a b; c]
2×1 Matrix{Any}:
 Any[(label = :a, blank = false) (label = :b, blank = false)]
 (label = :c, blank = false)

julia> @layout [a{0.3w}; b{0.2h}]
2×1 Matrix{Any}:
 (label = :a, width = 0.3, height = :auto)
 (label = :b, width = :auto, height = 0.2)

julia> @layout [_ ° _; ° ° °; ° ° °]
3×3 Matrix{Any}:
 (label = :_, blank = true)   …  (label = :_, blank = true)
 (label = :°, blank = false)     (label = :°, blank = false)
 (label = :°, blank = false)     (label = :°, blank = false)

This handy macro will process a function definition, replace --> commands, and then add a new version of RecipesBase.apply_recipe for dispatching on the arguments.

This functionality is primarily geared to turning user types and settings into the data and attributes that describe a Plots.jl visualization.

Set attributes using the --> command, and return a comma separated list of arguments that should replace the current arguments.

An example:

using RecipesBase

# Our custom type that we want to display
struct T end

@recipe function plot(t::T, n::Integer = 1; customcolor = :green)
    markershape --> :auto, :require
    markercolor --> customcolor, :force
    xrotation --> 5
    zrotation --> 6, :quiet
    rand(10,n)
end

# ---------------------

# Plots will be the ultimate consumer of our recipe in this example
using Plots; gr()

# This call will implicitly call `RecipesBase.apply_recipe` as part of the Plots
# processing pipeline (see the Pipeline section of the Plots documentation).
# It will plot 5 line plots, all with black circles for markers.
# The markershape argument must be supported, and the zrotation argument's warning
# will be suppressed.  The user can override all arguments except markercolor.
plot(T(), 5; customcolor = :black, shape=:c)

In this example, we see lots of the machinery in action. We create a new type T which we will use for dispatch, and an optional argument n, which will be used to determine the number of series to display. User-defined keyword arguments are passed through, and the --> command can be trailed by flags:

• quiet: Suppress unsupported keyword warnings
• require: Error if keyword is unsupported
• force: Don't allow user override for this keyword

Meant to be used inside a recipe to add additional RecipeData objects to the list:

@recipe function f(::T)
    # everything get this setting
    linecolor --> :red

    @series begin
        # this setting is only for this series
        fillcolor := :green

        # return the args, just like in recipes
        rand(10)
    end

    # this is the main series... though it can be skipped by returning nothing.
    # note: a @series block returns nothing
    rand(100)
end

@shorthands(funcname::Symbol)

Defines and exports shorthand plotting method definitions ($funcname and $funcname!). Pass the series type (as a symbol) to the macro.

Examples

# define some series type
@recipe function f(::Type{Val{:myseriestype}}, x, y)
    # some implementation here
end
# docstrings are forwarded
"""
    myseriestype(x, y)
Plot my series type!
"""
@shorthands myseriestype

You can easily define your own plotting recipes with convenience methods:

@userplot GroupHist

@recipe function f(gh::GroupHist)
    # set some attributes, add some series, using gh.args as input
end
# now you can plot like:
grouphist(rand(1_000, 4))