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.
AxonDeepSeg installation is not as quick as installing a package from pypi. You will need to install the package from the original GitHub repository.
- Install miniconda according to your system following the instructions here
- Either clone the AxonDeepSeg repository using Git or download it by pressing the green Clone button → Download ZIP
- Open a terminal with access to conda and navigate inside
axondeepsegfolder you just downloaded
- This step might take a while. Create a conda virtual environment:
$ conda env create
- Once the environment is created, activate it:
$ conda activate ads_venv
- While still in the same
axondeepsegfolder, install the dependencies inside the virtual environment:
$ pip install -e .
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.
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
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.
- Download the test image from here
- Unzip the content of the folder
- Open a conda terminal and activate the environment as in actual installation 3.
- 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.
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
-sflag in the command line, or having a
pixel_size_in_micrometer.txttext file with the number inside the same folder as the corresponding images.
Segment a single image
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 Analyze → Set Scale.. and set the scale of the image. You can then access the pixel size of the opened image via the Image → Show 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
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 Process → Batch → Convert.. 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.
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
-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
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.
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.
- Make sure that each original PNG has a corresponding axonmyelin mask and pixel_size_in_micrometer file in the same folder.
- 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.