Документация Engee

Работа с графиками

Для типа Plot определены различные методы. Здесь мы рассмотрим некоторые из них, но для получения более полной информации обратитесь к документации по API (которая будет выпущена в ближайшее время).

Функции Julia

Plot и SyncPlot имеют реализации общих методов Julia:

  • size: возвращает атрибуты width и layout в макете графика

  • copy: создает поверхностную копию всех линий на графике и макете, но создает новый divid

Функции API

Все экспортируемые функции из API plotly.js были представлены в Julia и работают с экземплярами Plot и SyncPlot. Каждая из этих функций имеет семантику, соответствующую семантике plotly.js.

В PlotlyJS.jl используются следующие функции:

  • restyle!: редактирует атрибуты для одной или нескольких линий

  • relayout!: редактирует атрибуты для макета

  • update!: сочетание restyle! и relayout!

  • react!: обновляет на месте все линии и макет графика. Является более эффективной, чем создание графика с нуля, но имеет такой же эффект.

  • addtraces!: добавляет линии на график по указанным индексам

  • deletetraces!: удаляет определенные линии с графика

  • movetraces!: переупорядочивает линии на графике

  • redraw!: для перерисовки всего графика

  • purge!: полностью удаляет все данные и макет из графика

  • extendtraces!: расширяет определенные атрибуты одной или нескольких линий дополнительными данными путем их добавления в конец атрибута

  • prependtraces!: добавляет дополнительные данные в начало определенных атрибутов одной или нескольких линий

При вызове любой из этих процедур для SyncPlot происходит обновление базового объекта Plot (в поле plot в объекте SyncPlot) и вызывается функция plotly.js. Именно поэтому у SyncPlot такое имя: при изменении графика он поддерживает синхронизацию объекта Julia и отображения.

Более подробную информацию о том, какие методы доступны для каждой из перечисленных функций, можно получить в строках docstring или в (готовящейся к выпуску) документации по API.

Будьте особенно осторожны при попытке использовать restyle!, extendtraces! и prependtraces! для задания атрибутов, являющихся массивами. Здесь применяется более тонкая семантика. Подробности и примеры см. в docstring.

Подграфики

Распространенной задачей является построение подграфиков или графиков с несколькими наборами осей. Ее можно реализовать с помощью декларативного синтаксиса plotly.js, но в лучшем случае эта задача может быть утомительной.

PlotlyJS.jl предоставляет удобный синтаксис для построения того, что мы будем называть правильными сетками подграфиков. Под «правильной» понимается квадратная сетка графиков.

Для этого мы воспользуемся функциями vcat, hcat и hvcat из Base и с помощью синтаксиса построения массивов создадим подграфики.

Предположим, что мы работаем со следующими графиками:

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"

Чтобы расположить p1 и p2 как подграфики рядом друг с другом, нужно сделать следующее.

[p1 p2]
manipulating plots1

Если же нам требуются две строки и один столбец, нужно сделать следующее.

[p3; p4]
manipulating plots2

Наконец, можно создать сетку 2x2 подграфиков:

[p1 p2
 p3 p4]
manipulating plots3

Новая возможность в PlotlyBase версии 0.6.5 (PlotlyJS версии 0.16.4)

Начиная с версии 0.16.4 с помощью этого синтаксиса можно также создавать непрямоугольную сетку подграфиков.

Например:

[p1 p2 p3 p4; p2 p4; p1]

make_subplots

Новая возможность в PlotlyBase версии 0.6.4 (PlotlyJS версии 0.16.3)

Начиная с версии 0.16.3 появилась еще одна возможность создания подграфиков: функция make_subplots.

Эта функция принимает ряд именованных аргументов и позволяет детально контролировать макет и надписи для подграфиков.

Рассмотрим пример ниже.

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

В настоящее время (14.07.2021) ведется работа над дополнительными примерами, но пока вы можете посмотреть документацию по make_subplots, чтобы получить представление о том, какие возможности еще доступны.

Сохранение фигур

С помощью функции savefig можно сохранять фигуры в разных форматах.

Обратите внимание, что приведенные ниже документы приведены для типа PlotlyBase.Plot, но также определены и для PlotlyJS.SyncPlot. Таким образом, эти методы можно использовать после вызова plot или Plot.

Эта функция имеет несколько методов.

1

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,
)

Сохраняет график p в файл fn. Если format задан и имеет тип png, jpeg, webp, svg, pdf, eps, json или html, он будет представлять формат файла. По умолчанию формат определяется расширением fn. scale задает масштаб изображения. width и height задают измерения (в пикселях). Значения по умолчанию можно получить из p.layout, либо их предоставляет plotly.

При использовании этого метода формат файла определяется расширением второго аргумента. В примерах ниже показаны возможные форматы экспорта.

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")

2

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

Этот метод позволяет сохранять график непосредственно в открытый поток ввода-вывода.

Дополнительные сведения см. в документации по API savefig(::IO, ::PlotlyBase.Plot).

3

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

Этот метод включен в обширную систему отображения Julia.

Возможные значения второго аргумента приведены в примерах ниже.

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})

Вы также можете сохранить JSON для фигуры, вызвав savejson(p::Union{Plot,SyncPlot}, filename::String).