AMFinder

The Automatic Mycorrhiza Finder (AMFinder) allows for automatic computer vision-based identification and quantification of AM fungal colonisation and intraradical hyphal structures on ink-stained root images using convolutional neural networks. The latest version of AMFinder is v2.0.

Reference publication: Evangelisti et al., 2021, New Phytologist.

See below how to compile, install and use AMFinder. We also provide tips for batch staining of plant roots.

We would like to hear from you: if you are working with a system that appears challenging for AMFinder, please get in touch. We would be happy to help generate specialised CNN1/2 networks and make them widely available to the research community.

Summary

1. Command-line tool amf
2. Standalone interface amfbrowser
3. A typical pipeline
4. How to batch stain plant roots?

Command-line tool amf

The command-line tool amf trains neural networks and predicts fungal colonisation and intraradical structures.

Installation instructions

1. Windows users only: install Windows Subsystem for Linux to get access to a Unix-like terminal.
2. Install Python 3.7 from the official website or from your package manager.
3. Download AMFinder sources from Github, and extract the archive.
4. Move to the amf folder.
5. Open a terminal, run export PYTHON=<path>, replacing <path> with the path to Python 3.7.
6. Run ./install.sh. If needed, add executable permissions with: chmod +x install.sh. Should the variable PYTHON not be set, the script will use the output of which python3 instead.

Important: Before using amf for training or prediction (see next section), you will need to activate its Python virtual environment. To that end, open a terminal in the amf directory and run the command source amfenv/bin/activate to activate the virtual environment. Your terminal prompt will change to (amfenv) $. Once you are done with amf, you can deactivate the environment by running the command deactivate.

Note: old processors may lack AVX and AVX2 processor instructions and may fail to run Tensorflow. If you encounter such error, you need to download and build Tensorflow from sources. Instructions can be found on the Tensorflow website.

Using the software

amf is used either to predict fungal colonisation and intraradical hyphal structures within plant root images (prediction mode), or to train AMFinder neural networks (training mode).

Prediction mode

Important: Remember to activate amf virtual environment before use (see installation instructions).

For predictions, run in a terminal amf predict <parameters> <images> where <parameters> are either the short or long names listed below. Replace <images> with the path to the JPEG or TIFF images to analyse.

Short	Long	Description	Default value
-net CNN	--network CNN	Mandatory. Use network CNN (see list below).
-t N	--tile_size N	Optional. Use N pixels as tile size.	N = 126

Pre-trained networks to be used with the parameter -net are available in folder trained_networks. You can add your own trained networks to this folder.

File name	Annotation level	Description
CNN1v1.h5	CNN1	Ink-stained, ClearSee-treated root pictures (flatbed scanner/microscope).
CNN1v2.h5	CNN1	Same, but trained with data augmentation.
CNN2v1.h5	CNN2	Ink-stained, ClearSee-treated microscope root pictures.
CNN2v2.h5	CNN2	Same, but trained with data augmentation.

Note: the image datasets used to generate these trained networks are available on Zenodo.

Training mode

Note: To be able to run amf, you first need to reactivate the virtual environment by running the command source amfenv/bin/activate (see installation guidelines, step 4).

For training, run in a terminal amf train <parameters> <images> where <parameters> are either the short or long names listed below (all training parameters are optional). Replace <images> with the path to the JPEG or TIFF images to analyse.

Short	Long	Description	Default value
-net CNN	--network CNN	Use network CNN.	ab initio training
-b N	--batch_size N	Use a batch size of N tiles.	N = 32
-k	--keep_background	Do not skip any background tile.	False
-a	--data_augmentation	Activate data augmentation.	False
-s	--summary	Save CNN architecture and graph.	False
-o PATH	--outdir PATH	Save trained model and CNN architecture in PATH.	cwd
-e N	--epochs N	Perform N training cycles.	N = 100
-p N	--patience N	Wait for N epochs before early stopping.	N = 12
-lr X	--learning_rate X	Use X as learning rate for the Adam optimiser.	X = 0.001
-vf N	--validation_fraction N	Use N percents of total tiles as validation set.	N = 15%
-1	--CNN1	Train for root colonisation.	True
-2	--CNN2	Train for intraradical hyphal structures.	False

Training can benefit from high-performance computing (HPC) systems. Below is a template script for Slurm:

#! /bin/bash
#SBATCH -e <error_file>
#SBATCH -o <output_file>
#SBATCH --mem=<memory_GB>
#SBATCH -n <procs>

ROOT=/home/<user>/amf

source $ROOT/amfenv/bin/activate
$ROOT/amf train <parameters> <images>
deactivate

Standalone interface amfbrowser

Browse, amend and validate amf predictions.

