Creating plots

At the lowest level, a single plot can be created through the following steps:

  1. Define a Viewport with the NDC of the boxes where the plot should be drawn.
  2. Create one or more Geometry objects based on the data that should be plotted and the kind of geometries that will represent them, and collect them in a vector.
  3. Create an Axes object with suitable dimensions and properties to contain the geometries.
  4. Create a Legend to display the legends, if suitable.
  5. Create a Colorbar to represent a guide to color codes, if suitable.
  6. Put all the previous components together in a PlotObject.
  7. Take a Figure where the plot should be displayed —; e.g. the current figure through gcf(), or create it, and put the newly created PlotObject into the plots vector of that figure.

GRUtils also provides various constructors of those types and other functions that make those steps easier.

Viewport constructors

GRUtils.ViewportMethod
Viewport(subplot, frame::Bool [, ratio::Real, margins])

Return a Viewport object, defined by the normalized coordinates of the box that contains it (the argument subplot, which are normalized with respect to the size of the figure, not the whole device), and a flag (frame::Bool) telling whether there should be a frame. The size of that frame is calculated automatically.

This constructor also accepts to optional arguments: ratio, which is the width:height ratio of the inner box, and margins, a 4-vector with extra margins that there should be between the outer and inner boxes, in addition to the default size of the frame (in the order left-right-bottom-top).

source

Geometry constructors

GRUtils.GeometryMethod
Geometry(kind::Symbol [; kwargs...])

Return a Geometry with selected parameters given by keyword arguments.

Most geometries do not need data for all the possible parameters that the Geometry type accepts. Thus, to simplify the creation of geometries, an alternative constructor takes the geometry’s kind as the only positional argument, and the rest of fields are given as keyword arguments (empty by default).

source
GRUtils.GeometryMethod
Geometry(g::Geometry; kwargs...)

Return a copy of g replacing the data and attributes given as keyword arguments.

source

There is also a function geometries to create vectors of Geometry objects from the input data easily, or to fetch them from an already existing plot, taking advantage of multiple dispatch:

GRUtils.geometriesFunction
geometries(kind, x [, y, z, c; kwargs...]) -> Vector{Geometry}

Create a vector of Geometry objects of a given kind, from arrays of data that define the coordinates of the geometries. All the other parameters of the geometries are given as keyword arguments

This function accepts coordinates defined only by one array of numbers, by two variables (x and y, typically for 2-D plots), three (x, y, z) or all four variables (x, y, z and c). If there is only one array x of real numbers given for the geometry coordinates, they will actually be used as Y coordinates, and X will be defined as a sequence of integers starting at 1. If that array contains complex numbers, the real part will be taken as X coordinates, and the imaginary part as Y coordinates.

The coordinates can be given as vectors or matrices with the same number of rows. In the latter case, each column of the matrices will be used to define a different Geometry. If some coordinates are given as vectors while other are in matrices, vectors will be recycled in all the geometries. E.g. if x is a vector with N numbers and y a matrix with N rows and M columns, the result will be a M-vector of geometries g such that g[i] will be a geometry whose X coordinates are the vector x, and whose Y coordinates are the i-th column of y.

In addition, the last coordinate can be given as a "broadcastable" function that takes the previous coordinates as inputs.

source
geometries(p::PlotObject)

Return the vector of geometries contained in p.

source

Axes constructors

There are two alternative constructors for Axes objects: one like the alternative Geometry constructor, which is basically a shortcut to define only the non-empty parameters via keyword arguments; and another one that sets the axes up automatically based on the data to be plotted.

GRUtils.AxesMethod
Axes(kind::Symbol [; kwargs...])

Return an Axes object with selected parameters given by keyword arguments.

This constructor only requires the kind of the axes (:axes2d, :axes3d or :axespolar), such that all the other parameters are passed as keyword arguments. Null or empty values are used by default for the parameters that are not given.

source
GRUtils.AxesMethod
Axes(kind, geoms::Array{<:Geometry} [; kwargs...]) where kind

Return an Axes object defined by the kind of the axes, and a vector of Geometry objects that are meant to be plotted inside the axes, which are used to calculate the different axis limits, ticks, etc. Keyword arguments are used to override the default calculations.

source

Legend constructors

GRUtils.LegendMethod
Legend(geoms, frame [, maxrows])

Return a Legend object defined by the collection of geometries that are meant to be referred to in the legend (geoms), and the dimensions (width, height) of the frame in which the legend should be drawn.

The geometries are used to set the number of items to be drawn in the legend, and their labels. The frame is used to estimate the font size of the labels.

Optionally, this constructor can take the maximum number of items that are represented in each column of the legend. Only the items in that collection of geometries where label is not empty will be included.

source

Colorbar constructors

GRUtils.ColorbarMethod
Colorbar(axes::Axes [, colors=256])

Return a Colorbar defined by an Axes object that is used to calculate its different properties, depending on the kind of axis and the range of the c axis. If the c axis is not defined, this will return an empty Colorbar.

source

Top-level plot constructors

The constructors presented above for the different components of a plot allow to build plots from data using different "grammars". Besides, GRUtils also provide top-level Plotting functions that imitate the interface provided by jlgr.

Since most of those functions follow the same basic steps described above, a macro @plotfunction is provided to create them from a template.

GRUtils.@plotfunctionMacro
@plotfunction(fname, options...)

Macro to create plotting functions. E.g. @plotfunction plot creates two functions:

* `plot!(f::Figure, args...; kwargs...)`
* `plot(args...; kwargs...)`

The first of those functions (the one whose name ends with an exclamation) edits the figure given as first argument, replacing its last plot by a new one. The second function (the one without exclamation) creates the plot in the current figure. How those functions work depends on the options that are passed after the function name to the macro. Those options are expressed in the fashion of keyword argments, i.e. as key = value, and they can be the following:

  • geom: a Symbol with the name of the kind of the Geometry that is created.
  • axes: a Symbol with the name of the kind of the Axes that are created.
  • plotkind: a Symbol with the name of the plot kind (only needed as meta-data). If this option is not given, the name of the function is used by default.
  • setargs: a function that takes the positional and keyword arguments that are passed to the functions, and returns: (a) a tuple of positional arguments to be passed to the function geometries), and (b) the set of keyword arguments that are passed to the constructor of geometries, axes, and the plot object. If setargs is not defined, the positional and keyword arguments are returned untransformed.
  • kwargs: a named tuple with extra keyword arguments that are passed to the constructors of geometries, axes and the plot object.
  • docstring: the documentation string that will be assigned to the plotting function.
source