Creating plots
At the lowest level, a single plot can be created through the following steps:
- Define a
Viewport
with the NDC of the boxes where the plot should be drawn. - 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. - Create an
Axes
object with suitable dimensions and properties to contain the geometries. - Create a
Legend
to display the legends, if suitable. - Create a
Colorbar
to represent a guide to color codes, if suitable. - Put all the previous components together in a
PlotObject
. - Take a
Figure
where the plot should be displayed —; e.g. the current figure throughgcf()
, or create it, and put the newly createdPlotObject
into theplots
vector of that figure.
GRUtils also provides various constructors of those types and other functions that make those steps easier.
Viewport
constructors
GRUtils.Viewport
— MethodViewport(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).
Geometry
constructors
GRUtils.Geometry
— MethodGeometry(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).
GRUtils.Geometry
— MethodGeometry(g::Geometry; kwargs...)
Return a copy of g
replacing the data and attributes given as keyword arguments.
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.geometries
— Functiongeometries(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.
geometries(p::PlotObject)
Return the vector of geometries contained in p
.
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.Axes
— MethodAxes(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.
GRUtils.Axes
— MethodAxes(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.
Legend
constructors
GRUtils.Legend
— MethodLegend(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.
Colorbar
constructors
GRUtils.Colorbar
— MethodColorbar(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
.
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.@plotfunction
— Macro@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
: aSymbol
with the name of the kind of theGeometry
that is created.axes
: aSymbol
with the name of the kind of theAxes
that are created.plotkind
: aSymbol
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 functiongeometries
), and (b) the set of keyword arguments that are passed to the constructor of geometries, axes, and the plot object. Ifsetargs
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.