Interactive Data Visualization in the browser, from Python

addresses #8084

fixes #4407 (new feature) fixes #4643 (irrelevant) fixes #5169 (fixed, needs a test) fixes #5572 (fixed) fixes #6294 (fixed) fixes #6417 (fixed, needs a test) fixes #6768 (fixed, needs a test) fixes #7120 (fixed, needs a test) fixes #7185 (irrelevant) fixes #7497 (fixed) fixes #7590 (fixed) [already closed?] fixes #7771 (fixed) fixes #8227 (fixed) fixes #8229 (new feature, needs tests, examples) fixes #6822 (fixed) fixes #4395 (fixed)

fixes #8391 (fixed, needs test) fixes #7260 (fixed) fixes #7454 (fixed, needs test) fixes #5749 (fixed) fixes #6259 (fixed) fixes #4608 (fixed) fixes #8611 (fixed)

Updated high level design principles:

• [ ] mime bundle for loading BokehJS

  The output_notebook() function generates a mime bundle looks like

  {'application/javascript': js, 
    'application/vnd.bokeh.bootstrap_bokehjs': ''}
  

  In the classic notebook, it ignores the bokeh mimetype and runs the JS. In JLab, the Bokeh mimetype has a higher precedence, so it ignores the JS mimetype.

  • For the classic notebook the JS will load the Bokeh mini-extension to register for the show mime type. Additionally BokehJS will be loaded from CDN or for inline resources, from the JS in the bundle itself.

  • For JLab the Bokeh mini-extension will be previously installed via usual JLab mechanisms. The extension will load BokehJS from CDN or for inline resources, from the locally installed Bokeh package. (via a REST endpoint??)

• [ ] mime bundle for showing standalone docs and applications

  The show(...) function generates a mime bundle that looks like

  'application/vnd.bokeh.show`: JSON
  

  Where JSON is the serialized Bokeh Document and any additional metadata (versions, comm ids etc)

This PR is one I have been working on with @bryevdv on my fork (https://github.com/jlstevens/bokeh/pull/4) that aims to fix issue #5278 and will possibly help address issue #3393. This PR supersedes #5276.

Aim

The goal is to allow users to specify Python and Javascript callbacks associated with events. Some suggestions for potential events include UIEvents (including hammer events such as 'tap', 'press', keypress events), model related events such as button click events as well as document level events such as 'busy'. Other proposals for events may be found on this wiki page.

As there are many potential event types, the goal is to introduce a very general mechanism that abstracts over all these potential event types (hammer, DOM, model related, document). This would be a very useful feature to have for building bokeh apps as well as for third party libraries used to build interactive Bokeh visualizations such as HoloViews.

Architecture outline

The API is very similar to the existing on_change and js_on_change API used to register callbacks triggered by property changes.

Events callbacks are defined on Model and stored on the JS side as a property js_event_callbacks and on the Python side in the _event_callbacks attribute of theEventCallbackManager mixin class (which is analogous to the PropertyCallbackManager class - formerly known as CallbackManager).

An EventManager instance exists per document in both on Python and Javascript - its job is to route events from wherever they are generated to the appropriate models that can process them. Model instances are responsible for actually invoking the registered callbacks in response to an event, triggered on the event manager. The EventManager also handles the communication of events from Javascript to Python as necessary.

To achieve this, Model has a subscribed_events property which specifies which events are being listened to on the Python side. These are the events that are to be communicated to Python so that Python callbacks can respond accordingly. Both Javascript and Python callbacks receive an event instance (e.g Tap) which contains information such as the position of the tap. In terms of the communication protocol, there is a single new Event message that is converted into corresponding event instances once received.

Current status

You can now use on_event and js_on_event with the currently defined set of events to execute either Javascript or Python callbacks. You can see the API in action in the fourier_animated.py example I am currently using for testing. I intend to write a new example app from scratch and include it in this PR later.

Open questions

The main architectural issue right now is that I need a way to supply event instances with a particular model id in order to target a particular model. For instance, events from a given UIEvents instance only apply to a particular Plot instance. What is the best way to get the appropriate model id - at the point where the events are generated? For more information about the problem, see https://github.com/jlstevens/bokeh/pull/4.

TODO

I have already listed various TODO items at https://github.com/jlstevens/bokeh/pull/4 and here are the most important outstanding items:

• [x] Write an example of a Button widget click event.
• [x] Make sure all classes have decent docstrings
• [x] Illustrate custom events by building a custom model.
• [x] Testing

Edit: to avoid having to refer back to the PR on my fork, here are the other TODO items I assigned myself:

• [x] Rename js_callbacks to js_property_callbacks
• [x] Add more event types and check they have useful contents
• [x] Make a new bokeh app example specifically for illustrating events (edit: superseded for now with two demos in examples/howto ).
• [x] Type annotations for typescript

Possible Future work

Currently events originating in JS can be communicated to Python but events originating in Python cannot currently be communicated to JS. An earlier prototype demonstrated that this feature is possible with the proposed architecture but this feature involves some tricky issues connecting up the communication protocol that are outside the scope of this PR.

In addition, it is trivial to add a Javascript API to the current system. This was successfully prototyped but is omitted here as there was no obvious naming scheme for the JS methods.

I'm not sure what's going on. I get this error occasionally and I may have gotten a reproducible example but I haven't confirmed just yet.

There are no errors in the python side. Instead of a plot I see <bokeh.io._CommsHandle at 0x109b1ec18> as the output. The javascript console shows:

Kernel: kernel_restarting (b738e19a-021b-47ef-9d08-076f696147c8)
main.min.js:22329 Kernel: kernel_created (b738e19a-021b-47ef-9d08-076f696147c8)
main.min.js:22673 Starting WebSockets: ws://localhost:8888/api/kernels/b738e19a-021b-47ef-9d08-076f696147c8
main.min.js:22329 Kernel: kernel_connected (b738e19a-021b-47ef-9d08-076f696147c8)
main.min.js:22329 Kernel: kernel_ready (b738e19a-021b-47ef-9d08-076f696147c8)
(program):67 Bokeh: BokehJS loaded, going straight to plotting
cdn.pydata.org/bokeh/release/bokeh-0.11.0.min.js:3 Bokeh: setting log level to: 'info'
(program):53 Bokeh: injecting CSS: https://cdn.pydata.org/bokeh/release/bokeh-0.11.0.min.css
(program):55 Bokeh: injecting CSS: https://cdn.pydata.org/bokeh/release/bokeh-widgets-0.11.0.min.css
(program):72 Bokeh: BokehJS loaded, going straight to plotting

Could not open comm  --  Error: Class 1854dd25-3916-46bd-aab3-1729f21a403a not found in registry
main.min.js:23119 Couldn't process kernel message WrappedError(anonymous function) @ main.min.js:23119

Couldn't process kernel message WrappedError(anonymous function) @ main.min.js:23119

• [x] implement per-root layout solver
• [ ] make layout reinitializable

fixes #5967 ? #5518 ? #4810 fixes #4449

? #1650 -- not fixed because constraints are still bound to models, and there are other issues to resolve (e.g. we shouldn't touch plot.renderers).

This is really preliminary stuff.

• [x] pie chart
• [x] bar chart
• [ ] line chart
• [x] hover centered on slices, not glyph
• [x] hover glyph sometimes doesn't deactivate (tooltip hides properly)
• [ ] hover can affect only certain properties (e.g. can't change AnnularWedge's radius) (#2367)
• [x] tooltip attachment in the vertical dimension
• [x] Quad supports categorical axes
• [x] allow to anchor tooltip to Quad glyph's sides

Those are related:

• [ ] fix range_padding when constructing plots in JS
• [ ] DataRange1d should consider only visible part of AnnularWedge
• [ ] AnnularWedge.bounds() always returns [0, 0, 0, 0]

fixes #4311

This PR adds a range of draw tools, which allow adding and editing points, multi-lines, boxes and polygons, addressing https://github.com/bokeh/bokeh/issues/6370. For a demo of each of the tools go here (currently these use HoloViews but I'm working on pure bokeh examples now): https://anaconda.org/philippjfr/drawing_tools/notebook

BoxDrawTool

Allows drawing a rectangular bounding box, which will persist.

PointDrawTool

Allows adding points, dragging points and deleting points:

• Add: Click anywhere on the plot
• Drag: Click on the point and drag it
• Delete: Tap on point (or use box_select tool) and hit delete

PolyDrawTool

The tool handles drawing multiple polygons/multi-lines. Holding shift will allow editing the previously drawn polygon. Without holding shift a new polygon is added.

• Add polygon/multi-line: Drag from one point to another
• Add vertex to polygon: Hold shift then click and drag to new vertex position
• Delete: Tap on polygon/multi-line and hit delete

PolyEditTool

The vertex editing tools allow double clicking on a polygon/polyline and edit its vertices.

• Double Tap: Selects a polygon/polyline for vertex editing
• Drag: Clicking and dragging a vertex adjusts the polygon/polyline
• Delete: Tap on a vertex and press delete

API

The API generally is very simple, pass the renderers to be edited to each of the tools. The VertexEditTool also requires a separate vertex_renderer to draw the vertices.

ToDo

• [x] Agree on naming
• [x] Refactor a bit to reduce code duplication
• [x] Add docstrings
• [x] Add documentation and examples
• [x] Resolve remaining TypeScript issues
• [x] tests added / passed
• [x] release document entry (if new feature or API change)

• [x] add support for getters/setters (Object.defineProperty)
• [x] fix all clashes between unrelated this.prop and this.get("prop")
• [x] implement CoffeeScript/TypeScript mid-level API (bokeh.plotting)
  • [x] finalize edge cases
  • [x] add support for legends
  • [x] add support for tools
  • [ ] ~~add remaining API functions (io, hold, etc.)~~
• [x] TypeScript typings for low- and mid-level APIs
  • [x] add support for included properties (mixins with prefix)
  • [ ] make attrs in new Model(attrs) type-safe without too much code duplication
  • [ ] figure out how to remove string from Color union type
• [x] make gulp test work again
  • [x] fix unit tests
  • [ ] ~~add support for on-the-fly typescript compilation~~
• [x] add examples:
  • [x] low-level (bokehjs/examples/anscombe)
  • [x] mid-level (bokehjs/examples/burtin)

Note: to compile everything (scripts, typings and examples), issue gulp examples.

Reopened PR #5504 as bokeh/bokeh branch to allow running image diffs. This PR implements some of the suggestions in https://github.com/bokeh/bokeh/issues/2204. In further discussion and initial testing (see https://github.com/bokeh/bokeh/pull/5429) we found that simple base64 encoding offers huge performance gains compared to the current implementation. A more complex binary json format is therefore not necessary at this time.

Motivation

Currently sending large arrays to the browser can take a very long time, particularly when sending relatively large images. This is because all data is sent as raw strings, which is highly inefficient both in terms of size of the data that has to be sent to the frontend and in terms of processing because both backend and frontend iterate over the arrays to validate them. For a simple 2x2 image column data source the JSON representation would previously have looked like this:

{'image': [[[0.19593542932534513, 0.8104239473495675], [0.3907588555073921, 0.15267810064366616]]]}

the new JSON representation looks as follows:

{'image': [{'data': 'yKTPhb3b2j/Qy4BxlXzvP1bfkgIid9Q/kz0MlC4F4T8=', shape: [2,2], dtype: 'float64'}]}

In the case of a 2000x2000 image it took up to 30 seconds to serialize and send the image. Through initial investigation we found that simple base64 encoding of arrays can result in huge performance gains for sending array data via web sockets. Overall this has the potential to bring 10-50x improvements in sending large arrays via the comms in the notebook and will also offer some more limited improvements for bokeh server.

Design

1. The encoding should happen as a last step during serialization on the Python end and as the first step after deserialization on the JS end, ensuring no other code has to deal with base64 encoded data avoiding any backward compatibility issues.
2. The data should be wrapped in a simple JS object along ith the shape and type information. A dedicated model might be considered in future but is not necessary.
3. The column data source on the fronted will unpack and store the shape information on the _shapes attribute.
4. The encoding behavior should be configurable, e.g. do not encode unless the array is larger than a configurable size.
5. All numeric column data source data should potentially be encoded, i.e. both 1-D and 2-D arrays.

Caveats

Currently this PR will correctly encode and decode any numerical types except for numpy int64 arrays. Since there is no native 64-bit integer type in Javascript (internally ints are handled as double precision floats where the maximum safe integer is 2**53), we cannot directly encode and decode 64-bit integer data. Using the npm int64-buffer package I managed to decode an int64 ArrayBuffer but the advantages and disadvantages of various approaches should be evaluated in a subsequent PR:

view = new Int32Array(bytes)
array = []
for i in [0...view.length/2]
  int = new Int64LE(view.buffer.slice(i*8,(i+1)*8))
  array.push(int)

To-Do

• [x] Add configurable options BOKEH_USE_BINARY_ARRAYS and BOKEH_BINARY_ARRAY_CUTOFF and document them
• [x] Add server and client side decoding and encoding
• [x] Handle patch events
• [x] Handle stream events
• [ ] Ensure current tests pass and add extensive tests
• [ ] Add release document entry (if new feature or API change)

I'm getting an error installing bokeh 0.12.12. Previous versions install okay on my PC. I did a fresh install of Python 3.6.3 and deleted the pip cache directory first.

Windows 10 32-bit Python 3.6.3 32-bit

Running pip install yields:

> pip install bokeh==0.12.12
Collecting bokeh==0.12.12
  Using cached bokeh-0.12.12.tar.gz
Exception:
Traceback (most recent call last):
  File "k:\users\ed\appdata\local\programs\python\python36-32\lib\tarfile.py", line 2268, in utime
    os.utime(targetpath, (tarinfo.mtime, tarinfo.mtime))
OSError: [WinError 87] The parameter is incorrect

During handling of the above exception, another exception occurred:

Traceback (most recent call last):
  File "k:\users\ed\appdata\local\programs\python\python36-32\lib\site-packages\pip\basecommand.py", line 215, in main
    status = self.run(options, args)
  File "k:\users\ed\appdata\local\programs\python\python36-32\lib\site-packages\pip\commands\install.py", line 324, in run
    requirement_set.prepare_files(finder)
  File "k:\users\ed\appdata\local\programs\python\python36-32\lib\site-packages\pip\req\req_set.py", line 380, in prepare_files
    ignore_dependencies=self.ignore_dependencies))
  File "k:\users\ed\appdata\local\programs\python\python36-32\lib\site-packages\pip\req\req_set.py", line 620, in _prepare_file
    session=self.session, hashes=hashes)
  File "k:\users\ed\appdata\local\programs\python\python36-32\lib\site-packages\pip\download.py", line 821, in unpack_url
    hashes=hashes
  File "k:\users\ed\appdata\local\programs\python\python36-32\lib\site-packages\pip\download.py", line 663, in unpack_http_url
    unpack_file(from_path, location, content_type, link)
  File "k:\users\ed\appdata\local\programs\python\python36-32\lib\site-packages\pip\utils\__init__.py", line 605, in unpack_file
    untar_file(filename, location)
  File "k:\users\ed\appdata\local\programs\python\python36-32\lib\site-packages\pip\utils\__init__.py", line 581, in untar_file
    tar.utime(member, path)
  File "k:\users\ed\appdata\local\programs\python\python36-32\lib\tarfile.py", line 2270, in utime
    raise ExtractError("could not change modification time")
