PlotlyLight
PlotlyLight is an ultra-lightweight (~150 lines) interface for working with Plotly.js.
π Features
π Fastest time-to-first-plot in Julia!π Use the Plotly.js Javascript documentation directly. No magic syntax: JustJSON3.write
.- Set deeply-nested keys easily with
EasyConfig.jl
.- e.g.
myplot.layout.xaxis.title.font.family = "Arial"
- e.g.
- Set deeply-nested keys easily with
πΈοΈ Plays nicely with Cobweb.jl to display or save plots as HTML.π Plots will appear inMIME"text/html"
environments (like Pluto.jl).π The Same built-in themes as Plotly's python package.
π Quickstart
using PlotlyLight
# Change template
PlotlyLight.template!("plotly_dark")
# Make plot
p = Plot(x = 1:20, y = cumsum(randn(20)), type="scatter", mode="lines+markers")
# Make changes
p.layout.title.text = "My Title!"
# `display(p)` to see the updated plot
p
Adding Traces
PlotlyLight.Plot
objects are callable. Repeatedly make calls to add traces.
Plot()(
x = 1:10, y = randn(10), name = "trace 1"
)(
x = 3:12, y = randn(10), name = "trace 2"
)
π Saving Plots
Cobweb.jl
Save HTML files withusing Cobweb: Page
page = Page(p)
save(page, "myplot.html")
PlotlyKaleido.jl
Save images withusing PlotlyKaleido
PlotlyKaleido.savefig(p, "myplot.png")
π Docs
?Plot
Plot(data, layout, config; id, js)
- A Plotly.js plot with components
data
,layout
, andconfig
.data = Config()
: AConfig
(single trace) orVector{Config}
(multiple traces).layout = Config()
.config = Config(displaylogo=false, responsive=true)
.
- Each of the three components are converted to JSON via
JSON3.write
. - See the Plotly Javascript docs here: https://plotly.com/javascript/.
- Keyword Args:
id
: Theid
of the<div>
the plot will be created in. Default:randstring(10)
.js
:Cobweb.Javascript
to add after the creation of the plot. Default:Cobweb.Javascript("console.log('plot created!')")
?PlotlyLight.src!
src!(x::Symbol) # `x` must be one of: [:cdn, :local, :standalone, :none]
:cdn
β Use PlotlyJS CDN.:local
β Use local artifact.:standalone
β Write JS into the HTML file directly (can be shared and viewed offline).:none
β For when inserting into a page with Plotly.js already included.
βοΈ Defaults
You can set default values for the layout
, config
, and a number of other options that affect how the plot displays in your browser. HTML defaults (class
/style
/parent_class
/parent_style
) are chosen to make the plot reactive to the browser window size.
module Defaults
# Plot defaults
config = Ref(Config(displaylogo=false, responsive=true))
layout = Ref(Config())
# HTML defaults
src = Ref(:cdn) # How plotly gets loaded. see ?PlotlyLight.src!
class = Ref("") # class of the <div> the plot is inside of.
style = Ref("height: 100%;") # style of the <div> the plot is inside of.
parent_class = Ref("") # class of the plot's parent <div>.
parent_style = Ref("height: 100vh;") # style of the plot's parent <div>.
end
- As a reference, the underlying HTML of the plot looks like this:
<div class="$parent_class" style="$parent_style">
<div class="$class" style="$style" id="plot_goes_here"></div>
</div>
- Default values are
Ref
s and can be changed e.g.
PlotlyLight.Defaults.layout[].title.text = "Default Title"
- Revert back to the original defaults with
Defaults.reset!()
π Themes/Templates
The themes available in Plotly's python package are also made available in PlotlyLight.jl. They can be set via:
layout = Config(template = PlotlyLight.template("plotly_dark"))
PlotlyLight.template!("plotly_dark") # or replace the default `layout.template`
See PlotlyLight.templates
for a list of theme/template options:
"ggplot2"
"gridon"
"plotly"
"plotly_dark"
"plotly_white"
"presentation"
"seaborn"
"simple_white"
"xgridoff"
"ygridoff"
π΅βπ« Gotchas
- JSON does not have multidimensional arrays (https://www.w3schools.com/js/js_json_datatypes.asp). Therefore, traces that require matrix inputs (such as heatmap) must use a Vector of Vectors. We include a small utility function for running this conversion:
PlotlyLight.collectrows(x::Matrix)
.