API Overview#

NAVis has grown a lot! Last I looked, there were over 120 functions and classes exposed at top level (e.g. navis.plot3d) and easily another 100 available via submodules (e.g. navis.transforms.AffineTransform). This can be a bit daunting at first - especially if you don't exactly know what you are looking for!

This document provides a curated, high-level summary. I recommend you either just have a browse, use the search field (upper right) or simply search in page (CONTROL/CMD-F). Failing that, please feel free to open a thread on Github Discussions with your question.

This API reference is a more or less complete account of the primary functions:

1. Neuron- and NeuronList functions and methods
2. Functions for visualization
3. Manipulate or analyze neuron morphology
4. Transforming and mirroring data
5. Analyze connectivity
6. Import/Export
7. Utility functions
8. Which functions work with which neuron types?

In addition NAVis has interfaces to various external datasets and tools:

• NEURON simulator
• Neuromorpho
• neuPrint
• InsectBrain DB
• Blender 3D
• Cytoscape
• Allen MICrONS datasets
• R and the natverse libraries

Most of these functions include examples of how to use them. Click on them to learn more!

Neurons & NeuronLists#

TreeNeurons, MeshNeurons, VoxelNeurons and Dotprops are neuron classes. NeuronLists are containers thereof.

General Neuron methods#

Despite being fundamentally different data types, all neurons share some common methods (i.e. functions) which they inherit from their abstract parent class BaseNeurons.

In addition to methods, neurons also have properties. These properties common to all neurons:

General Neuron properties#

Skeletons#

A navis.TreeNeuron represents a skeleton. These are class methods available specific for this neuron type. Note that most of them are simply short-hands for the other NAVis functions:

In addition, a navis.TreeNeuron has a range of different properties:

Skeleton utility functions#

Mesh neurons#

Properties specific to navis.MeshNeuron:

Methods specific to navis.MeshNeuron:

Voxel neurons#

VoxelNeurons (e.g. from confocal image stacks) are a relatively recet addition to NAVis and the interface might still change.

These are methods and properties specific to VoxelNeurons:

Dotprops#

navis.Dotprops are typically indirectly generated from e.g. skeletons or point clouds using navis.make_dotprops().

These are methods and properties specific to Dotprops:

Converting between types#

These functions will let you convert between neuron types:

See also Utility for functions to convert to/from basic data types.

NeuronList methods#

NeuronLists let you access all the properties and methods of the neurons they contain. In addition there are a few NeuronList-specific methods and properties.

Methods:

Properties:

Please see the tutorial on NeuronList for more information, including how to index them.

Visualization#

Various functions for plotting neurons and volumes.

Plotting Volumes/Meshes#

To plot meshes, you can pass trimesh.Trimesh objects directly to plot3d() or plot2d(). However, NAVis has a custom class to represent meshes that has some useful perks: navis.Volume.

Vispy 3D viewer#

Using navis.plot3d() with backend="vispy" from a terminal will spawn a Vispy 3D viewer object which has a bunch of useful methods. Note that this requires one of navis' vispy-* extras to be installed, so that vispy has a backend.

Octarine 3D viewer#

Using navis.plot3d() with backend="octarine" from a terminal will return an octarine.Viewer 3D viewer. Please see the Octarine documentation for details about the viewer.

Neuron Morphology#

Collection of functions to analyze and manipulate neuronal morphology.

Analyse#

Functions to analyze morphology.

Manipulate#

Functions to edit morphology:

Resampling#

Functions to down- or resample neurons.

Comparing morphology#

NBLAST and related functions:

Utilities for creating your own score matrices for NBLAST:#

Utilities for NBLAST#

Polarity metrics#

Distances#

Functions to calculate Euclidean and geodesic ("along-the-arbor") distances.

Intersection#

Functions to intersect points and neurons with volumes. For example, if you'd like to know which part of a neuron is inside a certain brain region.

Transforming and Mirroring#

Functions to transform spatial data, e.g. move neurons from one brain space to another. Check out the tutorials for examples on how to use them.

High-level functions:

NAVis supports several types of transforms:

The TemplateRegistry keeps track of template brains, transforms and such:

The relevant instance of this class is navis.transforms.registry. So to register and use a new transform you would look something like this:

