Glomeruli Detector

This site introduces an example of a glomeruli detector that detects glomeruli from Whole Slide Images.

We uses the Faster RCNN method and the Tensorflow Object Detection API for its implementation.

set up

Please set up by the following procedure.

Installing Tensorflow and Tensorflow Object Detection API

Please run through the installation instructions to install "Tensorflow Object Detection API" and all it dependencies.
Download our tools

Please download our glomeruli detection programs.
```
git clone https://github.com/jinseikenai/glomeruli_detection.git
```
dependencies

Our glomeruli detection programs depends on the following libraries. Please install the following libraries.
- OpenSlide
Operation Environment： We confirmed the operation in the following environment.
- python 3.5
- tensorflow 1.4.1

Quick Start

Quick Start Guide for getting Started to detection of glomeruli with our pre-traind models and sample WSIs.

Pre-trained models

We provide our pre-trained models trained on our WSI datasets.

Our pre-trained models are licensed under a Creative Commons Attribution-NonCommercial 4.0 International License.

Each of them is pre-trained for each staining type. Please choose a pre-trained model in accord with your purpose of use among the following inside.

PAS : for PAS(periodic acid-Schiff) stain slides.
PAM : for PAM(periodic acid-methenamine silver) stain slides.
MT : for MT(Masson trichrome) stain slides.
Azan : for Azan stain slides.

The downloaded files are compressed. You can un-tar each tar.gz file via, e.g.,:

tar -xvfz pas.train1.tar.gz

Even if there is no match exactly, if you find similar one in its characteristics, please try it. Or, you could try Transfer Learning on your data to detect glomeruli more correctly.

sample WSIs

The Whole Slide Images (WSIs) for your trial can be download from here. These data are not included in the training data of our pre-trained models.

These data are licensed under a Creative Commons Attribution-NonCommercial 4.0 International License.

Using these data, you could confirm the Faster R-CNN-Based Glomerular Detector and its result. Please see Quick Start Guide for how to do it.

Transfer Learning / Additional Learning

Based on our pre-trained model, you could do your transfer learning or additional learning.

For reference information on how to do learning, Please refer to the following notes, and my_train.py and my_trainer.py.

Data Preparation

Please prepare a set of learning data and annotations showing correct answers. And see the TensorFlow's "Preparing Inputs" manual and Programmer's Guide:"Importing Data".

Configuration

Please configure a variable "PATH_TO_BE_CONFIGURED" in "config/glomerulus_train.config" and "config/input.config" appropriately to your environment.

Learning Execution

You could execute learning with the following command.

python my_train.py --logtostderr \
  --train_dir=${TRAIN_DATA_PATH} \
  --model_config_path=${CONFIG_PATH}/glomerulus_model.config \
  --train_config_path=${CONFIG_PATH}/glomerulus_train.config \
  --input_config_path=${CONFIG_PATH}/input.config \
  --gpu_list=${GPU}

Set the path of learning data to ${TRAIN_DATA_PATH}
Set the path of configuration files to ${CONFIG_PATH}.
Set the path of directory of output files to ${TRAIN_DATA_PATH}.
Set the path of configuration files to ${CONFIG_PATH}. You could specify different paths for each.
- glomerulus_model.config
- glomerulus_train.config
- input.config
Set the GPU list you can use to ${GPU} like "--gpu_list=0,1" or "--gpu_list=1".

If you get the error message of "ValueError: Tried to convert 't' to a tensor and failed. Error: Argument must be a dense tensor: range(0, 3) - got shape [3], but wanted [].", Please check here and here.

List of programs

Here is the list of programs included in this repository listed by its function.

Glomeruli Detection Programs
1. detection : detect_glomus_test.py
2. merging overlapping regions : merge_overlaped_glomus.py
3. evaluation and visualization : eval_recall_precision_test.py
- common function : annotation_handler.py, glomus_handler.py
Transfer Learning / Additional Learning Programs
1. learning: my_train.py call my_trainer.py
  
  These programs for learning are almost the same as the original models/research/object_detection/train.py program. Please check the original latest source code to adapt to the latest Tensorflow Object Detection API.

jinseikenai / glomeruli_detection