README.md

Automated CZI to Ilastik Processing Pipeline

Author: Pierre Tocquin (University of Liège)

---

Overview

This script automates the processing of microscopy images in the CZI format. It provides functionalities to:

• Convert CZI files into mosaics stored as TIFF files.
• Perform segmentation of the mosaics using Ilastik in headless mode.
• Correct segmentation issues, including:
  • Identifying and preserving true nodes of Ranvier based on size and shape.
  • Filling interruptions in nerve segments caused by gaps in segmentation.
  • Applying morphological operations to refine segmentation results.
• Resize both original and segmented outputs for downstream analysis.
• Optimize disk usage by removing intermediate files.

---

Features

1. Mosaic Assembly: Converts tiled CZI images into complete mosaics stored as TIFF files.
2. Segmentation: Leverages Ilastik for pixel classification in headless mode.
3. Segmentation Correction:
   • Preserves true nodes of Ranvier based on cluster size and aspect ratio.
   • Removes thin or irregular structures via morphological operations.
   • Fills white gaps in blue regions (nerve interruptions).
4. Resizing: Scales the original and segmented images according to user-defined factors.
5. Intermediate File Cleanup: Removes intermediate TIFF files to save disk space.

---

Dependencies

Python Libraries:

• PyYAML: For reading the YAML configuration file.

  pip install pyyaml

• aicspylibczi: For handling CZI files.

  pip install aicspylibczi

• tifffile: For managing TIFF files.

  pip install tifffile

• OpenCV: For image resizing and morphological operations.

  pip install opencv-python-headless

Ilastik:

• Ilastik must be installed for pixel classification in headless mode.
• Download Ilastik.

---

Setup

Clone the repository:

git clone <repository-url>
cd <repository-directory>

Install dependencies:

pip install -r requirements.txt

(Alternatively, install the dependencies manually as listed above.)

Prepare the configuration file:

Create or edit a YAML file (e.g., config.yaml) with the following parameters:

output_dir: ./output
compression: lzw
resize_factor: 0.25
project: /path/to/ilastik_project.ilp
ilastik: /path/to/ilastik_executable
area_threshold: 50
closing_kernel_size: 11
aspect_ratio_min: 1.5
aspect_ratio_max: 5

---

Usage

Run the script with the following command:

python process_pipeline.py file1.czi file2.czi ... --config /path/to/config.yaml

Command-Line Arguments:

• file1.czi file2.czi ...: List of CZI files to process.
• --config /path/to/config.yaml: Path to the configuration file.

Example:

python process_pipeline.py sample1.czi sample2.czi --config config.yaml

---

How It Works

1. CZI File Processing:

   • The script reads tiled data from the CZI file and assembles it into a mosaic saved as a TIFF.

2. Segmentation:

   • The mosaic is passed to Ilastik in headless mode for segmentation.

3. Segmentation Correction:

   • Red Cluster Filtering: Red clusters (representing nodes of Ranvier) are identified based on:
     • Minimum area (area_threshold).
     • Aspect ratio (aspect_ratio_min, aspect_ratio_max).
   • Morphological Refinement:
     • Thin structures are removed using erosion + dilation.
     • Interruptions in nerve segments are filled with morphological closing.

4. Image Resizing:

   • Both the original mosaic and segmented outputs are resized using a scaling factor (resize_factor).

5. Intermediate File Cleanup:

   • Intermediate TIFF files are removed to save disk space.

---

Configuration Parameters

Parameter	Description	Example
output_dir	Directory where processed files are saved.	./output
compression	Compression type for TIFF files.	lzw
resize_factor	Scaling factor for resizing images.	0.25
project	Path to the Ilastik project file (.ilp).	/path/to/project.ilp
ilastik	Path to the Ilastik executable.	/path/to/ilastik
area_threshold	Minimum size of red clusters (nodes of Ranvier).	50
closing_kernel_size	Kernel size for filling interruptions in blue regions (nerve segments).	11
aspect_ratio_min	Minimum aspect ratio for identifying true nodes of Ranvier.	1.5
aspect_ratio_max	Maximum aspect ratio for identifying true nodes of Ranvier.	5

---

Output Files

• Original TIFF: The assembled mosaic from the input CZI file.
• Segmented TIFF: The output from Ilastik after pixel classification.
• Corrected TIFF: The segmented image after corrections for segmentation issues.
• Resized TIFFs: Resized versions of the original and segmented images.

---

Troubleshooting

1. Error: Ilastik not found:

   • Ensure the path to the Ilastik executable is correct in the configuration file.

2. FileNotFoundError for CZI files:

   • Verify the input file paths and ensure they exist.

3. Incorrect segmentation:

   • Adjust the area_threshold, aspect_ratio_min, and aspect_ratio_max in config.yaml.

---

License

This project is licensed under the MIT License. See the LICENSE file for details.