Quickstart#
This short introduction will show you the basics of how to use NAVis. This is not supposed to be comprehensive but rather to give you an idea of the basic concepts. For inspiration, explore the example gallery and for detailed explanations have a look at the API documentation.
Single Neurons#
For demonstration purposes NAVis comes with a bunch of fruit fly neurons from the Janelia hemibrain project:
import navis
# Load a single example neuron
n = navis.example_neurons(n=1, kind='skeleton')
n
type navis.TreeNeuron
name DA1_lPN_R
id 1734350788
n_nodes 4465
n_connectors 2705
n_branches 599
n_leafs 618
cable_length 266476.875
soma 4177
units 8 nanometer
created_at 2024-10-24 11:36:55.910763
origin /home/runner/work/navis/navis/navis/data/swc/1...
file 1734350788.swc
dtype: object
Loading your own neurons
Almost all tutorials will use the example neurons shipped with NAVis (see navis.example_neurons for details).
You will most likely want to load your own neuron data. NAVis has dedicated functions such as navis.read_swc for that . Check out the I/O Tutorials to learn more!
NAVis represents neurons as navis.TreeNeuron, navis.MeshNeuron, navis.VoxelNeuron or navis.Dotprops - see the tutorial on Neuron Types for details.
In above code we asked for a skeleton, so the neuron returned is a TreeNeuron. Like all neuron types, this class is essentially a wrapper around the actual neuron data (the node table in case of skeletons) and has some convenient features.
The skeleton's 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 28062.0 10.000000 -1 root
1 2 0 15764.0 37230.0 28082.0 18.284300 1 slab
2 3 0 15744.0 37190.0 28122.0 34.721401 2 slab
3 4 0 15744.0 37150.0 28202.0 34.721401 3 slab
4 5 0 15704.0 37130.0 28242.0 34.721401 4 slab
Pandas
pandas is the data science library for Python and will help you analyze and visualize your data. We 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.
Once you have your neuron loaded in NAVis things are as simple as passing it to the function that does what you need:
fig, ax = navis.plot2d(n, view=('x', '-z'), color="coral", method='2d')
Lists of Neurons#
When working with multiple neurons, NAVis uses navis.NeuronLists:
# Ask for 3 example neurons
nl = navis.example_neurons(n=3, kind='skeleton')
nl
<class 'navis.core.neuronlist.NeuronList'> containing 3 neurons (875.1KiB)
type ... file
0 navis.TreeNeuron ... 1734350788.swc
1 navis.TreeNeuron ... 1734350908.swc
2 navis.TreeNeuron ... 722817260.swc
navis.NeuronLists are containers and behave like a list (with some extras, of course):
# Access the first neuron in the list
nl[0]
type navis.TreeNeuron
name DA1_lPN_R
id 1734350788
n_nodes 4465
n_connectors 2705
n_branches 599
n_leafs 618
cable_length 266476.875
soma 4177
units 8 nanometer
created_at 2024-10-24 11:36:56.111337
origin /home/runner/work/navis/navis/navis/data/swc/1...
file 1734350788.swc
dtype: object
navis.NeuronLists provide quick and convenient access to all functions (methods) and properties of the neurons it contains:
# Get the cable length for all neurons in the list
nl.cable_length
[266476.88 304332.66 274703.38]
Most functions that accept single neurons, also happily work with NeuronLists:
# Generate a plot of our neurons
fig, ax = navis.plot2d(nl, view=('x', '-z'), method='2d')
See the Lists of Neurons tutorial for more information.
Methods vs Functions#
NAVis neurons and neuron lists have methods that serve as shortcuts to main functions.
These code snippets are equivalent:
import navis
s = navis.example_neuron(n=1, type='skeleton')
ds = navis.downsample_neuron(s, 5)
import navis
s = navis.example_neuron(n=1, type='skeleton')
ds = s.downsample(5)
# Under the hood, `s.downsample()` calls `navis.downsample_neuron(s)`
The inplace Parameter#
You may notice that many NAVis functions that modify neurons (resampling, pruning, etc.) have an inplace parameter. This is analogous to pandas where inplace defines whether we modify the original (inplace=True) or operate on a copy (inplace=False, default).
Downsample a copy of our skeleton and leaving the original unchanged (this is the default for almost all functions):
n_ds = navis.downsample_neuron(neuron, 10, inplace=False)
Downsample the original neuron:
navis.downsample_neuron(neuron, 10, inplace=True)
Using inplace=True can be useful if you work with lots of neurons and want avoid making unnecessary copies to keep the memory footprint low!
Getting Help#
Feeling a bit lost? No worries! Check out the Tutorials or browse the API documentation.
NAVis also supports autocompletion: typing navis. and pressing the TAB key should bring up a list of available functions. This also works with neuron properties and methods!
If you don't know what a function does, try e.g. help(navis.plot3d) or find it in the API documentation to get a nicely rendered docstring:
help(navis.prune_twigs)
Prune terminal twigs under a given size.
By default this function will simply drop all terminal twigs shorter than
`size`. This is very fast but rather stupid: for example, if a twig is
just 1 nanometer longer than `size` it will not be touched at all. If you
require precision, set `exact=True` which will prune *exactly* `size`
off the terminals but is about an order of magnitude slower.
Parameters
----------
x : TreeNeuron | MeshNeuron | NeuronList
size : int | float | str
Twigs shorter than this will be pruned. If the neuron has
its `.units` set, you can also pass a string including the
units, e.g. '5 microns'.
exact: bool
See notes above.
mask : iterable | callable, optional
Either a boolean mask, a list of node IDs or a callable taking
a neuron as input and returning one of the former. If provided,
only nodes that are in the mask will be considered for pruning.
inplace : bool, optional
If False, pruning is performed on copy of original neuron
which is then returned.
recursive : int | bool, optional
If `int` will undergo that many rounds of recursive
pruning. If True will prune iteratively until no more
terminal twigs under the given size are left. Only
relevant if `exact=False`.
parallel : bool
If True and input is NeuronList, use parallel
processing. Requires `pathos`.
n_cores : int, optional
Numbers of cores to use if `parallel=True`.
Defaults to half the available cores.
progress : bool
Whether to show a progress bar. Overruled by
`navis.set_pbars`.
omit_failures : bool
If True will omit failures instead of raising
an exception. Ignored if input is single neuron.
Returns
-------
TreeNeuron/List
Pruned neuron(s).
Examples
--------
Simple pruning
>>> import navis
>>> n = navis.example_neurons(2)
>>> # Prune twigs smaller than 5 microns
>>> # (example neuron are in 8x8x8nm units)
>>> n_pr = navis.prune_twigs(n,
... size=5000 / 8,
... recursive=float('inf'),
... inplace=False)
>>> all(n.n_nodes > n_pr.n_nodes)
True
Exact pruning
>>> n = navis.example_neurons(1)
>>> # Prune twigs by exactly 5 microns
>>> # (example neuron are in 8x8x8nm units)
>>> n_pr = navis.prune_twigs(n,
... size=5000 / 8,
... exact=True,
... inplace=False)
>>> n.n_nodes > n_pr.n_nodes
True
Prune using units
>>> import navis
>>> n = navis.example_neurons(1)
>>> # Example neurons are in 8x8x8nm units...
>>> n.units
<Quantity(8, 'nanometer')>
>>> # ... therefore we can use units for `size`
>>> n_pr = navis.prune_twigs(n,
... size='5 microns',
... inplace=False)
>>> n.n_nodes > n_pr.n_nodes
True
Note that most functions have helpful Examples!
What next?#
-
Neuron types ---
Find out more about the different neuron types in NAVis.
-
Lists of Neurons ---
Check out the guide on lists of neurons.
-
Neuron I/O
Learn about how to load your own neurons into NAVis.