Installation instructions

Note: As a graphical interface, amfbrowser cannot be installed on a text-based system such as an HPC. Ready-to-use binaries are available. Windows users can use the linux version once Windows Subsystem for Linux (WSL) has been activated.

Linux

1. Download and install OPAM from the official webwsite or from your package manager.

2. Open a terminal in the amfbrowser folder and run the command: export OPAM=<path>, replacing <path> with the path to the opam program. Then, run the command ./install.sh to install amfbrowser dependencies and compile amfbrowser.exe. Should the variable OPAM not be set, the script will use the output of which opam. If needed, add executable permissions to the installation file with: chmod +x install.sh. Follow the instructions on the screen and reply yes to the questions asked during opam installation and configuration.

Note: You may need to install development packages such as libgtk2.0-dev and libgtksourceview2.0-dev. Users with miniconda or similar tool suite installed may encounter problems if their PATH variable has been altered. You may have to temporarily mask miniconda directory from your PATH variable by running PATH=<modified_path> opam install ....

MacOS

Same as Linux, but you will need Homebrew to install OPAM.

Windows 10

amfbrowser can be installed and run on Windows 10 after activation of Windows Subsystem for Linux (WSL).

1. Activate Windows Subsystem for Linux (WSL). Then, go to Windows App store and install a Linux distribution (Ubuntu and Debian are recommended, but others should work too).

2. Install an OCaml build system based on the brew package manager:

$ sudo apt update
$ sudo apt upgrade
$ sudo apt autoclean
$ sudo apt install curl build-essential git
$ sh -c "$(curl -fsSL https://raw.githubusercontent.com/Linuxbrew/install/master/install.sh)"
$ test -d ~/.linuxbrew && eval $(~/.linuxbrew/bin/brew shellenv)
$ test -d /home/linuxbrew/.linuxbrew && eval $(/home/linuxbrew/.linuxbrew/bin/brew shellenv)
$ test -r ~/.bash_profile && echo "eval \$($(brew --prefix)/bin/brew shellenv)" >> ~/.bash_profile
$ echo "eval \$($(brew --prefix)/bin/brew shellenv)" >> ~/.profile
$ brew install gpatch opam gtk+ cairo

3. Follow the Linux installation instructions. You may have to edit the file install.sh with a text editor and uncomment the option --disable-sandboxing.

4. Install a X server (for instance, Xming) and configure bash to tell GUIs to use the local X server by running export DISPLAY=localhost:0.0. This variable has to be set for each session. As an alternative, you can save the variable in your session configuration file by running: echo "export DISPLAY=localhost:0.0" >> ~/.bashrc and reload the configuration (. ~/.bashrc). The new variable with then be automatically set and does not have to be redefined manually.

A typical pipeline

Make sure amf and amfbrowser.exe are in $PATH or use /path/to/amf and /path/to/amfbrowser.exe when typing the commands below.

1. Predict colonisation on ink-stained root images: amf predict -net your_CNN1.h5 *jpg.

   Note 1: amf parameters can be found in this section.

   Note 2: H5 files containing trained networks can be found in trained_networks. If you trained AMFinder on a specific dataset, copy/paste your custom H5 file to this folder. AMFinder won't use H5 files stored in other folders.

2. Convert computer predictions to annotations by running amfbrowser.exe your_image.jpg on each image. AMFinder is a semi-automatic prediction pipeline. User supervision and validation of computer predictions for fungal colonisation is required before intraradical hyphal structures can be analysed.

   Important: amfbrowser is a graphical interface. It won't run on a text-based system such as an HPC.

3. Predict intraradical hyphal structures: amf predict -net your_CNN2.h5 *jpg.

4. Convert computer predictions to annotations by running amfbrowser your_image.jpg on each image.

How to batch stain plant roots?

An optimised ink-staining protocol with additional clearing is available in Evangelisti et al. (2021).

Batch staining plant roots is essential for high-throughput analyses. It can be achieved using a hand-crafted device composed of 10 cell strainers (100 µm nylon mesh) tied together with adhesive sealing film for PCR plates. A single sieve can accommodate a 4-week-old N. benthamiana root system. The sieves containing roots are immersed in 10% KOH, water, or ink/vinegar staining solution poured in a plastic lid. Plastic lids are floated in a hot (95°C) water bath to achieve the desired staining conditions. Sieves are pulled out of the lid containing the KOH solution and transferred to the washing solution, then to the ink staining solution without the need to manipulate roots, thereby reducing the risk of damage.

View from above	View from below	With plastic lid

Credit: devices from Dr Albin Teulet and Alex Guyon (Schornack lab), derived from an original idea by Dr Clément Quan.