Use any Glyph to draw network nodes

[rambip]

Problem description

In the documentation, there is no example of using something else than models.Ellipse. But it would be very useful to use other shapes, for example model.Block or model.Quad.
In addition, the current layout_provider does not help to get a mental model of how to do it.
Indeed, if the user tries to put the coordinate data directly into the node renderer without specifying a layout_provider, he will get an error.

Feature description

A way to specify how the graph coordinates are translated into the glyph, and a corresponding example in the docs.

Potential alternatives

At least, a way to turn off the layout_provider and put directly the coordinates in node_renderer.data_source.data. Currently, if layout_provider is empty, I get a blank figure in any case.

Additional information

No response

[bryevdv]

@rambip Thanks for the issues. The relevant line from the docs is this:

Bokeh comes with a built-in LayoutProvider model that includes a dictionary of (x,y) coordinates for nodes.

And what is meant implicitly here is that any glyph that has x and y coordinate properties can be used here. E.g. in the example in the docs you can just replace Ellipse with Rect and get the ouput:

But any scatter marker with x and y coordinates would also work, etc. But things quad would not work out of the box, because they accept different inputs than x and y. There might be some ways to make those work with property transforms and extra columns but it will require some investigation.

In any case it seems the docs could be more clear about the expectation for x and y based coordinate glyphs. Would you like to submit a PR to improve things? The relevant file is here:

https://github.com/bokeh/bokeh/blob/branch-3.9/docs/bokeh/source/docs/user_guide/topics/graph.rst

[rambip]

I would be happy to do it, but I would like to know how it works under the wood before writing an explanation,
Is there a reason why the user has to specify the positions inside a layout_provider and not just inside node_rendere.data_source ?
What files should I look at to understand ?

[bryevdv]

Is there a reason why the user has to specify the positions inside a layout_provider and not just inside node_rendere.data_source

The data in the node_renderer and edge_renderer data sources specify just the nodes and their relationships, as well as any per-node or per-edge attribute data, independent of any geometry. So, e.g. looking at the networkx example in the docs we can see:

In [32]: graph.node_renderer.data_source.data
{'index': [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15, 16, 17, 18, 19]}

In [33]: graph.edge_renderer.data_source.data
{'end': [1, 19, 5, 2, 16, 3, 11, 4, 14, 5, 9, 6, 7, 15, 8, 18, 9, 13, 10, 11, 19, 12, 13, 17, 14, 15, 16, 17, 18, 19],
 'start': [0, 0, 0, 1, 1, 2, 2, 3, 3, 4, 4, 5, 6, 6, 7, 7, 8, 8, 9, 10, 10, 11, 12, 12, 13, 14, 15, 16, 17, 18]}

So there are twenty nodes, labeled simply 0–19, and then you can see that node 0 is connected to nodes 1, 19 and 5, etc. If we wanted to have additional non-geometric data, e.g. a temperature for each node or a weight for each edge, that data could also go in these data sources (useful to be show in hover tools, say).

It is common to fundamentally represent graphs in this "pure" way that does not make reference to any concrete locations for nodes or line paths for edges. So then the idea behind a LayoutProvider is that it is a thing that can be combined with the "pure" graph structure, to actually draw real shapes in some coordinate system. In principle, Bokeh could have "smart" layout providers that don't need any configuration from users. For instance there could be a ForceDirectedLayoutProvider that just automatically generates a Force-Directed Graph layout. There are lots of different Graph Drawing Methods that could be the basis for new layout providers in Bokeh.

However, as history would have it, the only layout provider that has been implemened so far is the StaticLayoutProvider and that layout provider is one that just says "I don't do anything automatically, you tell me where each node and edge should go". And the main reason for that is just that when graph support was initially added to Bokeh, there had to be some layout provider option, and a "static" one was the simplest to implement, and could also be used as a pass-through for geometric layouts provided by other tools like NetworkX. In other words, StaticLayoutProvider was "good enough for now" and that has continued to be the case.

I'd love to see newer, fancier, dynamic layout providers added to Bokeh. That would make it much easier to have graphs that react automatically if nodes or edges are added or removed at runtime. Or the layout algorithm itself could be made user-selectable, for instance. But adding new layout provider is probably be contingent on a new contributor with a specific interest in graph drawing to come along and decide to contribute their time and effort to make it happen.

In terms of looking at files, like most everything in Bokeh, almost all the actual work is done in the browser, in javascript. You can see some relevant source files here:

• layout_provider.ts — base class for layout providers
• static_layout_provider.ts — concrete implementation of the static layout profider
• graph_renderer.ts — renderer that uses a layout provider to supply concrete coodindates for its node and edge renderers to actually use to draw

[rambip]

Ok, makes sense !
Thank's for the detailed answer.
I will edit the documentation for graph and link to the scatter docs, since it would have helped me a lot.
As for the javascript graph layouts, I might give it a try if I have time. I already have implemented force-directed layout in rust (and I think there are great crates on this subject). Does bokeh ship wasm modules, and is it a problem if it starts shipping them ? (Bundle size, compatibility ...)

[bryevdv]

@rambip We have a somewhat complicated build/bundle system and currently everything is just geared towards compiling TypeScript. I am pretty sure that @mattpap is interested in WASM for the future but I don't know that he has gotten beyond some initial experiments here and there, and any further work down that path would need close collaboration with him. I'd suggest sticking to the existing system for the quickest/easiest time in the short term.

[mattpap]

An alternative is to use Text glyph with outline_shape (currently supported shapes are "none", "box", "rectangle", "square", "circle", "ellipse", "trapezoid", "parallelogram", "diamond", "triangle") and empty text (if you want only the shape). This is a fairly new feature, with some important limitations (e.g. hit testing only works on the bounding box of a shape) and not well documented.