Installation
Installing NAVis#
NAVis requires Python 3.10 or later. The instructions below assume that you have already installed Python and its package manager pip.
Python 3.10 caveat
Everything works on Python 3.10 except writing R data files: that needs rdata >= 1.0, which itself requires Python >= 3.11. Reading .rds/.rda is unaffected. See the R & the natverse tutorial.
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).
navis-fastcore is required
Since 2.0, navis-fastcore - the Rust engine behind NAVis' graph, geodesic and NBLAST core - is a core dependency rather than an optional extra. Both installs above pull it in.
It ships prebuilt wheels for macOS (Intel and ARM), Windows, and Linux on x86-64, aarch64, i686, armv7l, ppc64le and s390x, so there is nothing to compile. The exception is musl-based Linux (e.g. Alpine), which builds from the source distribution and therefore needs a Rust toolchain.
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.
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 manually adding some of these optional dependencies as they provide speed-boosts in certain situations or are required for certain functions.
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:
kdtree: pykdtree#
Faster than scipy's cKDTree implementation. If available, will be used to speed up e.g. NBLAST.
pip install pykdtree
joblib: joblib#
The parallel backend NAVis prefers where it is installed (see navis.set_parallel_backend). It serializes with cloudpickle, so it can run lambdas and functions defined in a notebook, and it keeps its worker processes alive between calls - which makes a sequence of parallel=True calls markedly faster than rebuilding a pool each time. joblib.parallel_config also lets you route the work through dask, ray or ipyparallel.
Parallel processing works without it - NAVis falls back to the standard library's process pool - but that one cannot ship lambdas.
pip install joblib
pathos: pathos#
An alternative parallel backend (see navis.set_parallel_backend). Like joblib it serializes with dill and so can ship lambdas, but it builds a fresh worker pool for every call, which makes it the slower of the two.
pip install pathos
hash: xxhash#
For speeding up some lookup tables.
pip install xxhash
meshes: nothing left to install#
This extra used to pull in open3d for mesh simplification and smoothing. Both (navis.simplify_mesh, navis.smooth_mesh, and hence navis.downsample_neuron on meshes) now run on navis-fastcore, which is a hard requirement - so pip install navis[meshes] still resolves but has nothing to do.
Cluster computing
For spreading parallel=True across more than one machine (see navis.set_parallel_backend). Neither is part of navis[all] - install them explicitly with pip install navis[cluster] or individually:
dask: dask.distributed#
Runs the work on a dask cluster - anything from a LocalCluster on your laptop to a SLURMCluster/KubeCluster spanning a compute centre. Hand NAVis the Client and it will size the units of work against the cluster and send the neurons straight to the workers.
pip install "dask[distributed]"
submitit: submitit#
Submits the work to a scheduler - SLURM, or your local machine for a dry run - as an array job. Use this where you would otherwise write a batch script: nothing has to stay connected while the jobs sit in the queue.
pip install submitit
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, plotly or k3d backends.
octarine3d: octarine3d#
For 3D visualisation in terminal and Jupyter notebooks.
Octarine3d is a modern, high-performance, WGPU-based viewer for interactive 3D visualisation of neurons and is the default 3D viewer for NAVis. 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. If you are running into issues try updating your operating system and/or your graphics drivers. Failing that, plotly works without a GPU.
plotly: plotly#
For 3D visualisation in Jupyter notebooks.
pip install plotly
k3d: k3d#
For 3D visualisation in Jupyter notebooks.
pip install k3d
Miscellaneous
shapely: Shapely#
This is used to get 2D outlines of navis.Volumes when plotting in 2D with volume_outlines=True.
pip install shapely
cpd: rcpd#
Coherent point drift - fitting a transform between two point clouds without knowing which point matches which. This is what [navis.align.align_rigid][], [navis.align.align_deform][] and navis.nblast_align run on.
pip install rcpd
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 for e.g. the MICrONs interface.
pip install cloud-volume
These extras can be installed directly (see instructions above), or alongside NAVis with
pip install navis[extra1,extra2]
What next?#
-
Quickstart ---
Check out the quickstart tutorial for an overview of basic concepts in NAVis.
-
Tutorials ---
Check out the tutorials!