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	x	y	z	radius	parent_id	type
0	1	15784.0	37250.0	28102.0	10.0000	-1	root
1	2	15764.0	37230.0	28102.0	18.2843	1	slab
2	3	15744.0	37190.0	28142.0	34.7214	2	slab
3	4	15744.0	37150.0	28182.0	34.7214	3	slab
4	5	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()

For more advanced stuff (plotting, pruning, cutting, NBLAST, etc.) have a look at the example gallery.