API Reference¶
navis has grown a lot! Last I looked, there were ~110 functions exposed
at top level (e.g. navis.plot3d) and easily another 100 secondary functions
available via submodules (e.g. navis.morpho.find_soma). This can be a bit
daunting at first - especially if you don’t exactly know what you are looking
for. 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 an issue on
the Github repo with your question.
This API reference is a more or less complete account of the primary functions:
In addition navis has interfaces to various external datasets and tools:
Most of these functions include examples of how to use them. Click on them to learn more!
Neuron/List¶
TreeNeurons, MeshNeurons, VoxelNeurons and Dotprops are neuron
classes. NeuronLists are containers thereof.
|
Base class for all neurons. |
|
Neuron represented as hierarchical tree (i.e. |
|
Neuron represented as mesh with vertices and faces. |
|
Neuron represented as voxels. |
|
Neuron represented as points + local vectors. |
|
Collection of neurons. |
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.
|
Return a copy of the neuron. |
|
Plot neuron using |
|
Plot neuron using |
|
Get a summary of this neuron. |
|
Convert coordinates to different unit. |
|
Convert units to match neuron space. |
|
Return estimated memory usage of this neuron. |
In addition to methods, neurons also have properties. These properties common to all neurons:
Connector table. |
|
Table with postsynapses. |
|
Table with presynapses. |
|
Names of all DataFrames attached to this neuron. |
|
Hashable ID. |
|
Neuron name. |
|
Unit space for this neuron. |
|
Neuron type. |
TreeNeurons¶
These are class methods available specific for TreeNeurons. Most of them are
simply short-hands for the other navis functions:
|
Convert coordinates to different unit. |
|
Prune neuron to its cell body fiber. |
|
Downsample the neuron by given factor. |
Calculate and return networkX representation of neuron. |
|
Calculate and return iGraph representation of neuron. |
|
|
Prune neuron down to the longest neurite. |
|
Prune neuron based on Strahler order. |
|
Prune neuron by intersection with given volume(s). |
|
Cut off nodes distal to given nodes. |
|
Remove nodes proximal to given node. |
|
Prune terminal twigs under a given size. |
|
Reload neuron. |
|
Reroot neuron to given node ID or node tag. |
|
Resample neuron to given resolution. |
|
Snap xyz location(s) to closest node or synapse. |
In addition TreeNeurons have a range of different properties:
Cable length. |
|
Cycles in neuron if any. |
|
|
Downsample the neuron by given factor. |
iGraph representation of this neuron. |
|
Whether neuron is a tree. |
|
Number of branch points. |
|
Return number of seperate skeletons in this neuron. |
|
Count number of connected trees in this neuron. |
|
Node table. |
|
Root node(s). |
|
Average cable length between 2 nodes. |
|
Neuron broken down into linear segments. |
|
Return simple neuron representation. |
|
Search for soma and return its position. |
|
List of subtrees. |
|
Radius-based volume. |
MeshNeurons¶
These are methods and properties specific to MeshNeurons.
Faces making up the neuron. |
|
Vertices making up the neuron. |
|
|
Skeletonize mesh. |
|
Snap xyz location(s) to closest vertex or synapse. |
Trimesh representation of the neuron. |
|
Volume of the neuron. |
|
|
Use trimesh to try and fix some common mesh issues. |
Voxel grid representation. |
|
(N, 3) array of x/y/z voxels locations |
|
Shape of voxel grid. |
|
|
Strip empty voxels (leading/trailing planes of zeros). |
Dotprops¶
These are methods and properties specific to Dotprops.
Center of tangent vectors. |
|
Tangent vectors. |
|
Alpha value for tangent vectors. |
|
|
Turn dotprops into a skeleton. |
|
Snap xyz location(s) to closest point or synapse. |
Dotprops are typically indirectly generated from e.g. skeletons or
point clouds using navis.make_dotprops().
Conversion¶
There are a couple functions to convert from one neuron type to another:
|
Produce dotprops from x/y/z points. |
|
Turn neuron into skeleton. |
|
Generate mesh from object(s). |
|
Turn neuron into voxels. |
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:
|
Apply function across all neurons in this NeuronList. |
|
Return summary for top N neurons. |
Helper to mimic |
|
|
Return mean numeric and boolean values over all neurons. |
|
Remove duplicate neurons from list. |
|
Return sum numeric and boolean values over all neurons. |
|
Get summary over all neurons in this NeuronList. |
|
Return summary for bottom N neurons. |
|
Split into NeuronLists of the same neuron type. |
Properties:
Bounding box across all neurons in the list. |
|
Return True if NeuronList is empty. |
|
Return True if contains neurons with non-unique IDs. |
|
Return True if contains more than one type of neuron. |
|
Shape of NeuronList (N, ). |
|
Return neuron types present in this list. |
Visualization¶
Various functions for plotting neurons and volumes.
|
Generate 3D plot. |
|
Generate 2D plots of neurons and neuropils. |
|
Plot neuron topology in 1D according to Cuntz et al. (2010). |
|
Plot neuron as flat diagrams. |
Clear viewer 3D canvas. |
|
Close existing vispy 3D canvas (wipes memory). |
|
Grab active 3D viewer. |
|
|
Save a screenshot of active vispy 3D canvas. |
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.
|
Mesh consisting of vertices and faces. |
|
Merge multiple volumes into a single object. |
|
Plot volume using |
Use trimesh to try and fix issues (holes/normals). |
|
|
Resize volume. |
Vispy 3D viewer¶
Using navis.plot3d() from a terminal will spawn a Vispy 3D viewer object
which has a bunch of useful methods:
|
Vispy 3D viewer. |
|
Add objects to canvas. |
Clear canvas. |
|
Close viewer. |
|
|
Colorize neurons using a seaborn color palette. |
|
Set neuron color. |
Hide given neuron(s). |
|
|
Unhide given neuron(s). |
|
Save a screenshot of this viewer. |
Show viewer. |
|
Toggle bounding box. |
Neuron Morphology¶
Collection of functions to analyze and manipulate neuronal morphology.
Manipulation¶
Functions to edit morphology:
|
Compute an average from a list of skeletons. |
|
Break neuron into its connected components. |
|
Remove spikes in skeleton (e.g. |
|
Remove small disconnected pieces of "fluff". |
|
Prune neuron to its cell body fiber. |
|
Split skeleton at given point and returns two new neurons. |
|
Guess radii for skeleton nodes. |
|
Heal fragmented skeleton(s). |
|
Return a neuron consisting of only the longest neurite(s). |
|
Prune neuron based on Strahler order. |
|
Prune terminal twigs under a given size. |
|
Prune all neurites past a given distance from a source. |
|
Reroot neuron to new root. |
|
Split a neuron into axon and dendrite. |
|
Split neuron into fragments. |
|
Stitch multiple skeletons together. |
|
Subset a neuron to a given set of nodes/vertices. |
|
Smooth skeleton(s) using rolling windows. |
|
Smooth meshes (TriMesh, MeshNeuron, Volume). |
|
Smooth voxel(s) using a Gaussian filter. |
|
Calculate tortuosity of a neuron. |
Resampling¶
Functions to down- or resample neurons.
|
Resample skeleton(s) to given resolution. |
|
Resample neuron such that nodes lie exactly on given 1d grid. |
|
Downsample neuron(s) by a given factor. |
|
Simplify meshes (TriMesh, MeshNeuron, Volume). |
Analysis¶
Functions to analyze morphology.
|
Return the branch point at which the two largest branches converge. |
|
Calculate Strahler Index (SI). |
|
NBLAST query against target neurons. |
|
Smart(er) NBLAST query against target neurons. |
|
All-by-all NBLAST of inputs neurons. |
|
Synapsed-based variant of NBLAST. |
Polarity metrics¶
Calculate bending flow. |
|
|
Calculate synapse flow centrality (SFC). |
Per arbor seggregation index (SI). |
|
Calculate segregation index (SI). |
Distances¶
Functions to calculate Euclidian and geodesic (“along-the-arbor”) distances.
|
Calculate the amount of cable of neuron A within distance of neuron B. |
|
Check if nodes A are distal to nodes B. |
|
Get the geodesic distance between nodes in nanometers. |
|
Generate geodesic ("along-the-arbor") distance matrix between nodes/vertices. |
|
Get length of a linear segment. |
Intersection¶
Functions to intersect points and neurons with volumes.
|
Test if points/neurons are within a given volume. |
|
Compute intersection matrix between a set of neurons and volumes. |
Transforming and Mirroring¶
Functions to transform spatial data between (e.g. neurons) template brains. Check out the tutorials for example on how to use them.
High-level functions:
|
Apply transform(s) to data. |
|
Transform 3D data between template brains. |
|
Symmetrize 3D object (neuron, coordinates). |
|
Mirror 3D object (neuron, coordinates) about given axis. |
|
Mirror 3D coordinates about given axis. |
navis supports several types of transforms:
|
Affine transformation of 3D spatial data. |
|
Elastix transforms of 3D spatial data. |
|
CMTK transforms of 3D spatial data. |
|
Hdf5 transform of 3D spatial data. |
|
Thin Plate Spline transforms of 3D spatial data. |
Helper transform that simply passes points through. |
|
|
Moving Least Squares transforms of 3D spatial data. |
The TemplateRegistry keeps track of template brains, transforms and such:
|
Tracks template brains, available transforms and produces bridging sequences. |
This relevant instance of this class is navis.transforms.registry. So to
register a new transform you would for example do this:
>>> navis.transforms.registry.register_transform(transform, ...)
These are the methods and properties of registry:
|
Register a transform. |
|
Parse and register a transform file. |
|
Register a template brain. |
|
Register path(s) to scan for transforms. |
|
Scan registered paths for transforms and add to registry. |
|
Draw bridging graph using networkX. |
|
Search for a mirror transformation for given template. |
|
Find bridging path from source to target. |
|
Find shortest bridging sequence to get from source to target. |
Clear caches of all cached functions. |
|
|
Generate summary of available transforms. |
Registered transforms (bridging + mirror). |
|
Registered mirror transforms. |
|
Registered bridging transforms. |
Connectivity¶
Collection of functions to work with graphs and adjacency matrices.
Graphs¶
Functions to convert neurons and networkx to iGraph or networkX graphs.
Turn Tree-, Mesh- or VoxelNeuron into an NetworkX graph. |
|
|
Turn Tree-, Mesh- or VoxelNeuron(s) into an iGraph graph. |
|
Turn neuron into scipy KDTree. |
|
Generate NetworkX graph from edge list or adjacency. |
|
Generate iGraph graph from edge list or adjacency. |
|
Rewire neuron from graph. |
|
Insert new nodes between existing nodes. |
|
Drop nodes from neuron without disconnecting it. |
Connectivity metrics¶
Functions to analyse/cluster neurons based on connectivity.
|
Calculate connectivity similarity. |
|
Calculate sparseness. |
|
Calculate the amount of cable of neuron A within distance of neuron B. |
|
Cluster neurons based on their synapse placement. |
Import/Export¶
Functions to import/export neurons.
|
Create Neuron/List from SWC file. |
|
Generate SWC file from neuron(s). |
|
Create Neuron/List from NRRD file. |
|
|
|
Read NMX files into Neuron/Lists. |
|
Read objects from nat R data (.rda) file. |
|
Load neuron from JSON (file or string). |
|
Save neuron(s) to json-formatted file. |
|
Export skeletons or meshes to neuroglancers' (legacy) precomputed format. |
|
Read skeletons and meshes from neuroglancer's precomputed format. |
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 compartment models of neurons. Please see the tutorials for details.
Not imported at top level! Must be imported explicitly:
import navis.interfaces.neuron as nrn
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
Fetch neuron info by ID or by name. |
|
Fetch neuron by ID or by name. |
|
List all available neuron fields. |
|
|
List all possible values for given neuron field. |
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
You can then import neuprint from navis like so:
import navis.interfaces.neuprint as neu
Fetch given ROI. |
|
Construct navis.TreeNeuron/List from neuprint neurons. |
|
Fetch mesh neuron. |
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
Authenticate against Insect Brain DB. |
|
Fetch brain meshes for given species. |
|
Get all info for given species. |
|
Get all info for given species. |
|
Fetch skeletons for given neuron(s). |
|
|
Fetch all skeletons for given species. |
Search for neurons matching given parameters. |
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 Python <3.6. 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 Handler
object. It is used to import objects and facilitate working with them
programmatically once they are imported.
|
Class that interfaces with scene in Blender. |
Objects¶
|
Add neuron(s) to scene. |
Clear all neurons |
|
|
Select given neurons. |
Hide all neuron-related objects. |
|
Unide all neuron-related objects. |
Materials¶
Assign color to all neurons. |
|
Randomly colorize ALL neurons. |
|
Change emit value. |
|
Change transparency (True/False). |
|
Change alpha (0-1). |
|
Change bevel of ALL neurons. |
Selections¶
|
Select given neurons. |
Select objects in 3D viewer |
|
Assign color to all objects in the list. |
|
Assign colors across the color spectrum. |
|
Change emit value. |
|
Change transparency (True/False). |
|
Change alpha (0-1). |
|
Change bevel radius of objects. |
|
Hide objects. |
|
Unhide objects. |
|
Hide everything BUT these objects. |
|
Delete neurons in the selection. |
Cytoscape API¶
Functions to use Cytoscape via the cyREST API.
Not imported at top level! Must be imported explicitly:
from navis.interfaces import cytoscape
Load network into Cytoscape. |
|
Initialises connection with Cytoscape and returns client. |
Allen MICrONS datasets¶
Functions to fetch neurons (including synapses) from the Allen Institute’s MICrONS EM datasets.
Requires caveclient as additional dependencies:
pip3 install caveclient -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.
R interface¶
Bundle of functions to use R natverse libraries.
Not imported at top level! Must be imported explicitly:
from navis.interfaces import r
|
Convert data from rcatmaid (e.g. |
|
Fetch given neuropil from |
|
Initialize the R Catmaid package. |
|
Load and convert R data file (.rda). |
|
NBLAST using R's |
|
All-by-all NBLAST using R's |
|
Class holding NBLAST results and wrappers that allow easy plotting. |
Convert R neuron objects (dotprops, neurons, etc) to navis Neuron/Lists. |
|
|
Convert Neuron/List to corresponding R neuron/neuronlist object. |
|
Transform 3D data between template brains. |
|
Mirror 3D object along given axixs. |
Utility¶
Various utility functions.
|
Run a health check on TreeNeurons and flag potential issues. |
|
Set global progress bar behaviors. |
|
Set levels for all associated module loggers. |
Set/update default connector colors. |
|
Remove all handlers from the |
|
Monkey patch cloud-volume to return navis neurons. |
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
(navis.longest_neurite()) in 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 is no single function but one for each neuron type.
Below table has an overview for which functions work with which neuron types.
Description |
TreeNeuron |
MeshNeuron |
VoxelNeuron |
Dotprops |
|---|---|---|---|---|
yes |
yes |
limited |
yes |
|
yes |
yes |
limited |
yes |
|
yes |
no |
no |
no |
|
yes |
no |
no |
no |
|
yes |
yes |
yes |
yes |
|
yes |
yes |
yes |
yes |
|
smoothing |
no |
|||
yes |
yes |
yes |
yes |
|
resampling (e.g. |
yes |
no |
no |
no |
NBLAST (e.g. |
no |
no |
no |
yes |
yes |
yes |
yes |
yes |
|
yes |
yes |
no |
yes |
|
no |
yes |
no |
no |
|
yes |
no |
yes |
no |
|
yes |
yes |
no |
yes |
|
yes |
yes |
no |
no |
|
yes |
yes |
no |
no |