Install

Installation instructions come in two flavours:

  1. Quick install: if you sort of know what you are doing

  2. Step-by-step instructions : if you are brand new to Python

By the way

You can try pymaid without having to install anything! Simply follow this link to Binder: they are kindly hosting a Jupyter notebook server with the most up-to-date version of pymaid. Just navigate and open examples/start_here.ipynb to have a crack at it!

Quick install

If you don’t already have it, get the Python package manager PIP. Then you can install pymaid like this:

pip3 install python-catmaid

Important

There is a pymaid package on PyPI but that is something else! Please make sure to install python-catmaid!

Installing from Github

You can also install pymaid directly from Github to get the bleeding edge version:

pip3 install git+https://github.com/navis-org/pymaid@master

Installing from source

Instead of using PIP to install from Github, you can also install manually:

  1. Download the source (e.g a tar.gz file from https://github.com/navis-org/pymaid/tree/master/dist)

  2. Unpack and change directory to the source directory (the one with setup.py).

  3. Run python3 setup.py install to build and install

Step-by-step instructions

  1. Check if Python 3 is installed and install if necessary.
    Linux and Mac should already come with Python distribution(s) but you need to figure out if you have Python 2, Python 3 or both:
    Open a terminal, type in
    python3 --version
    and press enter. You should get something similar to either of this:
    1. python3: command not found
      No Python 3 installed. See below box on how to install Python 3.
    2. Python 3.6.4 :: Anaconda, Inc.
      Python 3 is already installed. Nice! Proceed with step 2.
  2. Get the Python package manager PIP.
    Try running this in a terminal:
    pip3 install --upgrade pip wheel setuptools
    If you already have PIP, this should update it to the most recent version. If you get:
    pip3: command not found
    follow this link to download and install PIP.
  3. Install pymaid and its dependencies.
    Open a terminal and run:
    pip3 install python-catmaid -U
    to install pymaid and all of its mandatory dependencies from PyPI. You can also use this command to update an existing install of pymaid!
  4. Done! Go to Tutorial to get started.

Installing Python 3

On Linux and OSX (Mac), simply go to https://www.python.org to download + install Python3. I recommend getting Python 3.5 or 3.6 as newer versions may still have compatibility problems with some of pymaid’s dependencies.

On Windows, things are bit more tricky. While pymaid is written in pure Python, some of its dependencies are written in C for speed and need to be compiled - which a pain on Windows. I strongly recommend installing a scientific Python distribution that comes with “batteries included”. Anaconda is a widespread solution that comes with its own package manager conda.

Note

There are two optional dependencies that you might want to install manually: pyoctree and rpy2. The latter is only relevant if you intend to use pymaid’s R bindings.

Dependencies

Mandatory

If you installed pymaid using pip, mandatory dependencies should have been installed automatically.

NumPy

Provides matrix representation of graphs and is used in some graph algorithms for high-performance matrix computations.

Pandas

Provides advanced dataframes and indexing.

Vispy

Used to visualise neurons in 3D. This requires you to have one of the supported backends installed. During automatic installation pymaid will try installing the PyQt5 backend to fullfil this requirement.

Plotly

Used to visualise neurons in 3D. Alternative to Vispy based on WebGL.

NetworkX

Graph analysis library written in pure Python. This is the standard library used by pymaid.

SciPy

Provides tons of scientific computing tools: sparse matrix representation of graphs, pairwise distance computation, hierarchical clustering, etc.

Matplotlib

Essential for all 2D plotting.

Seaborn

Used e.g. for its color palettes.

tqdm

Neat progress bars.

PyPNG

Generates PNG images. Used for taking screenshot from 3D viewer. Install from PIP: pip3 install pypng.

Optional

Rpy2

Provides interface with R. This allows you to use e.g. R packages from https://github.com/jefferis and https://github.com/alexanderbates. 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!

pip3 install rpy2
Shapely

This is used to get 2D outlines of CATMAID volumes.

pip3 install shapely
ujson

Fast json en-/decoder written in C/C++. This will speed up fetching data.

pip3 install ujson

Advanced users: more speed with iGraph

By default pymaid uses the NetworkX graph library for most of the computationally expensive function. NetworkX is written in pure Python, well maintained and easy to install.

If you need that extra bit of speed, consider manually installing iGraph. It is written in C and therefore very fast. If available, pymaid will use iGraph over NetworkX. iGraph is difficult to install though because you have to install the C core first and then its Python bindings, python-igraph.