Published release of MuTILs

This is the original release of the published version of MuTILs by @kheffah.

A panoptic segmentation dataset and deep-learning approach for explainable scoring of tumor-infiltrating lymphocytes
Shangke Liu, Mohamed Amgad, Deeptej More, Muhammad A. Rathore, Roberto Salgado & Lee A. D. Cooper
npj | Breast Cancer volume 10, Article number: 52 (2024)

The repository consist of 3 main folders (mutils_panoptic, configs, utils) and a linked folder to a specific commit of histolab submodule @ 954a0c9. The repository also has a setup.py, a requirements.txt file.

• mutils_panoptic has the core modules including the training, the inference, and the model files.
  • mutils_panoptic/MuTILsWSIRunner.py runs WSI segmentation and analysis. It is the module to run for inference.
  • mutils_panoptic/MuTILsInference.py performs the inference itself, it is called by MuTILsWSIRunner.py.
  • mutils_panoptic/MuTILs.py has the torch model implemented for training and for inference.
  • mutils_panoptic/Unet.py is the implementation of the model architecture.
  • mutils_panoptic/MuTILsMaskVisualizer.py generates the visualization of the segmentation as large TIF image.
  • mutils_panoptic/MuTILsTrainer.py is for training new models.
  • mutils_panoptic/MuTILsAnalyticalValidation.py evaluates the training by calculating the segmentation accuracy.
  • mutils_panoptic/RegionDatasetLoaders.py loads and sets data for training MuTILs models.
• configs has the configuration files to run MuTILs.
  • configs/MuTILsWSIRunConfigs.py has quasi data classes with cohort-specific configurations.
  • configs/region_GTcodes.csv and configs/nucleus_GTcodes.csv have color codes for segmentation visualization.
  • configs/nucleus_style_defaults.py defines standardized annotation styles, color schemes, and hierarchical category mappings.
  • configs/panoptic_model_configs.py defines hierarchical categorizations and configurations for outputs. An issue was resolved related to this file.
• utils has the utilities for MuTILs.
  • utils/GeneralUtils.py has general-purpose utility functions and classes.
  • utils/MiscRegionUtils.py has image processing utility functions.
  • utils/RegionPlottingUtils.py has visualization utility functions.
  • utils/TorchUtils.py has utility functions for PyTorch.
  • utils/torchvision_transforms.py is the custom version of PyTorch's transforms module.

Using MuTILs needs a custom environment with all dependencies installed. One option is using a Docker container kheffah/ctme:latest:

docker run --name Mutils \
   --gpus '"device=0"' \
   -v /path/to/MuTILs_Panoptic/repository:/home/mtageld/Desktop/MuTILs_Panoptic \
   -v /path/to/input/data:/data \
   --ulimit core=0 \
   --rm \
   -it \
   kheffah/ctme:latest