FLASH: Framework for LArge-Scale Histomorphometry

This repository represents a python framework to train, evaluate and apply segmentation networks for renal histological analysis. In particular, we trained an nnUnet for kidney tissue segmentation followed by training another U-net-like CNN for the segmentation of several renal structures including tubulus, glomerulus, glomerular tuft, non-tissue background (including veins, renal pelvis), artery, and arterial lumen from PAS-stained histopathology data. In our experiments, we utilized human tissue data sampled from different cohorts including inhouse biopsies (UKA_B) and nephrectomies (UKA_N), the Human BioMolecular Atlas Program cohort (HuBMAP), the Kidney Precision Medicine Project cohort (KPMP), and the Validation of the Oxford classification of IgA Nephropathy cohort (VALIGA).

Installation

1. Clone this repo using git:
   

git clone https://git-ce.rwth-aachen.de/labooratory-ai/flash.git/

2. Install miniconda and use conda to create a suitable python environment as prepared in environment.yml that lists all library dependencies:
   

conda env create -f ./environment.yml

3. Activate installed python environment:

source activate python37

4. Install pytorch depending on your system:

conda install pytorch torchvision cudatoolkit=10.2 -c pytorch

Training

Train a structure segmentation network, e.g. using the following command:

python ./FLASH/training.py -m custom -s train_val_test -e 500 -b 6 -r 0.001 -w 0.00001

Note:

• Before, you need to specify the path to results folder (variable: resultsPath) in training.py and the path to your data set folder (variable: image_dir_base) in dataset.py
• training.py is parameterized as follows:

training.py --model --setting --epochs --batchSize --lrate --weightDecay 

• We trained the prior tissue segmentation network using the nnUnet repo.

Application

Use segment_WSI.py to apply the trained networks for tissue and histopathological renal structure segmentation to data of your choice.

python ./FLASH/segment_WSI.py

Note: Before running the script, you need to specify the path to the image folder (variable: WSIrootFolder), both network paths (variable: model_FG_path and modelpath), and the results folder (variable: resultsPath).
In particular, the script will recursively walk through all WSIs in a specified folder hierarchy and first apply the tissue segmentation CNN for segmentation. For this, the tissue is resampled to the expected pixel spacing by the CNN. The structure segmentation network is then applied to the detected tissue regions. After post-processing, the final prediction results are then saved using several (overlay) images as well as stored in numpy arrays for further feature analysis.

Feature computation

Use compute_features.py to extract different morphological features from the predicted segmentations.

python ./FLASH/compute_features.py

Note: The script outputs a feature table for all structures in a .csv file. Each row contains features from a different instance and can thus be used to identify the instances.

Besides, you can also apply the trained network to our provided exemplary image patches contained in the folder exemplaryData. These patches show various pathologies and are listed below including our ground-truth annotation:

Cohort	Annotation
UKA_B	Annotation
UKA_N	Annotation
HuBMAP	Annotation
KPMP	Annotation

Contact

Peter Boor, MD, PhD
Institute of Pathology
RWTH Aachen University Hospital
Pauwelsstrasse 30
52074 Aachen, Germany
Phone: +49 241 80 85227
Fax: +49 241 80 82446
E-mail: pboor@ukaachen.de

/**************************************************************************
*                                                                         *
*   Copyright (C) 2022 by RWTH Aachen University                          *
*   http://www.rwth-aachen.de                                             *
*                                                                         *
*   License:                                                              *
*                                                                         *
*   This software is dual-licensed under:                                 *
*   • Commercial license (please contact: pboor@ukaachen.de)              *
*   • AGPL (GNU Affero General Public License) open source license        *
*                                                                         *
***************************************************************************/