LIONESS

---

Copyright ©2023. Institute of Science and Technology Austria (IST Austria).

This file is part of the code developed for the paper "Dense 4D nanoscale reconstruction of living brain tissue". This code is free software: you can redistribute it and/or modify it under the terms of the MIT License.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the MIT License for more details.

You should have received a copy of the MIT License along with this program. If not, see https://opensource.org/licenses/.

OVERVIEW

---

The following code is used to prepare LIONESS data for pytorch_connectomics training/inference, and then to create segmentations from the affinity maps generated by the network. Additionally, the code provides scripts for processing and validating the obtained segmentations.

Instructions for installing and using the pytorch_connectomics software can be found on the project website: https://connectomics.readthedocs.io/en/latest/index.html A configuration file for the pytorch_connectomics framework is provided in the "config" folder.

SYSTEM REQUIREMENTS

---

The software was tested on Linux system (Debian GNU/Linux 11 (bullseye)). The code requires the Conda package manager (https://docs.conda.io/en/latest/). The code was tested with Python 2.7. Required packages will be installed automatically when following the installation guide below.

CONTENTS

---

The tools the user will interact with can be found in the folder "tools/cli".

Folder contents:

• lioness --> base modules to handle computations on segmentations
  • segmentation
    • segmentation.py --> basic handling of segmentation
    • oversegmentation.py --> oversegmentation metric computations
    • watershed.py --> module responsible for running watershed at 2D and 3D levels
  • utils
    • utils.py --> utilities to load and write volume data in different formats
• tools/cli --> command line scripts to wrap functionality of the lioness package
  • clean_segmentation.py --> script to clean an automatic segmentation, removing small segments and segments with few slices
  • compute_ari_error.py --> script to compute the ARI error between a ground truth and an automatic segmentation
  • evaluate_oversegmentation.py --> script to compute several oversegmentation metrics used to evaluate different UNet configurations
  • preprocess_dataset.py --> script to preprocess the input datasets before training or inference
  • run_watershed.py --> script to run the watershed stage on affinity maps
  • show_seg_info.py --> script to print basic information about segmentations
• config
  • config.yaml --> example configuration file to use with the pytorch_connectomics framework to train a UNet or run inferences on test data

INSTALLATION

---

In order to install dependencies, run the following commands:

git clone https://github.com/danzllab/LIONESS.git
cd LIONESS

git clone https://github.com/zudi-lin/zwatershed.git
cd zwatershed
git reset --hard c2a046f2510bf3972266a87b52724375fd70a160
cd ..

git clone https://github.com/zudi-lin/waterz.git
cd waterz
git reset --hard 76a41790de558e8dbab592211a1d568e33d413f8
cd ..

cd zwatershed
conda create -n lioness_test --file requirements.txt
conda activate lioness_test
cd ../waterz
conda install --file requirements.txt -c conda-forge
cd ..
patch -u zwatershed/setup.py -i zwatershed.patch
cd zwatershed 
python setup.py install
cd ../waterz
python setup.py install
cd ..
conda env update --file environment.yml
cd lioness
python setup.py install
cd ..

Installation takes about 30 minutes.

DEMONSTRATION DATA

---

lioness_data.tif --> demo LIONESS dataset.

segmentation.tif --> corresponding segmentation.

affinity_map.h5 --> output of the UNet (for a different dataset) that is used as input to the watershed stage.

DEMO

---

Each script can be tested using the following command line command: To use the scripts on your own data or the test data provided, replace the names of the demo files below with your own I/O paths and filenames. A more detailed description of all the additional arguments is provided in each individual python script.

1. preprocess_dataset.py

python tools/cli/preprocess_dataset.py demo_data/lioness_data.tif demo_data/lioness_data_preprocessed.tif

Expected output: One new file 'lioness_data_preprocessed.tif' with the preprocessed data. Expected runtime: 5-10 seconds.

2. run_watershed.py

python tools/cli/run_watershed.py demo_data/affinity_map.h5 . --wz-thres 0.4

Expected output: Two new files 'affinity_map-seg0.40.h5' and 'affinity_map-seg0.40.tif' with the resulting segmentation, generated using watershed threshold=0.4. Expected runtime: 3 min.

3. evaluate_oversegmentation.py

python tools/cli/evaluate_oversegmentation.py demo_data/segmentation.tif demo_data/segmentation.tif

Note: for purposes of demonstration, the same segmentation file is used as the ground truth and as the evaluated file. Expected output: stats.csv file with the resulting statistics. Expected runtime: 15 sec.

4. clean_segmentation.py

python tools/cli/clean_segmentation.py demo_data/segmentation.tif --size 3 --slices 3 --output demo_data/segmentation_cleaned.tif

Expected output: One new file 'segmentation_cleaned.tif' with the processed segmentation. Expected runtime: 1 min.

5. show_seg_info.py

python tools/cli/show_seg_info.py demo_data/segmentation.tif

Expected output: information about the input segmentation file displayed in the terminal. Expected runtime: 15-20 sec.

6. compute_ari_error.py

python tools/cli/compute_ari_error.py --seg demo_data/segmentation.tif --gt demo_data/segmentation.tif --out result.txt

Note: for purposes of demonstration, the same segmentation file is used as the ground truth and as the evaluated file. Expected output: result.txt file with the ARI error value. Expected runtime: 5 sec.