Preliminaries

PlotlyJS.jl is a Julia package that relies on the plotly.js JavaScript library.

In that library, figures are constructed by calling the function:

Plotly.newPlot(divid, data, layout, config, frames)

where

data is an array of JSON objects describing the various data traces in the visualization (see Note)
layout is a JSON object describing the presentation properties of the visualization
config is a JSON object describing the configuration properties of the visualization (see more detail here)
frames can contain data and layout objects, which define any changes to be animated, and a traces object that defines which traces to animate.

The divid argument refers to an html <div> element to control the plot on a page and is handled automatically by one of the supported front-ends. Users of this package will mostly be concerned about constructing the data and the layout, and (optionally) config and frames arguments.

Note

A trace is a general term for how data is shown graphically on a plot, whether it is a scatter plot, bar chart, 3D surface, choropleth map or some other plot type. A trace is fundamentally a collection of data and the specifications of how that data should be plotted. For a complete list of traces and their attributes see the plotly figure reference.

When we want to construct a Plot in PlotlyJS.jl for plotting on some display, we will usually have at least one trace tr along with a layout object ly which we combine together as Plot(tr, ly). If we don't have a layout object then a template will supply a default layout for us.

Julia types

There are a handful of core Julia types for representing a visualization.

The data, layout, frames, divid and config fields of the Plot type, shown below, map to the arguments to the Plotly.newplot function. These types are defined in the PlotlyBase.jl package (a dependency of PlotlyJS.jl). These are shown (in a much simplified form) here:

abstract type AbstractTrace end
abstract type AbstractLayout end

mutable struct GenericTrace <: AbstractTrace
    fields::Dict{Symbol,Any}
end

mutable struct Layout <: AbstractLayout
    fields::Dict{Symbol,Any}
    subplots::Subplots
end

mutable struct PlotlyFrame <: AbstractPlotlyAttribute
    fields::Dict{Symbol,Any}
end

mutable struct PlotConfig
    scrollZoom::Union{Nothing,Bool} = true
    editable::Union{Nothing,Bool} = false
    staticPlot::Union{Nothing,Bool} = false
...
end

mutable struct Plot
    data::Vector{<:AbstractTrace}
    layout::AbstractLayout
    frames::Vector{<:PlotlyFrame}
    divid::UUID
    config::PlotConfig
end

The data field of the Plot type can be constructed from a single trace or a vector of multiple traces. Each trace is itself made up of a Dict type holding information about the type of trace and its data along with attributes for customising the plotting of that data.