>>> transform = navis.transforms.AffineTransform(...)
>>> navis.transforms.registry.register_transform(transform,
...                                              source='brainA',
...                                              target='brainB')
>>> xf = navis.xform_brain(data, 'brainA', 'brainB')

You can check which transforms are registered like so:

>>> navis.transforms.registry.summary()  # this outputs a dataframe

These are the methods and properties of registry:

Connectivity#

Collection of functions to work with graphs and adjacency matrices.

Connectivity metrics#

Functions to analyse/cluster neurons based on connectivity.

Import/Export#

Functions to import neurons.

Functions to export neurons.

Utility#

Various utility functions.

Conversion#

Functions to convert between data types.

Network Models#

NAVis comes with a simple network traversal model (used in Schlegel, Bates et al., 2021).

Not imported at top level! Must be imported explicitly:

from navis import models

Interfaces#

Interfaces with various external tools/websites. These modules have to be imported explicitly as they are not imported at top level.

NEURON simulator#

Functions to facilitate creating models of neurons/networks. Please see the tutorials for examples.

Not imported at top level! Must be imported explicitly:

import navis.interfaces.neuron as nrn

Compartment models#

A single-neuron compartment model is represented by CompartmentModel:

The DrosophilaPN class is a subclass of CompartmentModel with pre-defined properties from Tobin et al. (2017).

Network models#

A network of point-processes is represented by PointNetwork:

NeuroMorpho API#

Set of functions to grab data from NeuroMorpho which hosts thousands of neurons (see tutorials).

Not imported at top level! Must be imported explicitly:

from navis.interfaces import neuromorpho

neuPrint API#

NAVis wraps neuprint-python and adds a few navis-specific functions. You must have neuprint-python installed for this to work:

pip install neuprint-python -U

You can then import neuprint from NAVis like so:

from navis.interfaces import neuprint

These are the additional functions added by NAVis:

Please also check out the tutorials for examples of how to fetch and work with data from neuPrint.

InsectBrain DB API#

Set of functions to grab data from InsectBrain which hosts some neurons and standard brains (see tutorials).

Not imported at top level! Must be imported explicitly:

from navis.interfaces import insectbrain_db

Blender API#

Functions to be run inside Blender 3D and import CATMAID data (see Examples). Please note that this requires Blender >2.8 as earlier versions are shipped with older Python versions not supported by NAVis. See the tutorials for an introduction of how to use NAVis in Blender.

Not imported at top level! Must be imported explicitly:

from navis.interfaces import blender

The interface is realised through a navis.interfaces.blender.Handler object. It is used to import objects and facilitate working with them programmatically once they are imported.

Objects#

Materials#

Selections#

You can use Handler.select() to select a group of neurons e.g. by type. That method then returns ObjectList which can be used to modify just the selected objects:

Cytoscape API#

Functions to use Cytoscape via the cyREST API.

Not imported at top level! Must be imported explicitly:

from navis.interfaces import cytoscape

Allen MICrONS datasets#

Functions to fetch neurons (including synapses) from the Allen Institute's MICrONS EM datasets.

Requires caveclient and cloud-volume as additional dependencies:

pip3 install caveclient cloud-volume -U

Please see caveclient's docs for details on how to retrieve and set credentials.

Not imported at top level! Must be imported explicitly:

from navis.interfaces import microns

Please also see the MICrONS tutorial.

H01 dataset#

Functions to fetch neurons (including synapses) from the H01 connectome dataset.

Requires caveclient and cloud-volume as additional dependencies:

pip3 install caveclient cloud-volume -U

Not imported at top level! Must be imported explicitly:

from navis.interfaces import h01

Please also see the H01 tutorial.

R interface#

Bundle of functions to use R natverse libraries.

Not imported at top level! Must be imported explicitly:

from navis.interfaces import r

Neuron types and functions#

As you can imagine not all functions will work on all neuron types. For example it is currently not possible to find the longest neurite via longest_neurite() for a VoxelNeuron. Conversely, some functionality like "smoothing" makes sense for multiple neuron types but the application is so vastly different between e.g. meshes and skeletons that there are specicialized functions for every neuron type.

Below table has an overview for which functions work with which neuron types: