Quickstart

This tutorial will show you the basics of how to use NAVis. This is not supposed to be comprehensive but rather to give you a flavor of how things work. For inspiriation, explore the example gallery and for detailed explanations have a look at the API documentation.

Single Neurons

NAVis lets you import neurons from a variety of local and remote sources. For demonstration purposes NAVis comes with a bunch of fruit fly neurons from the Janelia hemibrain project:

import navis

n = navis.example_neurons(n=1, kind='skeleton')
n
type navis.TreeNeuron
name 1734350788
id 1734350788
n_nodes 4465
n_connectors 2705
n_branches 599
n_leafs 618
cable_length 266476.875
soma [4177]
units 8 nanometer

In above code we loaded one of the example neurons. NAVis represents neurons as TreeNeuron, MeshNeuron, VoxelNeuron or Dotprops. In this example we asked for a skeleton, so the neuron returned is a TreeNeuron. This class is essentially a wrapper around the actual neuron data (the SWC table in this case) and has some convenient features.

Node data is stored as pandas.DataFrame:

n.nodes.head()
node_id label x y z radius parent_id type
0 1 0 15784.0 37250.0 28102.0 10.0000 -1 root
1 2 0 15764.0 37230.0 28102.0 18.2843 1 slab
2 3 0 15744.0 37190.0 28142.0 34.7214 2 slab
3 4 0 15744.0 37150.0 28182.0 34.7214 3 slab
4 5 0 15704.0 37130.0 28242.0 34.7214 4 slab

Note

Pandas pandas is the data science library for Python and will help you analyze and visualize your data. I highly recommend familiarizing yourself with pandas! There are plenty of good tutorials out there but pandas’ own 10 Minutes to pandas is a good place to start.

Try typing in “n.” and hitting tab: most attributes and functions are accessible via autocompletion. If you don’t know what a function does, check out the documentation using help() or via the API documentation:

help(navis.TreeNeuron.root)

Help on property:

    Root node(s).

help(navis.TreeNeuron.downsample)

Help on function downsample in module navis.core.neurons:

downsample(self, factor=5, inplace=False, **kwargs)
    Downsample the neuron by given factor.

    Parameters
    ----------
    factor :                int, optional
                            Factor by which to downsample the neurons.
                            Default = 5.
    inplace :               bool, optional
                            If True, operation will be performed on
                            itself. If False, operation is performed on
                            copy which is then returned.
    **kwargs
                            Additional arguments passed to
                            downsample_neuron().

    See Also
    --------
    downsample_neuron()
        Base function. See for details and examples.

You will notice that many NAVis functions that accept neurons have an inplace parameter. This is analogous to pandas:

# Downsample a copy, leaving the original unchanged
# (this is the default for almost all functions)
n_ds = n.downsample(10, inplace=False)

# Downsample the original neuron
n_ds2 = n.copy()
n_ds2.downsample(10, inplace=True)

n_ds2
type TreeNeuron
name neuron_38885
n_nodes 867
n_connectors 0
n_branches 235
n_leafs 243
cable_length 1.02046e+06
soma [3490]

TreeNeuron functions such as .downsample() are shorthands for calling the actual NAVis functions. So above code is equivalent to:

n_ds = navis.downsample_neuron(n, downsampling_factor=10, inplace=False)
n_ds
type TreeNeuron
name neuron_38885
n_nodes 867
n_connectors 0
n_branches 235
n_leafs 243
cable_length 1.02046e+06
soma [3490]

Lists of Neurons

For multiple neurons, NAVis uses NeuronList:

nl = navis.example_neurons(n=3, kind='skeleton')
nl
<class 'navis.core.neuronlist.NeuronList'> containing 3 neurons (875.1KiB)
type name id n_nodes n_connectors n_branches n_leafs cable_length soma units
0 navis.TreeNeuron 1734350788 1734350788 4465 2705 599 618 266476.87500 [4177] 8 nanometer
1 navis.TreeNeuron 1734350908 1734350908 4847 3042 735 761 304332.65625 [6] 8 nanometer
2 navis.TreeNeuron 722817260 722817260 4332 3136 633 656 274703.37500 None 8 nanometer

NeuronList is a container and behaves like a glorified list:

nl[0]
type TreeNeuron
name neuron_38885
n_nodes 6365
n_connectors 0
n_branches 235
n_leafs 243
cable_length 1.21335e+06
soma [3490]

NeuronList lets you run/access all functions (methods) and properties of the neurons it contrains:

nl.cable_length

array([266458.00615559, 304277.01267831, 274910.5606301 ])

nl_ds = nl.downsample(10, inplace=False)

nl_ds
type name id n_nodes n_connectors n_branches n_leafs cable_length soma units
0 TreeNeuron 1734350788 1734350788 1309 None 603 619 247375.660645 [4176] 8 nanometer
1 TreeNeuron 1734350908 1734350908 1555 None 733 760 282432.973650 [6] 8 nanometer
2 TreeNeuron 722817260 722817260 1350 None 635 658 254958.940182 None 8 nanometer

Let’s finish this primer with some eye candy

fig = nl.plot3d()