BokehServer: a Bokeh server in Julia

Goals

It seemed Julia was missing a reactive plot library, meaning one which would react to changes in the data when used with Pluto or IJulia. This package tries to bring these features by relying on the excellent (Bokeh)[https://docs.bokeh.org/en/latest/index.html] library. The latter is basically a python web server with a javascript client. This package reproduces the python server and reuses the javascript part as is. This package's API is loosely similar to its python counterpart.

Getting Started

A number of examples are provided in the examples directory. These usually involve starting a server:

BokehServer.serve() do
    BokehServer.line(rand(Float64, 100))
end

One could also create a stand-alone html page:

BokehServer.html() do
    BokehServer.line(rand(Float64, 100))
end

We try to keep a similar API to the one provided by Bokeh. The main differences are due to Julia's aversion to instance or class methods. A python call fig.line([1, 2, 3]) becomes line!(fig; y = [1, 2, 3]). In other words:

Julia relies on free functions. Thus the call requires adding the current plot as first argument.
Julia suggests using a ! when a function mutates its first argument. Thus our free functions:
- without a !, will create a plot, feed it to the !-ended free function, finally returning said plot.
- with a !, will require a plot as first argument. The function usually adds one or more renderers to the plot.
Julia makes a clear distinction between positional and keyword arguments, whereas python doesn't. We recreated something similar to python's: one will obtain the same plot when writing line!(fig, 1:10, (1:10).^2) or line!(fig; x = 1:10, y = (1:10).^2).

Gallery

Checkout Bokeh's gallery or try the files in the examples directory.

Using the `Plots` package

A Plots backend is provided. It relies on a bokeh function being called.

begin
    using Plots
    using BokehServer
    bokeh()
end

Using Jupyter or Pluto

Example notebooks are examples/jupyter_notebook.ipynb and examples/pluto_notebook.jl.

Using the library requires two initial lines:

using BokehServer # import our library
# provide javascript headers to your browser, default port is 5006
BokehServer.Embeddings.notebook(; port = 4321)

Initializing a notebook environment

We need the notebook call to be the last in the cell! This is so the bokehjs library is added to the browser page.

Any layout or plot returned by a cell is then displayed in the notebook. Changes occurring in julia in other cells will affect this display.

The following will display a time series, with default indices on the x axis.

plot = BokehServer.line(; y = randn(Float64, 100) .+ (1:100))

We can update the previous cell from another:

push!(
    plot.renderers[1].data_source,
    Dict("y" => randn(Float64, 100) .+ (100:-1:1), "x" => 101:200)
);

In the background, a websocket server is created which will synchronize your BokehServer objects in Julia with their typescript counterparts. It will also manage the event mechanism provided by BokehServer.

Starting a server or creating a stand-alone html page

Examples abound in the examples directory. They all involve using:

BokehServer.serve() do
    plot = figure() # create a plot
    ...
    plot # return the plot
end

Stand-alone HTML pages

To create a stand-alone page, simply replace serve by html.

The do ... end scope

BokehServer objects should be created strictly within the do ... end scope. This is because of the event mechanism is initialized only within this scope.

Available plots

One can create a plot using:

BokehServer.Plotting.figure — Function

figure(;
    # tool keywords
    active_drag    :: Union{Nothing, iDrag, String, Model.EnumType{(:auto,)}}                              = :auto
    active_inspect :: Union{Nothing, iInspectTool, String, Model.EnumType{(:auto,)}, Vector{iInspectTool}} = :auto
    active_multi   :: Union{Nothing, iGestureTool, String, Model.EnumType{(:auto,)}}                       = :auto
    active_scroll  :: Union{Nothing, iScroll, String, Model.EnumType{(:auto,)}}                            = :auto
    active_tap     :: Union{Nothing, iTap, String, Model.EnumType{(:auto,)}}                               = :auto
    tools          :: Union{String, Vector{Union{iTool, String}}}                                          = "pan,wheel_zoom,box_zoom,save,reset,help"
    tooltips       :: Union{Nothing, iTemplate, String, Vector{Tuple{String, String}}}                     = nothing

    # x-axis keywords
    x_axis_label    :: Union{Nothing, iBaseText, String}                                            = ""
    x_axis_location :: Union{Nothing, Model.EnumType{(:above, :below)}}                             = :below
    x_axis_type     :: Union{Nothing, Model.EnumType{(:auto, :linear, :log, :datetime, :mercator)}} = :auto
    x_minor_ticks   :: Union{Int64, Model.EnumType{(:auto,)}}                                       = :auto
    x_range         :: Any                                                                          = nothing

    # y-axis keywords
    y_axis_label    :: Union{Nothing, iBaseText, String}                                            = ""
    y_axis_location :: Union{Nothing, Model.EnumType{(:left, :right)}}                              = :left
    y_axis_type     :: Union{Nothing, Model.EnumType{(:auto, :linear, :log, :datetime, :mercator)}} = :auto
    y_minor_ticks   :: Union{Int64, Model.EnumType{(:auto,)}}                                       = :auto
    y_range         :: Any                                                                          = nothing
)

Create a Plot object.