Manipulating plots

There are various methods defined on the Plot type. We will cover a few of them here, but consult the (forthcoming) API docs for more exhaustive coverage.

Julia functions

Plot and SyncPlot both have implementations of common Julia methods:

size: returns the width and layout attributes in the plot’s layout
copy: create a shallow copy of all traces in the plot and the layout, but

create a new divid

API functions

All exported functions from the plotly.js API have been exposed to Julia and operate on both Plot and SyncPlot instances. Each of these functions has semantics that match the semantics of plotly.js

In PlotlyJS.jl these functions are spelled:

restyle!: edit attributes on one or more traces
relayout!: edit attributes on the layout
update!: combination of restyle! and relayout!
react!: In place updating of all traces and layout in plot. More efficient than constructing an entirely new plot from scratch, but has the same effect.
addtraces!: add traces to a plot at specified indices
deletetraces!: delete specific traces from a plot
movetraces!: reorder traces in a plot
redraw!: for a redraw of an entire plot
purge!: completely remove all data and layout from the chart
extendtraces!: Extend specific attributes of one or more traces with more data by appending to the end of the attribute
prependtraces!: Prepend additional data to specific attributes on one or more traces

When any of these routines is called on a SyncPlot the underlying Plot object (in the plot field on the SyncPlot) is updated and the plotly.js function is called. This is where SyncPlot gets its name: when modifying a plot, it keeps the Julia object and the display in sync.

For more details on which methods are available for each of the above functions consult the docstrings or (forthcoming) API documentation.

Be especially careful when trying to use restyle!, extendtraces!, and prependtraces! to set attributes that are arrays. The semantics are a bit subtle. Check the docstring for details and examples

Subplots

A common task is to construct subpots, or plots with more than one set of axes. This is possible using the declarative plotly.js syntax, but can be tedious at best.

PlotlyJS.jl provides a convenient syntax for constructing what we will call regular grids of subplots. By regular we mean a square grid of plots.

To do this we will make a pun of the vcat, hcat, and hvcat functions from Base and leverage the array construction syntax to build up our subplots.

Suppose we are working with the following plots:

julia> p1 = Plot(scatter(;y=randn(3)))
data: [
  "scatter with fields type and y"
]

layout: "layout with fields margin and template"

julia> p2 = Plot(histogram(;x=randn(50), nbinsx=4))
data: [
  "histogram with fields nbinsx, type, and x"
]

layout: "layout with fields margin and template"

julia> p3 = Plot(scatter(;y=cumsum(randn(12)), name="Random Walk"))
data: [
  "scatter with fields name, type, and y"
]

layout: "layout with fields margin and template"

julia> p4 = Plot([scatter(;x=1:4, y=[0, 2, 3, 5], fill="tozeroy"),
                  scatter(;x=1:4, y=[3, 5, 1, 7], fill="tonexty")])
data: [
  "scatter with fields fill, type, x, and y",
  "scatter with fields fill, type, x, and y"
]

layout: "layout with fields margin and template"

If we wanted to combine p1 and p2 as subplots side-by-side, we would do

[p1 p2]

If instead we wanted two rows and one column we could

[p3; p4]

Finally, we can make a 2x2 grid of subplots:

[p1 p2
 p3 p4]

New in PlotlyBase version 0.6.5 (PlotlyJS version 0.16.4)

As of version 0.16.4, we can also create a non-rectangular grid of subplots using this syntax.

For example:

[p1 p2 p3 p4; p2 p4; p1]

`make_subplots`

New in PlotlyBase version 0.6.4 (PlotlyJS version 0.16.3)

As of version 0.16.3, there is another option for creaing subplots: the make_subplots function

This function takes a number of keyword arguments and allows fine grained control over the layout and labels for subplots.

Consider the example below:

p = make_subplots(
    rows=5, cols=2,
    specs=[Spec() Spec(rowspan=2)
           Spec() missing
           Spec(rowspan=2, colspan=2) missing
           missing missing
           Spec() Spec()]
)

add_trace!(p, scatter(x=[1, 2], y=[1, 2], name="(1,1)"), row=1, col=1)
add_trace!(p, scatter(x=[1, 2], y=[1, 2], name="(1,2)"), row=1, col=2)
add_trace!(p, scatter(x=[1, 2], y=[1, 2], name="(2,1)"), row=2, col=1)
add_trace!(p, scatter(x=[1, 2], y=[1, 2], name="(3,1)"), row=3, col=1)
add_trace!(p, scatter(x=[1, 2], y=[1, 2], name="(5,1)"), row=5, col=1)
add_trace!(p, scatter(x=[1, 2], y=[1, 2], name="(5,2)"), row=5, col=2)

relayout!(p, height=600, width=600, title_text="specs examples")
p.plot

More examples are being worked on at this time (2021-07-14), but for now you can view the docs for make_subplots to get an idea of what else is possible.

Saving figures

Figures can be saved in a variety of formats using the savefig function.

!!! note

Note that the docs below are shown for the PlotlyBase.Plot type, but are also defined for PlotlyJS.SyncPlot. Thus, you can use these methods after calling either plot or Plot.

This function has a few methods:

# PlotlyJS.savefig — Method

savefig(
    p::Plot, fn::AbstractString;
    format::Union{Nothing,String}=nothing,
    width::Union{Nothing,Int}=nothing,
    height::Union{Nothing,Int}=nothing,
    scale::Union{Nothing,Real}=nothing,
)

Save a plot p to a file named fn. If format is given and is one of png, jpeg, webp, svg, pdf, eps, json, or html; it will be the format of the file. By default the format is guessed from the extension of fn. scale sets the image scale. width and height set the dimensions, in pixels. Defaults are taken from p.layout, or supplied by plotly

When using this method the format of the file is inferred based on the extension of the second argument. The examples below show the possible export formats:

savefig(p::Union{Plot,SyncPlot}, "output_filename.pdf")
savefig(p::Union{Plot,SyncPlot}, "output_filename.html")
savefig(p::Union{Plot,SyncPlot}, "output_filename.json")
savefig(p::Union{Plot,SyncPlot}, "output_filename.png")
savefig(p::Union{Plot,SyncPlot}, "output_filename.svg")
savefig(p::Union{Plot,SyncPlot}, "output_filename.jpeg")
savefig(p::Union{Plot,SyncPlot}, "output_filename.webp")

savefig(
    io::IO,
    p::Plot;
    width::Union{Nothing,Int}=nothing,
    height::Union{Nothing,Int}=nothing,
    scale::Union{Nothing,Real}=nothing,
    format::String="png"
)

This method allows you to save a plot directly to an open IO stream.

See the savefig(::IO, ::PlotlyBase.Plot) API docs for more information.

Base.show(::IO, ::MIME, ::Union{PlotlyBase.Plot})

This method hooks into Julia’s rich display system.

Possible arguments for the second argument are shown in the examples below:

savefig(io::IO, ::MIME"application/pdf", p::Union{Plot,SyncPlot})
savefig(io::IO, ::MIME"image/png", p::Union{Plot,SyncPlot})
savefig(io::IO, ::MIME"image/svg+xml", p::Union{Plot,SyncPlot})
savefig(io::IO, ::MIME"image/eps", p::Union{Plot,SyncPlot})
savefig(io::IO, ::MIME"image/jpeg", p::Union{Plot,SyncPlot})
savefig(io::IO, ::MIME"application/json", p::Union{Plot,SyncPlot})
savefig(io::IO, ::MIME"application/json; charset=UTF-8", p::Union{Plot,SyncPlot})

You can also save the json for a figure by calling savejson(p::Union{Plot,SyncPlot}, filename::String).