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)))

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
type T end

@recipe function plot{N<:Integer}(t::T, n::N = 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(1000,4))