AxonDeepSeg is an open-source software using deep learning and aiming at automatically segmenting axons and myelin sheaths from microscopy images. It performs 3-class semantic segmentation using a convolutional neural network.
AxonDeepSeg was developed at NeuroPoly Lab, Polytechnique Montreal, University of Montreal, Canada.
The following sections will help you install all the tools you need to run AxonDeepSeg.
Starting with Version 2.0, AxonDeepSeg supports the Windows operating system. However, please note that our continuous integration testing framework (TravisCI) only tests AxonDeepSeg for Unix-style systems, so releases may be more unstable for Windows than Linux/macOS.
Starting with version 3.2.0, AxonDeepSeg is only supported using Python 3.7.x. Although your system may already have a Python environment installed, we strongly recommend that AxonDeepSeg be used with Miniconda, which is a lightweight version of the Anaconda distribution. Miniconda is typically used to create virtual Python environments, which provides a separation of installation dependencies between different Python projects. Although it can be possible to install AxonDeepSeg without Miniconda or virtual environments, we will only provide instructions for this recommended installation setup.
First, verify if you already have an AxonDeepSeg-compatible version of Miniconda or Anaconda properly installed and is in your systems path.
In a new terminal window (macOS or Linux) or Anaconda Prompt (Windows – if it is installed), run the following command::
conda search python
If a list of available Python versions are displayed and versions >=3.7.0 are available, you may skip to the next section (git).
To install Miniconda, run the following commands in your terminal::
cd ~ wget https://repo.anaconda.com/miniconda/Miniconda3-latest-Linux-x86_64.sh -O ~/miniconda.sh bash ~/miniconda.sh -b -p $HOME/miniconda echo ". ~/miniconda/etc/profile.d/conda.sh" >> ~/.bashrc source ~/.bashrc
conda isn’t available on new terminal sessions after running these steps, it’s possible that your system is configured to use a different startup script. Try adding the line
source ~/.bashrc to your
~/.bash_profile file. See here for more details.
To install Miniconda, run the following commands in your terminal::
cd ~ curl https://repo.anaconda.com/miniconda/Miniconda3-latest-MacOSX-x86_64.sh -o ~/miniconda.sh bash ~/miniconda.sh -b -p $HOME/miniconda echo ". ~/miniconda/etc/profile.d/conda.sh" >> ~/.bash_profile source ~/.bash_profile
The AxonDeepSeg installation instruction using the Miniconda have only been tested for Windows 10. Older versions of Windows may not be compatible with the tools required to run AxonDeepSeg.
To install Miniconda, go to the Miniconda installation website and click on the Python 3.x version installer compatible with your Windows system (64 bit recommended). After the download is complete, execute the downloaded file, and follow the instructions. If you are unsure about any of the installation options, we recommend you use the default settings.
git is a software version control system. Because AxonDeepSeg is hosted on GitHub, a service that hosts
git repositories, having
git installed on your system allows you to download the most up-to-date development version of AxonDeepSeg from a terminal, and also allows you to contribute to the project if you wish to do so.
git, please follow instructions for your operating system on the git website
To install AxonDeepSeg, “clone” AxonDeepSeg’s repository (you will need to have
git installed on your system) and then open the directory:
git clone https://github.com/neuropoly/axondeepseg.git cd axondeepseg
Virtual environments are a tool to separate the Python environment and packages used between Python projects. They allow for different versions of Python packages to be installed and managed for the specific needs of your projects. There are several virtual environment managers available, but the one we recommend and will use in our installation guide is conda, which is installed by default with Miniconda. We strongly recommend you create a virtual environment before you continue with your installation.
To setup a Python virtual environment named “ads_venv” with all the required packages, in a terminal window (macOS or Linux) or Anaconda Prompt (Windows) run the following command and answer “y” to the installation instructions:
conda env create -f environment.yml -n ads_venv
For some users, the installation may take up to 30 minutes as many dependencies have shared subdependencies, and resolving these potential conflicts takes time. If that’s the case, we encourage you to take a break from your screen and go for a walk while listening to the AxonDeepSeg Spotify playlist.
FSLeyes is only supported on Mac and Linux. Windows users are encouraged to use a virtual machine if they want to use the GUI.
Then, activate your virtual environment:
conda activate ads_venv
To switch back to your default environment, run:
Once your virtual environment is installed and activated, install the AxonDeepSeg software with the following commands:
pip install -e .
To update an already cloned AxonDeepSeg package, pull the latest version of the project from GitHub and re-install the application:
cd axondeepseg git pull pip install -e .
When re-installing the application, the
model_seg_pns_bf folders in
AxonDeepSeg/models will be deleted and re-downloaded. Please do not store valuable data in these folders.
Testing the installation
Ensure that the virtual environment is activated.
To test if the software was installed correctly, you can launch a quick integrity test by running the following command on the terminal:
This integrity test automatically performs the axon and myelin segmentation of a test sample. If the test succeeds, the following message will appear in the terminal:
* * * Integrity test passed. AxonDeepSeg is correctly installed. * * *
For some users, the test may fail because Keras is using Theano backend instead of Tensorflow. In that case, you will see the line
Using Theano backend. when launching
axondeepseg_test. To fix this issue, add the line
export KERAS_BACKEND="tensorflow" at the end of the
<your_conda_install_location>\envs\<your_environment_name>/etc/conda/activate.d/keras_activate.sh file, then deactivate and reactivate your environment. The test should print
Using Tensorflow backend. and pass.
To run the entire testing suite (more code coverage), go to your AxonDeepSeg project directory on the terminal and run
cd axondeepseg py.test --cov AxonDeepSeg/ --cov-report term-missing
If all tests pass, AxonDeepSeg was installed succesfully.
Graphical User Interface (GUI) (optional)
AxonDeepSeg can be run via a Graphical User Interface (GUI) instead of the Terminal command line. This GUI is a plugin for the software FSLeyes. Beyond the convenience of running AxonDeepSeg with the click of a button, this GUI is also an excellent way to manually correct output segmentations (if need to).
In FSLeyes, do the following:
- Click on
file -> load plugin
ads_plugin.py (found in AxonDeepSeg folder)
- When asked
Install permanently click on
From now on, you can access the plugin on the FSLeyes interface by selecting
Settings -> Ortho View -> ADScontrol.
In case, you find trouble installing FSLeyes plugin for ADS you could refer the video below.