huangzhii / nuclei.io

nuclei.io: Human-in-the-loop active learning framework for pathology image analysis

nuclei.io: Human-in-the-loop active learning framework for pathology image analysis

Introduction

This software is an open-release under the study of A pathologist–AI collaboration framework for enhancing diagnostic accuracies and efficiencies published in Nature Biomedical Engineering.

For the full information, please visit our homepage: https://huangzhii.github.io/nuclei-HAI/

Nuclei.io is a python-based platform, it can help achieve:

• Easy & fast human-in-the-loop active learning with real-time feedback.
• Single cell level annotation;
• Virtual flow cytometry & dynamic visualization;
• WSI-level cell statistics.

The codebase is built with Python, so you can plug in your AI/ML model in any way you want!

⚠️ Note: We are working hard to resolve the OS compatibility issue for a better user experience. Feel free to submit pull requests and improve it!

If you are a pathologist/user/developer who plan to use this software for annotating / analyzing whole slide pathology images, please follow the tutorial below.

Install nuclei.io and run on your Macbook now!

Youtube tutorial

Watch our 8-minute comprehensive tutorial on how to install and use nuclei.io by clicking the link below!

Initialization

We use Anaconda to manage the codes.

Note: If you do not have Anaconda yet, please follow this tutorial to install anaconda on your computer: https://docs.anaconda.com/free/anaconda/install/index.html

First thing first, clone our respository:

git clone https://github.com/huangzhii/nuclei.io.git

In this repository, we have some experimental data which are stored using git-lfs. If this is your first time using git-lfs, please follow this tutorial: https://docs.github.com/en/repositories/working-with-files/managing-large-files/installing-git-large-file-storage. You may want to use git lfs fetch and git lfs pull to retrieve the actual files inside experimental_data/.

Step 1. Initialize anaconda environment.

conda create -n nuclei.io python=3.10
conda activate nuclei.io
# Install dependencies
conda install openslide -c conda-forge # install openslide using conda.

Step 2. Install the software.

Open the nuclei.io folder, and then install the software via:

cd nuclei.io/
pip install -e .

Download example whole slide image.

Step 3. Create directory and download .svs files from the Internet.

cd nuclei.io/
mkdir example_data;
cd example_data;
mkdir CMU_Aperio;
mkdir CMU_Aperio/CMU-1;
mkdir CMU_Aperio/CMU-2;
wget -O CMU_Aperio/CMU-1/CMU-1.svs https://openslide.cs.cmu.edu/download/openslide-testdata/Aperio/CMU-1.svs
wget -O CMU_Aperio/CMU-2/CMU-2.svs https://openslide.cs.cmu.edu/download/openslide-testdata/Aperio/CMU-2.svs

Step 4. Run feature pre-calculation code for whole slide images.

Here, we simply run below python script to process the example images. Note: This feature pre-calculation should be better run on a Linux machine with GPU. We have not yet tried on Mac OS.

python feature_pre-calculation/main.py --slidepath "example_data/CMU_Aperio/CMU-1/CMU-1.svs" --stardist_dir "example_data/CMU_Aperio/CMU-1/stardist_results" --stage "all"
python feature_pre-calculation/main.py --slidepath "example_data/CMU_Aperio/CMU-2/CMU-2.svs" --stardist_dir "example_data/CMU_Aperio/CMU-2/stardist_results" --stage "all"

Start using nuclei.io to annotate and visualize your data.

python software/main.py

Now, on the sidebar, click "Browse local", and open the folder example_data/CMU_Aperio/CMU-1/.

After that, you can follow our Youtube tutorial on how to annotate and analyze the whole slide image.

Gallery

nuclei.io user study diagram.

nuclei.io experiment screenshot.

nuclei.io for neuropathology.

nuclei.io annotation session during CRC lymph node metastasis experiment.

Standing on the shoulders of giants

This software and research could not have been accomplished without being inspired by the ideas and codes from existing, exceptional visualization and feature calculation tools:

• QuPath
• SlideRunner
• Qt for Python
• OpenSlide
• Stardist
• HistomicsTK

nuclei.io's Issues

feature pre-calculation code cannot produce a result

Thanks for your great work.
When running feature pre-calculation code, it stopped just before the Stardist stage 3: deep learning feature extraction finished and no patches were saved.
I suspect it might be due to multithreading. Could you please figure out the reason.