braintools.visualize.morphology module#

Morphology, topology and value plots driven by neutral data.

The plots take MorphologyData (a tree of BranchData) or TopologyGraph, or any object implementing __morphology_data__() / __topology_data__(); a simulator converts its own objects, so this package imports none. It is not imported by import braintools:

import braintools.visualize.morphology as bvm

Matplotlib renders the 2-D plots. networkx (topology-graph layouts), PyVista and Plotly (3-D) are optional: pip install braintools[morphology].

Plots of neuron morphologies, discrete topology graphs (branches, control volumes, solver nodes) and values over them. The plots never read a simulator’s objects: they take the neutral, frozen data types below, or any object implementing __morphology_data__() / __topology_data__(), so a simulator only has to convert its own objects. This module is not imported by import braintools; import it explicitly:

import braintools.visualize.morphology as bvm

Matplotlib draws every 2-D plot. Topology-graph layouts need networkx, and 3-D rendering needs PyVista or Plotly; install them with pip install braintools[morphology].

Data#

Geometry is stored in micrometres as read-only host arrays. Branches are identified by index (their position) and name (unique, and stable across edits of the source morphology); graph nodes by integer identifiers.

BranchData

Geometry and attachment of one unbranched section of a morphology.

MorphologyData

A tree of BranchData, the input of every morphology plot.

RegionData

A continuous selection of a morphology, as branch intervals.

LocsetData

Discrete locations on a morphology.

TopologyGraph

A rooted graph with optional per-node values or highlight fractions.

as_morphology_data

Return obj as MorphologyData.

as_topology_graph

Return obj as TopologyGraph.

Morphology plots#

2-D layouts (fan, stem, balloon, radial_360, projected), 3-D rendering, comparisons, time series and animations. Values are given per branch, per segment or per centerline point; ValueSpec carries the colour settings and, optionally, the value space.

plot2d

Draw a morphology in 2-D with Matplotlib.

plot3d

Render a morphology in 3-D with PyVista or Plotly.

compare_morphologies

Render several morphologies side by side with a shared layout.

compare_values

Render the same morphology with multiple value overlays.

plot_traces

Plot time-series traces at selected morphology locations.

TracesResult

Axes handles returned from plot_traces().

plot_movie

Render a time-varying colour-by-values animation over a morphology.

MovieResult

Artifacts returned from plot_movie().

ValueSpec

Styling parameters for a color-by-values overlay.

OverlaySpec

User-facing overlay request passed through plot2d / plot3d.

Structure#

Tree schematics and morphometry of a morphology, and the discrete topology graph drawn with a graph layout (unlike braintools.visualize.network_topology(), which draws an adjacency matrix).

plot_dendrogram

Render a left-to-right dendrogram of the morphology.

plot_topology

Render a topology-only schematic (length-ignored) of the morphology.

plot_sholl

Plot a Sholl-intersection curve.

plot_branch_order_histogram

Bar chart of the number of branches per branch order.

plot_topology_graph

Render a TopologyGraph as a topology-only graph.

Layout, style and interaction#

Layout parameters and the layout cache, global plot defaults and themes (publication_theme sets both the morphology colours and Matplotlib rcParams; braintools.visualize.publication_style() sets rcParams only), pick callbacks, and figure export for every backend.

LayoutConfig

Configurable parameters for the 2D layout engine.

LayoutCache

Size-bounded LRU cache for layout-branch builder results.

VisDefaults

configure_defaults

get_defaults

reset_defaults

theme

Temporarily override visualization defaults for the duration of a block.

publication_theme

Activate the PublicationTheme for the duration of a block.

PublicationTheme

Publication-quality styling preset for braintools.visualize.morphology.

VisHooks

Bundle of interactive callbacks understood by the vis backends.

PickInfo

Payload delivered to a VisHooks callback.

save_figure

Save a vis backend return value to disk.

Constants#

braintools.visualize.morphology.PUBLICATION_BRANCH_TYPE_COLORS#

Branch-type colours (RGB, 0-255) of publication_theme(), from Paul Tol’s colour-blind-safe palette; the keys are the branch types ("soma", "axon", "basal_dendrite", "apical_dendrite", "dendrite", "custom").

braintools.visualize.morphology.PUBLICATION_RC_PARAMS#

Matplotlib rcParams applied by publication_theme(): serif font, thicker lines, no grid and tight margins, tuned for export at 300 dpi.