navis 1.4.0
  • Install
  • Quickstart
  • Tutorials
  • API
  • Changelog
  • Github
  • Ecosystem
  • Site
    • Page
        • navis.plot3d
          • plot3d()

    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 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 (if available) 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.

    Back to top

    Source

    © Copyright 2018, Philipp Schlegel.
    Created using Sphinx 5.3.0.