Data types

Overview

navis is a Python package for analysing, manipulating and visualizing neurons.

pymaid lets you interface with a CATMAID server such as those hosted by VFB.

Both packages have extensive documentation (navis | pymaid) with introductory tutorials, examples and a list of all available functions.

Basic datatypes: neurons and neuron lists

navis knows three types of neurons:

1. TreeNeurons = skeletons, e.g. from CATMAID
2. MeshNeurons = meshes, e.g. from the hemibrain segmentation
3. Dotprops = points + tangent vectors (typically only used for NBLAST)

Collections of neurons are typically held in a specialized container: a NeuronList.

Neurons

In this notebook we will focus on skeletons - a.k.a. TreeNeurons - since this is what you get out of CATMAID. Let’s kick things off by having a look at what neurons look like once it’s loaded:

import navis

# Load one of the example neurons shipped with navis
# (these are olfactory projection neurons from the hemibrain data set)
n = navis.example_neurons(1, kind='skeleton')

# Print some basic info
n

WARNING: Could not load OpenGL library.

Above summary lists a couple of (computed) properties of the neuron. Each of those can also be accessed directly like so:

n.id

1734350788

There are many more properties that you might find interesting! In theory, you can use type n. and TAB to get auto-complete suggestions of available properties and methods.

Deepnote appears to have problems with that sometimes - you can fall back to good ‘ole dir() in that case.

Here is an (incomplete) list of some of the more relevant properties:

• bbox: bounding box of the neuron
• cable_length: cable length
• id: every neuron has an ID
• nodes: the SWC node table underlying the neuron

And a couple of class methods:

• reroot: reroot neuron
• plot2d/plot3d: plot the neuron (see also subsequent lessons)
• copy: make and return a copy
• prune_twigs: remove small terminal twigs

At this point I encourage you to just explore and play around with what TreeNeuron has to offer. Also check out the docs!

As an example: this is how you get the ID of this neuron’s root node.

# Current root node of this neuron
n.root

array([1], dtype=int32)

Some of the properties such as .root or .ends are computed on-the-fly from the underlying raw data. For TreeNeurons that’s the node table (and it’s graph representation). The node table is a pandas DataFrame that looks effectively like a SWC:

# `.head()` gives us the first couple rows
n.nodes.head()

The methods (such as .reroot) are short-hands for main navis functions:

# Reroot neuron to another node
n2 = n.reroot(new_root=2)
# Print the new root -> expect "2"
n2.root

array([2])

# Instead of calling the shorthand method, we can also do this
n3 = navis.reroot_neuron(n, new_root=2)
n3.root

array([2])

NeuronLists

In practice you will likely work with multiple neurons at a time. For that, navis has a convenient container: NeuronLists

# Get more than one example neuron
nl = navis.example_neurons(5)

# `nl` is a NeuronList 
type(nl)

navis.core.neuronlist.NeuronList

# You can also create neuron lists yourself
my_nl = navis.NeuronList(n)

In many ways NeuronLists work like Python-lists with a couple of extras:

# Calling just the neuronlist produces a summary 
nl

# Get a single neuron from the neuronlist
nl[1]

neuronlists also support fancy indexing similar to numpy arrays:

# Get multiple neurons from the neuronlist
nl[[1, 2]]

# Slicing is also supported
nl[1:3]

Strings will be matched against the neurons’ names.

# Get neuron(s) by their name
nl['754534424']

neuronlists have a special .idx indexer that let’s you select neurons by their ID

# Get neuron(s) by their ID 
# -> note that for example neurons name == id 
nl.idx[[754534424, 722817260]]

# Access properties across neurons -> returns numpy arrays
nl.n_nodes 

array([4465, 4845, 4336, 4702, 4890])

# Select neurons by given property
# -> this works with any boolean array 
nl[nl.n_nodes >= 4500]

Exercises:

1. Select the first and the last neuron in the neuronlist
2. Select all neurons with a soma
3. Select all neurons with a soma and less than 300,000 cable length

Further reading: https://navis.readthedocs.io/en/latest/source/tutorials/neurons_intro.html