navis.plot3d

navis.plot3d(x, **kwargs)

Generate 3D plot.

Uses either vispy, k3d or plotly. By default, the choice is automatic and depends on context:

terminal: vispy used
Jupyter: plotly used

See backend parameter on how to change this behavior.

Parameters

• x (Neuron/List | Volume | numpy.array) –

  • numpy.array (N,3) is plotted as scatter plot

  • multiple objects can be passed as list (see examples)

• backend ('auto' | 'vispy' | 'plotly' | 'k3d', default='auto') –

  Which backend to use for plotting. Note that there will be minor differences in what feature/parameters are supported depending on the backend:

  • auto selects backend based on context: vispy for terminal and plotly for Jupyter environments. You can override this by setting an environment variable NAVIS_JUPYTER_PLOT3D_BACKEND=”k3d”.

  • vispy uses OpenGL to generate high-performance 3D plots. Works in terminals.

  • plotly generates 3D plots using WebGL. Works “inline” in Jupyter notebooks but can also produce a html file that can be opened in any browers.

  • k3d generates 3D plots using k3d. Works only in Jupyter notebooks!

• connectors (bool, default=False) – Plot connectors (e.g. synapses) if available.

• color (None | str | tuple | list | dict, default=None) – Use single str (e.g. 'red') or (r, g, b) tuple to give all neurons the same color. Use list of colors to assign colors: ['red', (1, 0, 1), ...]. Use ``dict to map colors to neurons: {neuron.id: (r, g, b), ...}.

• cn_colors (str | tuple | dict | "neuron") –

  Overrides the default connector (e.g. synpase) colors:

  • single color as str (e.g. 'red') or rgb tuple (e.g. (1, 0, 0))

  • dict mapping the connectors tables type column to a color (e.g. {“pre”: (1, 0, 0)})

  • with “neuron”, connectors will receive the same color as their neuron

• palette (str | array | list of arrays, default=None) – Name of a matplotlib or seaborn palette. If color is not specified will pick colors from this palette.

• color_by (str | array | list of arrays, default = None) – Can be the name of a column in the node table of TreeNeurons or an array of (numerical or categorical) values for each node. Numerical values will be normalized. You can control the normalization by passing a vmin and/or vmax parameter.

• shade_by (str | array | list of arrays, default=None) – Similar to color_by but will affect only the alpha channel of the color. If shade_by='strahler' will compute Strahler order if not already part of the node table (TreeNeurons only). Numerical values will be normalized. You can control the normalization by passing a smin and/or smax parameter. Does not work with k3d backend.

• alpha (float [0-1], optional) – Alpha value for neurons. Overriden if alpha is provided as fourth value in color (rgb*a*).

• clusters (list, optional) – A list assigning a cluster to each neuron (e.g. [0, 0, 0, 1, 1]). Overrides color and uses palette to generate colors according to clusters.

• radius (bool, default=False) – If True, will plot TreeNeurons as 3D tubes using the radius column in their node tables.

• width/height (int, optional) – Use to adjust figure/window size.

• scatter_kws (dict, optional) –

  Use to modify scatter plots. Accepted parameters are:

  • size to adjust size of dots

  • color to adjust color

• soma (bool, default=True) – Whether to plot soma if it exists (TreeNeurons only). Size of the soma is determined by the neuron’s .soma_radius property which defaults to the “radius” column for TreeNeurons.

• inline (bool, default=True) –

  If True and you are in an Jupyter environment, will render plotly/k3d plots inline. If False, will generate and return either a plotly Figure or a k3d Plot object without immediately showing it.

  Below parameters are for plotly backend only:

• fig (plotly.graph_objs.Figure) – Pass to add graph objects to existing plotly figure. Will not change layout.

• title (str, default=None) – For plotly only! Change plot title.

• fig_autosize (bool, default=False) – For plotly only! Autoscale figure size. Attention: autoscale overrides width and height

• hover_name (bool, default=False) – If True, hovering over neurons will show their label.

• hover_id (bool, default=False) – If True, hovering over skeleton nodes will show their ID.

• legend_group (dict, default=None) –

  A dictionary mapping neuron IDs to labels (strings). Use this to group neurons under a common label in the legend.

  Below parameters are for the vispy backend only:

• clear (bool, default = False) – If True, will clear the viewer before adding the new objects.

• center (bool, default = True) – If True, will center camera on the newly added objects.

• combine (bool, default = False) – If True, will combine objects of the same type into a single visual. This can greatly improve performance but also means objects can’t be selected individually anymore.

Return type

Union[Viewer, dict, None]

Returns

• If backend='vispy' – Opens a 3D window and returns navis.Viewer.

• If backend='plotly' – Returns either None if you are in a Jupyter notebook (see also inline parameter) or a plotly.graph_objects.Figure (see examples).

• If backend='k3d' – Returns either None and immediately displays the plot or a k3d.plot object that you can manipulate further (see inline parameter).

See also

navis.Viewer

Interactive vispy 3D viewer. Makes it easy to add/remove/select objects.

Examples

>>> import navis

In a Jupyter notebook using plotly as backend.

>>> import plotly.offline
>>> nl = navis.example_neurons()
>>> # Backend is automatically chosen but we can set it explicitly
>>> # Plot inline
>>> nl.plot3d(backend='plotly')                             
>>> # Plot as separate html in a new window
>>> fig = nl.plot3d(backend='plotly', inline=False)
>>> _ = plotly.offline.plot(fig)                            

In a Jupyter notebook using k3d as backend.

>>> nl = navis.example_neurons()
>>> # Plot inline
>>> nl.plot3d(backend='k3d')                                

In a terminal using vispy as backend.

>>> # Plot list of neurons
>>> nl = navis.example_neurons()
>>> v = navis.plot3d(nl, backend='vispy')
>>> # Clear canvas
>>> navis.clear3d()

Some more advanced examples:

>>> # plot3d() can deal with combinations of objects
>>> nl = navis.example_neurons()
>>> vol = navis.example_volume('LH')
>>> vol.color = (255, 0, 0, .5)
>>> # This plots a neuronlists, a single neuron and a volume
>>> v = navis.plot3d([nl[0:2], nl[3], vol])
>>> # Clear viewer (works only with vispy)
>>> v = navis.plot3d(nl, clear3d=True)

See the plotting tutorial for even more examples.