Contents

A short guide to the use of AxonDeepSeg

How to use and optimize the use of AxonDeepSeg for the segmentation of EM nerve fiber images.

Follow the original documentation
This post is a quick how-to guide. It’s aimed at helping with the installation, use and solve issues that are sometimes counter-intuitive of AxonDeepSeg. This doesn’t replace the original documentation which treats all aspects in much more details. Please take a look at the original documentation for more information.

Installation

AxonDeepSeg installation is not as quick as installing a package from pypi. You will need to install the package from the original GitHub repository.

Before installation

  1. Install miniconda according to your system following the instructions here
  2. Either clone the AxonDeepSeg repository using Git or download it by pressing the green Clone button → Download ZIP

Actual installation

  1. Open a terminal with access to conda and navigate inside axondeepseg folder you just downloaded
  2. This step might take a while. Create a conda virtual environment:
$ conda env create
  1. Once the environment is created, activate it:
$ conda activate ads_venv
  1. While still in the same axondeepseg folder, install the dependencies inside the virtual environment:
$ pip install -e .
Troubleshooting

It may occur that some time after you installed the package, the use or import of the package will fail. This can occur even if the virtual environment is still present, and likely due to the way the package is installed.

If this occurs, it is often enough to re-install the package following step 4., but deleting and re-creating the virtual environment from scratch might be necessary. Keep in mind that doing so will reset the models for the segmentation.

Testing

AxonDeepSeg provides a testing suite to verify the correct installation. While still in the same folder from the installation:

$ axondeepseg_test # quick test
$ py.test --cov AxonDeepSeg/ --cov-report term-missing # long test
What if it fails?

If some of the test fails, it might not mean the package won’t function. If what you want to do is to use the simple pre-trained models to segment images, most likely the package will still work.

Before uninstalling the software or trying to fix the issues, try to segment the test image and see if it works as expected.

Test image

  1. Download the test image from here
  2. Unzip the content of the folder
  3. Open a conda terminal and activate the environment as in actual installation 3.
  4. Try to segment an image, for example:
$ axondeepseg -t TEM -i test_segmentation/test_tem_image/image1_tem/image.png 

If no errors occur, this will create the axon, myeline and axonmyelin segmentation masks.

Lot's of stuff in the terminal!

Depending on your computer and installation, you will see much output in the terminal after lauching the command.

Most likely if you are running it on a laptop, you will have a No GPU available warning. This is not a problem, having a working GPU will speed up the calculations considerably, however.

Pre-trained model workflow

Fine-tuning or re-training a model
AxonDeepSeg comes with a SEM and a TEM pre-trained model. In this guide we will only consider using one of those models. If you want to train a new model or fine-tune an existing one, please refer to the corresponding guide.
Pixel size
AxonDeepSeg relies on knowing the pixel size of your images. This can either be communicated to the software through the -s flag in the command line, or having a pixel_size_in_micrometer.txt text file with the number inside the same folder as the corresponding images.

Segment a single image

Determine pixel size

If your images have been saved properly, it should be possible to retrieve the pixel size from the metadata. However it is possible that this information is not accessible, in that case the pixel size can be estimated from a reference object.

Many EM images come with a scalebar in a corner of an image: open the image in Fiji, select the line tool and draw a line over the scale bar. Then go to AnalyzeSet Scale.. and set the scale of the image. You can then access the pixel size of the opened image via the ImageShow Info.. menu.

In general, it is reccommended to optimize the segmentation parameters on a few image before batch processing entire folders.

Place your PNG image you want to segment into a separate folder (so you can keep input and output together). Then use axondeepseg to segment it:

$ axondeepseg -t MODEL -i path/to/image/IMAGE.png
What if my images are not PNG?

The best strategy would be to convert them to PNG. The best way to do this is using Fiji.

You can batch convert entire folders of images using the ProcessBatchConvert.. menu.

Find the correct zoom factor

Depending on the pixel size and image size of your images, the pre-trained models might perform great or very poorly. If you see your segmentation is “chopped up” in lots of squared sections, it’s likely that your images pixel size does not match well the images used to train the models.

Here is an example of over-segmented image due to incompatible zoom factor.

/mic-photon/image-analysis-hub/post_images/axondeepseg_guide/oversegmentation-axondeepseg.png

To compensate for this effect, AxonDeepSeg offers a zoom parameter -z which can be tuned to render the pixel size comparable. You can either manually try different values of zoom or use a zoom screening with -r and -l flags. This will create a folder with several segmentation masks inside corresponding to the tried zoom factor.

$ axondeepseg -t MODEL -i path/to/image/IMAGE.png -z ZOOM-VALUE # for a specific zoom value
$ axondeepseg -t MODEL -i path/to/image/IMAGE.png -r 0.5 3.0 -l 5 # for 5 values between 0.5 and 2.5 included

The above two commands should be enough to find a resonable zoom factor. Once you are happy with the results of a few images and found a good range, you can move to batch segment many images.

Segment many images at the time

Similarly to segmenting a single image, you can use the command line to segment entire folders. In this case it’s much more convenient to separate your images by pixel size and have the pixel_size_in_micrometer.txt to give AxonDeepSeg the information it needs. If you have images acquired at different zoom / magnifications, separate them in different folders and add a file for each of them with the correct pixel size.

$ axondeepseg -t MODEL -i path/to/folder/containing/images/ # plus extra parameters
Troubleshooting

It might occur that the above command will not work, but process only the first image in the folder instead of all images.

One workaround is to manually give a list of all the images inside a folder separated by a space. To speed this up you might want to find an automatic way to get all images inside a folder (such as the find command in bash) and paste that list in the command line.

Manually correcting the segmentation

Segmentation masks are simply images with empty background and a positive value for the foreground. So manually adjusting them is as simple as opening them in a software and using a brush to ‘touch-up’ the mask. Follow their guide for more information.

Calculate morphometrics

Most likely, the reason why you are trying to segment the nerve fibers is to obtain some morphometrics properties out of your images. AxonDeepSeg has this built in via another command.

  1. Make sure that each original PNG has a corresponding axonmyelin mask and pixel_size_in_micrometer file in the same folder.
  2. Use the axondeepseg morphometrics command to obtain a table of measurements.
$ axondeepseg_morphometrics -i path/to/image/IMAGE.png # plus extra options

In order to verify the segmentation and the properties values easily, we reccommend to use the -b and the -c flags in the command above. -b will add to the exported table the information if the nerve fibers touch an image border or not. This is important because obtaining morphometrics from incomplete fibers (because only part of it appears in the image) can be misleading and incorrect. -c will additionally export a colored image with the segmented masks and the corresponding index number of the measurements table. This allows quick back and forth between the image and the morphometrics table to verify the values and the segmentation.

If strange or impossible values are obtained via this calculations, warnings will appear in the terminal. To access this information in a easier way, make sure to check the axondeepseg.log file that is automatically created in the current folder where you used the command. Refer to their explanation for precise definition of every calculated property.