braincell.vis.plot_cell_topology

braincell.vis.plot_cell_topology#

braincell.vis.plot_cell_topology(cell, *, level='node', preset='dendrotweaks', layout=None, layout_scale=1.0, region=None, locset=None, coverage_mode='fraction', highlight_color='#ef4444', value=None, cmap=None, vmin=None, vmax=None, norm=None, value_label=None, show_colorbar=True, node_color=None, edge_color=None, root_color=None, ax=None)[source]#

Draw a cell’s topology at the node, CV, or branch level.

Parameters:

  • cell (Cell) – Cell to render. level="node" requires an initialized cell; "cv" and "branch" also work on a declaration-only cell.

  • level (Literal['node', 'cv', 'branch']) – Topology abstraction level. One node per runtime point, per control volume, or per morphology branch respectively.

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

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

  • layout_scale (float) – Global spacing multiplier for the resolved layout.

  • region (RegionExpr | RegionMask | None) – Continuous morphology selection to highlight. At level="node" and "cv" the selection is reduced to CV granularity; at level="node" each selected CV is attributed to its midpoint point.

  • locset (LocsetExpr | LocsetMask | None) – Discrete morphology locations to highlight, each mapped to the CV that owns it. Not supported at level="branch".

  • coverage_mode (Literal['fraction', 'any', 'all']) – Coverage display rule for region. "fraction" blends by overlap fraction, "any" highlights any overlap fully, and "all" only highlights fully covered nodes. Locset-backed highlights are always full intensity.

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

  • value (object, optional) –

    Colouring source. Not supported at level="branch". Supported forms are:

    • an array in the level’s own space (n_point or n_cv)

    • an array in the other space, which is mapped across

    • "V" or "voltage"

    • ("ion", ion_name, field)

    • ("channel", class_name, field)

    • ("layout_id", layout_id, field)

    value is mutually exclusive with region / locset.

  • 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 override. When None, named value selectors infer a label automatically.

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

  • node_color (str | None) – Base style colour overrides.

  • edge_color (str | None) – Base style colour overrides.

  • root_color (str | None) – Base style colour overrides.

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

Returns:

The rendered axes. Call matplotlib.pyplot.show() to display it; like every other braincell.vis entry point this function does not display on your behalf.

Return type:

Any

Raises:

  • TypeError – If cell is not a Cell.

  • ValueError – If level is not one of the three known levels; if level="branch" is combined with a parameter it does not support; if value is combined with region / locset; if level="cv" is used on a cell without exactly one root CV; or if a supplied value source cannot be mapped into the level’s space.

  • RuntimeError – If level="node" is used before init_state().

See also

braincell.vis.plot_topology

Branch-order schematic of a Morphology, drawn without a cell and ignoring segment lengths — a different rendering of a different object.

braincell.vis.plot_point_topology

The underlying renderer, taking a bare NodeTree and pre-resolved highlight or value arrays.

Notes

Highlight mode (region / locset) and value mode (value) are mutually exclusive. Region and locset mappings use CV midpoint semantics, matching the runtime lowering model.

level="branch" is topology-only: it accepts region for coverage but rejects locset, value, and every value-colormap parameter, because a branch spans many CVs and so carries no single runtime value.

Examples

Colour the node topology by membrane voltage:

>>> import braincell as bc
>>> import matplotlib.pyplot as plt
>>> ax = bc.vis.plot_cell_topology(cell, value="V", cmap="viridis")
>>> plt.show()

Highlight a region at control-volume level:

>>> ax = bc.vis.plot_cell_topology(
...     cell, level="cv", region=bc.filter.BranchSlice(1, 0.0, 0.5)
... )

Show which branches a region covers:

>>> ax = bc.vis.plot_cell_topology(cell, level="branch", region=region)

Colour nodes by a channel parameter:

>>> ax = bc.vis.plot_cell_topology(
...     cell, value=("channel", "IL", "g_max")
... )