tarfile.ExtractError: could not change modification time

Some initial partial observations on Windows 7 with 0.11.0dev3 with python 2.7.11:

• sliders.py works
• fourier example does not animate
• stocks example does not update

Software versions

Python version : 3.9.5 (default, Jun 4 2021, 12:28:51) IPython version : (not installed) Tornado version : 6.1 Bokeh version : 3.0.3 BokehJS static path : /home/lele/.conda/envs/py3.9-torch1.9-opencv/lib/python3.9/site-packages/bokeh/server/static node.js version : v16.19.0 npm version : 8.19.2 Operating system : Linux-6.1.1-arch1-1-x86_64-with-glibc2.36

Browser name and version

Chrome Version 108.0.5359.124 (Official Build) (64-bit)

Jupyter notebook / Jupyter Lab version

No response

Expected behavior

Nothing is written in the browser console when changing the status of the CheckboxGroup (The callback seems to be not triggered).

Other example codes (i.e. the Switch) properly print in the browser console.

Observed behavior

Nothing happens.

Example code

from bokeh.io import show
from bokeh.models import CheckboxGroup, CustomJS

LABELS = ["Option 1", "Option 2", "Option 3"]

checkbox_group = CheckboxGroup(labels=LABELS, active=[0, 1])
checkbox_group.js_on_event('button_click', CustomJS(code="""
    console.log('checkbox_group: active=' + this.origin.active, this.toString())
"""))

show(checkbox_group)

Stack traceback or browser console output

No response

Screenshots

No response

Software versions

Python version : 3.8.12 (default, Jan 10 2022, 15:40:15) [MSC v.1916 64 bit (AMD64)] IPython version : (not installed) Tornado version : 6.1 Bokeh version : 3.0.3 BokehJS static path : C:\ProgramData\Anaconda3\envs\Py3.8\lib\site-packages\bokeh\server\static node.js version : (not installed) npm version : (not installed) Operating system : Windows-10-10.0.19044-SP0

Browser name and version

No response

Jupyter notebook / Jupyter Lab version

No response

Expected behavior

DatePicker showing up correctly.

Observed behavior

Whenever I use DatePicker in Bokeh 3, the entire layout of my dashboard seems to be broken (all widgets in a column with 100% width). Was OK in 2.x

Example code

import bokeh.plotting as bk
from bokeh.models.widgets import DatePicker, Select
from bokeh.layouts import row, column

p = bk.figure(width=600,
              height=600,
              title="Hello World!")
xs = [0,1,2,3,4,5]
ys = [x**2 for x in xs]

p.line(xs, ys, line_width=2)
s = Select(width=200)
dp = DatePicker(width=200)
b = column(s, dp, p)
#b = column(s, p)
bk.show (b)

Stack traceback or browser console output

No response

Screenshots

No response

Problem description

I think it would be helpful to include class inheritance diagrams in the sphinx docs. The API reference understandably contains a lot of text, I would like to break this up a bit with inheritance diagrams and I think it would help people who are visual learners (i.e. most bokeh users and contributors) to better understand the class structure.

Feature description

Inheritance diagrams in appropriate places in the docs. Particularly useful, so maybe a good starting place, would be bokeh.models.

Potential alternatives

Do nothing.

Additional information

There is a sphinx extension for this (https://www.sphinx-doc.org/en/master/usage/extensions/inheritance.html) but that requires graphviz to generate the diagrams. I understand there used to be some in bokeh but these were removed in 2016 (https://github.com/bokeh/bokeh/pull/4825).

I think it would be better for us to write our own sphinx extension to generate the diagrams, using our GraphRenderer, rather than require graphviz. The proposed new circumscribe glyphs, e.g. ellipse around contained text, would be useful here.

Software versions

Python version : 3.8.13 | packaged by conda-forge | (default, Mar 25 2022, 05:59:45) [MSC v.1929 64 bit (AMD64)] IPython version : 7.33.0 Tornado version : 6.2 Bokeh version : 3.0.0.dev20 BokehJS static path : C:\ProgramData\Anaconda3\envs\geo_env38v1\lib\site-packages\bokeh\server\static node.js version : (not installed) npm version : (not installed) Operating system : Windows-10-10.0.19044-SP0

Browser name and version

No response

Jupyter notebook / Jupyter Lab version

No response

Expected behavior

Changing the tooltips on a HoverTool via CustomJS does not result in the tooltip actually being updated in the plot.

Identified here: https://discourse.bokeh.org/t/update-tooltips-with-customjs-callback-function/9907/2,

Observed behavior

Looks like the tooltips property successfully updates according the console.log() statements, but the plot tooltip does not correspond.

Example code

from bokeh.plotting import figure, show
from bokeh.layouts import column
from bokeh.models import CustomJS, HoverTool, Select

f = figure()
f.scatter(x=[1,2,3],y=[1,2,3],size=5)

hvr=HoverTool(tooltips=[('A','$x')])

f.add_tools(hvr)

sel = Select(options=['A','B'],value='A')
cb = CustomJS(args=dict(hvr=hvr,sel=sel)
              ,code='''
              console.log(hvr)
              console.log(hvr.tooltips[0][0])
              hvr.tooltips[0][0]=sel.value
              console.log(hvr.tooltips[0][0])
              hvr.change.emit()              
              ''')
sel.js_on_change('value',cb)
show(column([f,sel]))

Stack traceback or browser console output

No response

Screenshots

No response

Early work in progress.

This PR:

• adds support for more GL glyphs (Annulus, Wedge, AnnularWedge and Ellipse)
• simplifies loading of GL glyphs in base glyphs (greatly reduced code duplication)
• greatly reduces code duplication and complexity in GL glyphs (in _set_data(), etc.)
• improves handling of settings.force_webgl in tests

TODO:

• [ ] resolve issues with GL attribute number limitations

This adds rudimentary support for item fill policies:

import numpy as np

from bokeh.plotting import figure, show

x = np.linspace(0, 4*np.pi, 50)
y = np.sin(x)

TOOLS = "pan,wheel_zoom,box_zoom,reset,save,box_select"

p1 = figure(title="Legend Example", tools=TOOLS, width=300, height=300)

p1.circle(x, 1*y, legend_label="1*sin(x)", fill_color=None, line_color="green")

p1.square(x, 2*y, legend_label="2*sin(x)", fill_color=None, line_color="orange")
p1.line(x, 2*y, legend_label="2*sin(x)", line_color="orange")

p1.circle(x, 3*y, legend_label="3*sin(x)", fill_color=None, line_color="blue")

p1.square(x, 4*y, legend_label="4*sin(x)", fill_color=None, line_color="tomato")
p1.line(x, 4*y, legend_label="4*sin(x)", line_color="tomato")

p1.circle(x, 5*y, legend_label="5*sin(x)", fill_color=None, line_color="purple")

p1.square(x, 6*y, legend_label="6*sin(x)", fill_color=None, line_color="pink")
p1.line(x, 6*y, legend_label="6*sin(x)", line_color="pink")

p1.legend.title = 'Markers'
p1.legend.ncols = 2
p1.legend.orientation = "vertical"
p1.legend.click_policy = "mute"
p1.legend.title_location = "above"
p1.legend.item_background_policy = "even"
show(p1)

fixes #12692

/cc @mosc9575