navis.plot3d¶
- navis.plot3d(x, **kwargs)[source]¶
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 plotmultiple 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 (if available) andplotly
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. Uselist
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 avmin
and/orvmax
parameter.shade_by (str | array | list of arrays, default=None) – Similar to
color_by
but will affect only the alpha channel of the color. Ifshade_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 asmin
and/orsmax
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]
). Overridescolor
and usespalette
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 dotscolor
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 forTreeNeurons
.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 returnsnavis.Viewer
.If
backend='plotly'
– Returns eitherNone
if you are in a Jupyter notebook (see alsoinline
parameter) or aplotly.graph_objects.Figure
(see examples).If
backend='k3d'
– Returns eitherNone
and immediately displays the plot or ak3d.plot
object that you can manipulate further (seeinline
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.