One-function API

A central design goal of Plots.jl is that the user should rarely have to consult the documentation while plotting. This is achieved by having a tightly unified syntax that has few function names to remember, and by having a great deal of flexibility in the inputs of those functions through aliases and redundancy.

Plots.jl’s main interface is simply the plot function,¹ which creates a new plot object. Additionally, there is a plot! function that modifies an existing plot object, e.g. by changing axes limits or adding new elements. Any type of predefined plot (e.g. a histogram, a bar plot, a scatter plot, a heatmap, an image, a geographical map, etc.) may be created by a call to plot. The exact type is defined by the keyword argument seriestype and the input arguments (type and number). New seriestypes can be created with recipes (see below).

For convenience, plots.jl also exports shorthand functions named after the seriestypes (see examples in Listing 1).

All aspects of the plot are controlled by a set of plot attributes, that are controlled by keyword arguments [26]. plots.jl distinguishes four hierarchical levels of attributes: plot attributes, subplot attributes, axis attributes and series attributes (cf. Figure 1). There is one additional special type of attributes called magic attributes. They allow to set multiple attributes that belong to a common element in a single keyword. E.g. plot(1:2; line = (5, :dash)) is equivalent to plot(1:2; linewidth = 5, linestyle = :dash).

A series in the context of plots.jl syntax is an individual plot element, such as a continuous line or a set of scatter points. For example, the left plot in Figure 1 has three series, distinguished by different types of markers. A plot may contain multiple series, e.g. when adding a trend line to a scatter plot. Multiple series may be added in the same plot call by concatenating the data as columns in a row matrix (see below), or added sequentially with the plot! function.

Input arguments can have many different forms, such as:

Calling the plot function returns a plot object. The plot object is essentially a big nested dictionary holding the plot attributes for the layout, subplots, series, segments, etc. and their associated data values. The plot object is automatically rendered in the surrounding context² when returned to an interactive session, or can be displayed explicitly by calling the display function on the object. This delayed rendering means that plot calls can be combined without unnecessary intermediate rendering.

Pipeline

The plotting pipeline has two main stages (cf. Figure 2): construction of the plot using plot/plot! calls and creation of the output via savefig/display/gui calls. These calls are often called implicitly in environments like the Julia REPL, notebooks or IDEs.

The very first step upon construction is to convert all inputs to form the list of plot attributes that constitute the plot specification. As shown in Listing 3 plots.jl is very flexible about possible input values. The conversion step involves defining values for every attribute based on the provided keyword arguments. This includes replacing aliases of attributes (which are multiple alternatively spelled keywords, such as ‘c’ or ‘color’, encoding the same attribute), handling of missing and nothing values in the input data and attribute values, and determining the final values based on the set of defaults. The default values are organized in a hierarchical framework, based on the values of other attributes; e.g. linecolor, fillcolor and markercolor will default to seriescolor under most seriestypes. But, for instance, under the bar seriestype, linecolor will default to :black, giving bars a black border by default. This allows the construction of appropriate plots with a minimum of user specification, an input paradigm that contrasts with that of e.g. matplotlib, where every aspect of the plot is usually defined manually by the user. This paradigm allows for quick and simple visualisation as part of e.g. data analysis.

After input and attribute conversion, recipes are applied recursively and the plot and Subplot objects are initialized. Recipes will be explained in detail in the next section.

When an output is to be produced the layout will be computed and the backend-specific code will be executed to produce the result.

Recipes

As mentioned in the introduction, recipes are the key mechanism in the plots.jl pipeline to allow composable definition of visualizations across Julia packages. A recipe works as a template that allows the users and package developers to define custom plotting routines while only depending on the lightweight package RecipesBase.jl (instead of on plots.jl). Recipes are applied recursively, which makes it easy to compose or combine multiple recipes. This means that any recipe may call other recipes until the plot consists of a seriestype defined internally in plots.jl. This composability, is a major improvement to ecosystem support, as it gives a combinatory reduction in the amount of code required for downstream libraries to add native plotting support for their types.

