Installation
Installing NAVis#
NAVis requires Python 3.9 or later. The instructions below assume that you have already installed Python and its package manager pip.
By the way
You can use NAVis without having to install anything on your local machine! Follow this link to open an example notebook in Google's Colaboratory.
NAVis is published as a Python package and can be installed with pip, ideally by using a virtual environment. Open up a terminal and install NAVis with:
This is the "batteries included" install that will install NAVis plus a number of extra dependencies that are just nice to have.
pip install navis[all] -U
If you run into issues, try the minimal install instead.
If you're running into issues with the full install, you can try this minimal install instead:
pip install navis -U
If you go down this route some functions in NAVis might complain about missing dependencies. No worries though: they should also tell you how to install them. See also the section on Optional Dependencies below.
To install the latest version from Github:
pip install git+https://github.com/navis-org/navis@master
To install the latest dev with extras:
pip install "navis[all] @ git+https://github.com/navis-org/navis@master"
Note
MacOS (both Intel and the new ARM chips) and Linux should work off the bat without any problems. On Windows, you might run into issues with some of the dependencies. If that happens, we recommend you check out the Windows Subsystem for Linux (WSL).
Optional dependencies#
If you installed NAVis using the batteries-included [all] option, you can ignore this section.
If you opted for the minimal install, you might want to consider adding some of these optional dependencies as they e.g. provide speed-boosts in certain situations or are for certain functions.
These extras can be installed directly, or along with NAVis with
pip install navis[extra1,extra2]
The user-facing extras, the dependencies they install, and how to install those dependencies directly, are listed below:
Performance
These dependencies aren't strictly necessary but will speed up certain operations:
fastcore: navis-fastcore#
navis-fastcore re-implements a bunch of low-level functions in Rust and wraps them in Python. NAVis will use fastcore under-the-hood if it is available. This is a highly recommended extra as it can speed up operations such as geodesic distances, Strahler Index, pruning and other downstream functions by several orders of magnitude.
pip install navis-fastcore
kdtree: pykdtree#
Faster than scipy's cKDTree implementation. If available, will be used to speed up e.g. NBLAST.
pip install pykdtree
pathos: pathos#
Pathos is a multiprocessing library. NAVis uses it to parallelize functions across lists of neurons.
pip install pathos
hash: xxhash#
For speeding up some lookup tables.
pip install xxhash
meshes: open3d, pyfqmr#
Assorted functionality associated with meshes. pyfqmr in particular is highly recommended if you want to downsample meshes.
pip install open3d pyfqmr
Visualization
NAVis supports various different backends for 2D and 3D visualization. For 2D visualizations we use matplotlib by default which is installed automatically. For 3D visualizations, you can use octarine3d, vispy, plotly or k3d backends.
octarine3d: octarine3d#
For 3D visualisation in terminal and Jupyter notebooks.
Octarine3d is a modern, high-performance, WGPU-based viewer for 3D visualisation of neurons. It is the default 3D viewer for NAVis. It is recommended to install it as it is the fastest, most feature-rich viewer available. By default, navis[all] will install octarine3d with standard windows manager pyside6 and Jupyter notebook manager jupyter_rfb. It will also install the navis-octarine-plugin which is required to use octarine3d as a viewer for NAVis. This is equivalent to the following command:
pip install octarine3d[all] octarine-navis-plugin
Please see octarine3d installation instructions for information on how to choose a different backend.
Note
Older systems (pre ~2018) might not support WGPU, in which case you might want to fall back to the vispy backend.
vispy-* backends: vispy#
For 3D visualisation in terminal and Jupyter notebooks.
Vispy provides a high-performance, OpenGL-based viewer for 3D data visualisation. Vispy itself has a choice of window managers: the one which works for you will depend on your operating system, hardware, other installed packages, and how you're using navis. The default, supplied with NAVis' vispy-default extra, is pyside6 (for use from the console) and jupyter_rfb (for use in Jupyter notebooks). Each of vispy's backends, listed here can be installed through vispy and its extras, or NAVis' vispy-* extras.
pip install navis[vispy-pyqt5]
# or
pip install vispy[pyqt5]
Note
The Vispy backend is deprecated in favor of Octarine. We might still decide to keep it if people end up having problems with Octarine. Please get in touch on Github if that's the case.
plotly: plotly#
For 3D visualisation in Jupyter notebooks.
pip install plotly
k3d: k3d#
For 3D visualisation in Jupyter notebooks.
pip install k3d
Miscellaneous
r: Rpy2#
Provides interface with R. This allows you to use e.g. the natverse R packages. Note that this package is not installed automatically as it would fail if R is not already installed on the system. You have to install Rpy2 manually!
pip install rpy2
shapely: Shapely#
This is used to get 2D outlines of navis.Volumes when plotting in 2D with volume_outlines=True.
pip install shapely
flybrains: flybrains#
Transforming data between some template Drosophila brains.
pip install flybrains
cloudvolume: cloud-volume#
Reading and writing images, meshes, and skeletons in Neuroglancer precomputed format. This is required required for e.g. the MICrONs interface.
pip install cloud-volume
What next?#
-
Quickstart ---
Check out the quickstart tutorial for an overview of basic concepts in NAVis.
-
Tutorials ---
Check out the tutorials!