braincell.vis.plot_point_topology

braincell.vis.plot_point_topology#

braincell.vis.plot_point_topology(node_tree, *, preset='dendrotweaks', layout=None, layout_scale=1.0, highlight_point_ids=None, highlight_fractions=None, coverage_mode='fraction', highlight_color='#ef4444', color_mode=None, values=None, cmap=None, vmin=None, vmax=None, norm=None, value_label=None, value_unit_label=None, show_colorbar=True, node_color=None, edge_color=None, root_color=None, ax=None)[source]#

Render a NodeTree as a topology-only graph.

Parameters:

  • node_tree (NodeTree) – Declaration-time node tree to render.

  • preset (str) – Name of the built-in style preset. Presets bundle default layout and colour settings.

  • layout (str | None) – Explicit layout algorithm override. When None, uses the layout implied by preset.

  • layout_scale (float) – Global spacing multiplier for the resolved layout. This scales the full node layout; it does not alter pairwise target distances.

  • highlight_point_ids (iterable of int or None, optional) – Point ids to highlight. Highlight mode is mutually exclusive with values mode in v1.

  • highlight_fractions (dict[int, float] | None) – Per-node highlight fractions in [0, 1]. When supplied, coverage-style colouring is used instead of discrete point-id highlighting.

  • coverage_mode (Literal['fraction', 'any', 'all']) – Interpretation of highlight_fractions.

  • highlight_color (str) – Colour used for highlighted points.

  • color_mode (Literal['solid', 'depth', 'values'] | None) – Node colouring mode. None means “infer from values or preset”.

  • values (array-like or Quantity, optional) – Per-point scalar values for value colouring.

  • cmap (str | None) – Matplotlib colormap name used in value mode.

  • vmin (float | None) – Explicit lower and upper bounds for the value colormap.

  • vmax (float | None) – Explicit lower and upper bounds for the value colormap.

  • norm (matplotlib.colors.Normalize or None, optional) – Explicit normalization object for value mode.

  • value_label (str | None) – Colorbar label text.

  • value_unit_label (str | None) – Explicit unit label appended to the colorbar label.

  • show_colorbar (bool) – If True (default), draw a colorbar in value mode.

  • node_color (str | None) – Base node colour override.

  • edge_color (str | None) – Edge colour override.

  • root_color (str | None) – Root node colour override.

  • ax (matplotlib.axes.Axes or None, optional) – Destination axes. When None, a fresh figure and axes are created.

Returns:

The rendered Matplotlib axes.

Return type:

Any

Raises:

  • TypeError – If node_tree is not a NodeTree.

  • ValueError – If the node tree is empty, the layout is invalid, the layout scale is invalid, or highlight mode is combined with value mode.

Notes

Supported layouts in the current wrapper are "twopi", "dot", "neato", and "kamada_kawai". Graphviz-backed layouts fall back to "kamada_kawai" with a warning when Graphviz is unavailable.

Examples

Render with the default preset:

>>> ax = plot_point_topology(node_tree)

Render with explicit value colouring:

>>> ax = plot_point_topology(
...     node_tree,
...     values=point_values,
...     cmap="plasma",
...     value_label="Voltage",
... )