plots.jl distinguishes four types of recipes: user recipes, type recipes, plot recipes and series recipes [20] (cf. Listing 4). By far the most commonly used types are User recipes, which define how to plot objects of a certain type, and series recipes, which define a new seriestype. All four types can be constructed with the @recipe macro which acts on a function definition and creates a new method for the RecipesBase.apply_recipe function. The recipe type is determined by the signature of the function definition, utilizing the multiple dispatch capabilities of the Julia programming language.

It is sufficient to depend on the RecipesBase.jl package, a small and lightweight dependency to define a recipe. The aim of RecipesBase.jl is to make specialized syntax available for the code author to define visualizations; it has no effect until the package end user loads plots.jl directly.

How is this an improvement over other approaches to defining new visualizations? In most plotting libraries such as matplotlib [21], a downstream ODE solver library can add a new function plotsolution that will plot an ODE solution. However, the primary technological advance of the plots.jl recipe system is that the application of recipes is recursive and extendable via multiple dispatch. This solves a combinatory problem for downstream support: it is possible to combine and chain recipes to support plotting on new combinations of input types without ever defining a recipe for that specific combination.

To illustrate this, consider the example of combining recipes defined by the Julia packages DifferentialEquations.jl [33] and Measurements.jl [16] (cf. Figure 3 and Listing 9). In this example, a user solves a differential equation with uncertain initial conditions specified by Measurements.Measurement objects. The uncertainty encoded in the Measurement objects are automatically propagated through the ODE solver, as multiple methods for this type have been defined for arithmetic functions. The resulting ODE solution Sol will then also be specified in terms of Measurements.Measurements. When calling plot(sol), the recipe for ODE solvers will transform the ODESolution object into an array of arrays, each representing a time series to plot, using techniques like dense output to produce a continuous looking solution. This array of arrays contains number types matching the state of the solution, in this case Measurements.Measurements. Successive applications of the user recipe defined in Measurements.jl then take each state value and assign the uncertainty part of the state to the yerror attribute and pass the value part of the state to the next recipe. When used with the initial seriestype :scatter this results in a scatter plot with proper error bars as seen in Figure 3.

Notably, the two packages have not been developed to work together and are not aware of each other. Yet, multiple dispatch allows to efficiently combine functionality from both packages, and the plots.jl recipe system allows the combined visualization to work automatically.

The recipe of Measurements.jl is an example of a particularly short recipe (cf. Listing 5). A Measurements.Measurement is represented as a type with two fields: value and uncertainty. It can be conveniently constructed with the Unicode infix operator ±. Thus, the object a ± b has a as the value and b as the uncertainty. An array of measurement values can be converted into an array of floating point values to plot, along with having the uncertainties as error bars, via the recipe defined in Listing 5:

Structure and interfaces

The code for plots.jl is not located in one repository, but split into a few packages, to enhance reuse of more general parts of the code by other packages (cf. Figure 4). In the following the different packages and their use cases will be described.

Plots.jl: The main user facing package; Defines all default values and holds the code for layouting, conversion of input arguments, output generation, all backend code and the default recipes. This is the repository with the highest rate of change.

StatsPlots.jl: A drop-in replacement for plots.jl, meaning it loads and reexports all of plots.jl and adds recipes that are specially targeted at visualisation of statistical data; It aims to be integrated with Julia’s statistical package ecosystem under the JuliaStats organisation. Therefore it has more dependencies than plots.jl, which increases the loading time. Since not all plots.jl users need this functionality it is separated in its own repository.

PlotUtils.jl: Provides general utility routines, such as handling colors, optimizing ticks or function sampling; This package is also used by e.g. the newer plotting package Makie.jl.

RecipesBase.jl: A package with zero 3rd-party dependencies, that can be used by other packages to define recipes for their own types without needing to depend on plots.jl.

RecipesPipeline.jl: Another lightweight package that defines an API such that other plotting packages can consume recipes from RecipesBase.jl without needing to become a backend of plots.jl.

GraphRecipes.jl: A package that provides recipes for visualisation of graphs in the sense of graph theory; These are also split out because they have some heavy dependencies.

