plot_topology_graph

plot_topology_graph#

class braintools.visualize.morphology.plot_topology_graph(graph, *, frame=None, 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 TopologyGraph as a topology-only graph.

Parameters:
  • graph (Any) – The graph, or an object implementing __topology_data__() (for example a simulator’s solver-node tree).

  • frame (int | None) – Frame of graph.values to draw; required when the values are two-dimensional (T, N).

  • 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. Defaults to graph.highlight_fractions; giving both is an error.

  • 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-node scalar values for value colouring, aligned with graph.node_ids. Defaults to graph.values; giving both is an error.

  • 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; defaults to graph.value_label.

  • 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 graph is not a TopologyGraph and does not implement __topology_data__().

  • ValueError – If the layout or layout scale is invalid, highlight mode is combined with value mode, values or highlight fractions are given both in graph and as arguments, two-dimensional values come without frame, or a level="branch" graph receives a colour-map argument (branch graphs are topology-only).

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

>>> import numpy as np
>>> import brainunit as u
>>> from braintools.visualize.morphology import TopologyGraph, plot_topology_graph
>>> graph = TopologyGraph(
...     node_ids=(0, 1, 2, 3), edges=((0, 1), (1, 2), (1, 3)), root_id=0,
...     values=np.array([-65.0, -60.0, -55.0, -50.0]) * u.mV, value_label="V",
... )
>>> ax = plot_topology_graph(graph, layout="kamada_kawai", cmap="plasma")
>>> len(ax.collections) > 0
True