PlotThemes.jl: Provides different themes for plots.jl.

PlotDocs.jl: Hosts the documentation of plots.jl.

Backends

plots.jl currently supports seven plotting frameworks as backends. These backends are the libraries that do the actual rendering, either on the screen or to a file. The code in plots.jl translates the user code to backend code (cf. Listings 6 to 8 and Figure 5).

The backend packages are independently developed by different people and organizations. Typically these plotting frameworks themselves have different graphic libraries as backends to support different output types. They differ in their area of expertise and have different trade-offs.

GR: The default backend; It uses the GR framework [18] and is among the fastest backends with a good coverage of functionality.

Plotly/PlotlyJS: The backend with the most interactivity and best web support using the plotly javascript library [29]; One use case is to create interactive plots in documentation [31] or notebooks. The plotly backend is a version with minimal dependencies, which doesn’t require the user to load any other Julia package and displays its graphics in the browser, while plotlyJS requires the user to load plotlyJS.jl, but offers display of plots in a standalone window.

PyPlot:PyPlot.jl is the Julia wrapper of matplotlib [21] and covers a lot of functionality at moderate speed.

PGFPlotsX: Uses the pgfplots LATEXpackage [28]; Thus, it is the slowest of the backends, but integrates very good with LATEXdocuments.

InspectDR: Fast backend with GUI and some interactivity; It does good for 2D and handles large datasets and high refresh rates [25].

UnicodePlots: A backend that allows plotting in the terminal with unicode characters; It can be used in a terminal also on headless machines [38]. Therefore it lacks a lot of functionality compared to the other backends.

HDF5: A backend that can be used to save the plot object along with the data in a hdf5-file using HDF5.jl [19], such that it can be recovered with any backend; It potentially allows interfacing with plots.jl from other programming languages.

Furthermore, there are six deprecated backends that were used in the earlier stages of plots.jl, but which are no longer maintained as well as the Gaston.jl backend which is in an early experimental stage. Gaston.jl is a Julia interface for gnuplot [17]. This shows that plots.jl can be sustained even if a maintainer of backend code leaves. Either the backend will be maintained by the community or it will be replaced by another backend.

The backend code of these backends, that is the glue code that translates plots.jl objects and attributes into calls and objects of the backend library, is located in the src/backends folder and, apart from the default backend, are only loaded when the backend gets activated.

A shortcoming of the backend design is that, in terms of maintenance, this part of the codebase is the biggest challenge, since it requires knowledge of plots.jl as well as of the target backend library. Maintainers of those libraries are usually working to capacity on their library, while users of plots.jl are often using plots.jl because they don’t want to learn the usage of one or even several different backends. That is why feature coverage between backends typically varies, though a good amount of these holes can be covered by recipes. Sometimes these even provide features that the backend library is missing or gives at least easier access in terms of syntax. On the other hand there are some features that are present in one backend library, but not in others. Some examples are layouts, information on hover, shared or split legends, hexagonal bins and more. In these cases one either has to find workarounds leveraging other aspects of the backend code, not support that feature at all, or only support it partially.

Dependencies

plots.jl has the following direct dependencies:

Contour.jl v0.5

FFMPEG.jl v0.2 – v0.4

FixedPointNumbers v0.6 – v0.8

GR.jl v0.46 – v0.55, v0.57

GeometryBasics.jl v0.2, v0.3.1 – v0.3

JSON.jl v0.21, v1

Latexify.jl v0.14 – v0.15

Measures.jl v0.3

NaNMath.jl v0.3

PlotThemes.jl v2

PlotUtils.jl v1

RecipesBase.jl v1

RecipesPipeline.jl v0.3

Reexport.jl v0.2, v1

Requires.jl v1

Scratch.jl v1

Showoff.jl v0.3.1 – v0.3, v1

StatsBase.jl v0.32 – v0.33

In addition, plots.jl has 125 indirect dependencies all of which can be seen at JuliaHub [30]. Thanks to Julia’s excellent package manager Pkg.jl, BinaryBuilder.jl, semantic versioning and required upper bounds for the general registry, handling of dependencies is relatively painless for users.