HoVer-Net复现：手把手带你实现细胞核的分割与分类，并输出叠加图像

小罗碎碎念

先说一下，只要你跟着我一步一步走，你能实现的效果——对细胞核进行分割和分类，并在原始图像上以颜色叠加的方式直观地展示这些结果。

昨天我在交流群里进行了一下预热，并且提供了一些前期的教程，反响还不错，私聊与我交流的也很多。我准备了两期推文，这一期介绍基础知识，讲解代码仓库里的文件与脚本的作用，同时介绍要想训练模型，或者运用模型进行推理，你需要修改哪些参数。

在掌握了第一期推文的基础上，我会再出一期，讲解如何把这个模型迁移到自己的数据上。两期推文看下来，相信你一定能建立起一个非常系统的认知，并且后续看到任何模型的时候，你都不会觉得无从下手了。

我是罗小罗同学，明天见！！

交流群

欢迎大家来到【医学AI】交流群，本群设立的初衷是提供交流平台，方便大家后续课题合作。

目前群内成员已达三位数，大部分来自全国百强医院/前50院校。此外，小罗也借助自媒体，与华盛顿大学、北大、北航、华科、北科、南方医等院校的课题组建立了联系，欢迎更多的人加入我们的队伍！！

由于近期入群推销人员较多，已开启入群验证，扫码添加我的联系方式，备注姓名-单位-科室/专业，即可邀您入群。

一、`HoVer-Net`概述

HoVer-Net是一个用于多组织显微图像中细胞核的实例分割和分类的多分支网络。该网络利用细胞核像素的水平和垂直距离来区分聚集的细胞，并使用专门的上采样分支来对每个分割实例进行核类型的分类。

接下来要介绍的代码，是HoVer-Net的官方版本，并且提供了训练模型权重——这些权重在CoNSeP、PanNuke、MoNuSAC、Kumar和CPM17等数据集上进行了训练。提供了环境设置指令、代码库结构、主要可执行脚本的说明，以及训练和推理的使用和选项。

训练之前，需要设置数据目录、检查点保存路径和预训练的Preact-ResNet50权重。训练和推理的数据格式要求是将图像块存储为具有特定通道的多维NumPy数组。提供了训练和推理的命令行使用示例，包括如何可视化数据集、使用GPU进行训练、以及如何进行推理。

此外，还提供了模型权重的链接，这些权重可以用于处理输入图像或WSI（全切片图像），并且提到了使用这些权重时需要引用的论文。最后，还提供了一些用于比较PyTorch实现与原始TensorFlow实现的分割结果的表格。

二、设置环境

友情提醒，后续的操作我是在服务器上进行的，并且我的电脑是macos，所以界面和你的可能有所不同，但是流程是一样的，你做一个替换就行。

2-1：克隆仓库

首先进入你要克隆的仓库页面，复制仓库地址。

https://github.com/vqdang/hover_net.git

登陆服务器

我这里用的是Royal，不同软件操作界面不一样。

新建一个目录

mkdir h_net

进入新建的目录

cd h_net

克隆仓库

git clone https://github.com/vqdang/hover_net.git

成功界面如下。

2-2：检查仓库

查看一下仓库中的文件目录

cd hover_net
ls -ltr

你稍微扫一眼就会发现，这和你在github上看到的文件是一样的。这一步主要是想让我们养成一个细心的习惯，同时掌握一下查看仓库内容的方法。

2-3：构造虚拟环境

下面这段代码包含两个部分，一部分是使用conda创建和管理Python环境，另一部分是使用pip安装特定版本的PyTorch和torchvision库。

conda env create -f environment.yml：
这行命令使用conda创建一个新的Python环境。conda是一个开源的包管理系统和环境管理系统，可以轻松地安装、运行和更新包和它们的依赖项。env create命令用于创建一个新的环境。-f标志后面跟着environment.yml文件，这个文件包含了环境配置的详细信息，比如要安装哪些包和它们的版本。
conda activate hovernet：
这行命令用于激活一个名为hovernet的conda环境。一旦环境被激活，后续的所有操作（比如安装新的包或者运行Python脚本）都会在这个环境中进行，与系统默认的Python环境相互隔离。
pip install torch==1.6.0 torchvision==0.7.0：
这行命令使用pip安装特定版本的PyTorch和torchvision库。pip是Python的包安装器，install命令用于安装包。torch==1.6.0指定安装PyTorch的1.6.0版本，torchvision==0.7.0指定安装torchvision的0.7.0版本。torchvision是PyTorch的一个图形库，它为PyTorch提供了大量的数据集、模型和图像处理工具。

综上所述，这段代码首先根据environment.yml文件创建一个名为hovernet的conda环境，然后激活这个环境，最后在这个环境中安装了指定版本的PyTorch和torchvision库。这样做的好处是，你可以为不同的项目创建不同的环境，每个环境都有自己独立的依赖项，从而避免了不同项目间依赖项的冲突。

安装依赖项&创建虚拟环境

conda env create -f environment.yml

激活虚拟环境

conda activate hovernet

注意箭头指向。

安装PyTorch

pip install torch==1.6.0 torchvision==0.7.0

三、代码库结构

代码库结构是软件开发中组织文件和目录的一种方式，它有助于维护和理解项目。

以下是HoVer-Net项目代码库的主要目录和文件的详细解释：

dataloader/：包含数据加载器和数据增强流程的代码。数据加载器负责从存储介质中读取数据并将其组织成适合模型训练和推理的格式。数据增强则是通过一系列操作（如旋转、缩放、裁剪等）来增加数据的多样性，从而提高模型的泛化能力。
docs/：存放代码库中使用的图表和GIF动画。这些视觉资料有助于理解项目的工作原理和结果展示。
metrics/：包含用于计算性能指标的脚本。性能指标是评估模型效果的关键数据，例如准确率、召回率、F1分数等。
misc/：存放一些实用工具和辅助功能，它们可能在多个地方被复用，但不属于核心功能。
models/：包含模型定义、主要运行步骤和超参数设置。这是定义神经网络结构、选择损失函数、优化器等核心组件的地方。
run_utils/：定义训练/验证循环和回调函数。训练循环是模型学习数据的过程，而回调函数可以在训练过程中的特定时刻执行额外的操作，如保存模型、打印日志等。

以下是代码库中的主要可执行脚本：

config.py：配置文件，包含了项目运行所需的各种配置参数，如文件路径、网络参数等。
dataset.py：定义数据集类的脚本，这些类用于封装数据集的加载和处理逻辑。
extract_patches.py：用于从原始图像中提取图像块的脚本。这些图像块是模型训练和推理的输入。
compute_stats.py：主要的统计量计算脚本，用于在训练和推理后计算模型的性能指标。
run_train.py：主要的训练脚本，用于启动模型的训练过程。
run_infer.py：主要的推理脚本，用于对图像块和全切片图像（WSI）进行模型推理。
convert_chkpt_tf2pytorch：一个转换脚本，用于将原始代码库中使用TensorFlow训练的模型（.npz格式）转换为PyTorch支持的模型（.tar格式）。

这些脚本和目录的组织方式确保了项目的模块化和可维护性，同时也方便了开发者和研究人员对项目进行贡献和扩展。

四、训练模型

4-1：数据格式

在HoVer-Net项目中，数据格式是模型训练和推理过程中输入数据的组织方式，它对模型的性能和训练效率有直接影响。

以下是对数据格式要求的详细解释：

训练数据格式：
- 使用extract_patches.py脚本从原始图像中提取图像块（patches）。这些图像块是用于训练模型的基本单元。
- 对于实例分割任务，每个图像块被存储为一个四维NumPy数组，包含以下通道：
  - RGB：代表红、绿、蓝三个颜色通道，是图像的常规颜色表示。
  - inst：实例分割的真实标注（ground truth），用于指示图像中每个像素属于哪个实例。像素值从0到N，其中0代表背景，N代表该图像中细胞核实例的总数。
- 对于同时进行实例分割和分类的任务，图像块被存储为一个五维NumPy数组，增加的通道为：
  - type：细胞核类型的真值标注，用于指示每个像素属于哪个类别。像素值从0到K，其中0代表背景，K代表类别的总数。
训练前的配置：
- 在config.py配置文件中设置数据目录的路径，这是模型训练时读取图像块的来源。
- 同样在config.py中设置保存检查点（checkpoints）的路径，检查点是在训练过程中的模型状态，用于保存和恢复训练过程。
- 在models/hovernet/opt.py文件中设置预训练的Preact-ResNet50权重的路径。Preact-ResNet50是一个预训练的网络模型，可以加速收敛并提高模型性能。需要从指定的链接下载这些权重。
- 在models/hovernet/opt.py中修改超参数，包括训练的轮数（epochs）和学习率（learning rate）。超参数是控制模型训练过程的重要参数，需要根据具体情况进行调整以获得最佳性能。

通过上述步骤，可以确保HoVer-Net模型在训练前正确地加载和处理数据，同时通过适当的超参数设置来优化训练过程。这些准备工作对于实现高质量的细胞核分割和分类至关重要。

4-2：使用方法&选项

接下来将讲解，如何使用HoVer-Net项目中的run_train.py脚本进行模型训练，并提供了一些选项和示例来说明如何使用这些命令。

1、命令行使用说明：

python run_train.py [--gpu=<id>] [--view=<dset>]：这是启动训练脚本的基本命令格式。其中，--gpu=<id>和--view=<dset>是可选参数。
- --gpu=<id>：指定用于训练的GPU设备编号。可以是单个GPU（如--gpu=0）或多个GPU的列表（如--gpu=0,1），用于并行加速训练过程。
- --view=<dset>：可视化训练或验证数据集的图像增强效果。可以选择'train'或'valid'，分别代表训练集和验证集。

2、帮助和版本信息：

python run_train.py (-h | --help)：显示帮助信息，列出所有可用的命令行选项和它们的说明。
python run_train.py --version：显示当前脚本的版本信息。

3、选项说明：

-h --help：显示帮助信息。
--version：显示版本信息。
--gpu=<id>：指定用于训练的GPU列表，多个GPU编号用逗号分隔。
--view=<dset>：选择可视化的数据集，可以是训练集或验证集。

4、示例：

可视化训练数据集：
- python run_train.py --view='train'：在开始训练之前，使用此命令可以对训练数据集进行可视化检查，以确保数据增强的效果符合预期。
使用多个GPU进行训练：
- python run_train.py --gpu='0,1'：此命令初始化训练脚本，使用编号为0和1的两个GPU设备进行训练。这可以加快训练速度，尤其是在处理大型数据集或复杂模型时。

通过这些命令和选项，用户可以灵活地控制HoVer-Net模型的训练过程，包括选择使用哪些GPU资源以及如何检查数据增强的效果。这些功能对于确保模型训练的顺利进行和优化训练效果至关重要。

五、模型推理

在HoVer-Net项目中，推理（Inference）阶段是模型训练完成后，使用训练好的模型对新的数据进行分析和预测的过程。

5-1：输入数据格式（Input）

支持标准的图像文件格式，包括PNG、JPG和TIFF等。
支持由OpenSlide库支持的全切片图像（Whole-Slide Images, WSIs），包括SVS、TIF、N DPI和Mrxs等格式。这些格式通常用于存储和处理显微图像数据。

5-2：输出数据格式（Output）

JSON文件：对于图像块（tiles）和全切片图像，输出包含以下键（keys）的JSON文件：
- 'bbox'：每个细胞核的边界框坐标。
- 'centroid'：每个细胞核的质心坐标。
- 'contour'：每个细胞核的轮廓坐标。
- 'type_prob'：每个细胞核属于各个类别的概率（默认配置不输出此信息）。
- 'type'：每个细胞核预测的类别。
MAT文件：仅图像块输出，包含以下键的MAT文件：
- 'raw'：网络的原始输出（默认配置不输出此信息）。
- 'inst_map'：实例映射，包含从0到N的值，其中N是图像中细胞核的数量。
- 'inst_type'：长度为N的列表，包含每个细胞核的预测结果。
PNG叠加图：图像块还会输出一个PNG格式的叠加图，将细胞核边界叠加在原始RGB图像上。这使得可以直接在原始图像上可视化细胞核的分割和分类结果。

5-3：推理过程的详细步骤

数据输入：首先，将标准图像文件或全切片图像作为输入数据提供给推理脚本。
模型推理：使用训练好的模型对输入数据进行处理，得到细胞核的分割和分类结果。
结果输出：将推理结果以JSON和MAT文件的形式输出，包括细胞核的位置、轮廓、类别概率等信息。
可视化：对于图像块，生成一个PNG叠加图，直观展示细胞核的边界和分类结果。

这种数据格式的设计使得HoVer-Net的推理结果既可以用于进一步的分析和研究，也可以直接用于临床诊断和病理学研究，提供了丰富的信息和直观的可视化效果。

5-4：代码使用说明

接下来介绍使用HoVer-Net进行推理的命令行工具run_infer.py的使用说明和选项。

基本使用说明（Usage）:

run_infer.py [options] [--help] <command> [<args>...]：这是执行推理操作的基本命令格式，其中[options]是可选参数，<command>和<args>是命令和参数。
run_infer.py --version：显示当前脚本的版本信息。
run_infer.py (-h | --help)：显示帮助信息。

选项（Options）:

-h --help：显示帮助信息。
--version：显示版本信息。
--gpu=<id>：指定用于推理的GPU编号，默认为0。
--nr_types=<n>：预测的细胞核类型数量，默认为0。
--type_info_path=<path>：指定一个JSON文件的路径，该文件定义了类型ID、类型名称和预期的叠加颜色映射，默认为空。
--model_path=<path>：指定保存的检查点文件路径。
--model_mode=<mode>：选择原始HoVer-Net模型或用于PanNuke / MoNuSAC的简化版本，‘original’或’fast’，默认为fast。
--nr_inference_workers=<n>：推理过程中的工作线程数，默认为8。
--nr_post_proc_workers=<n>：后处理过程中的工作线程数，默认为16。
--batch_size=<n>：批处理大小，默认为128。

图像块处理选项（Tile Processing Options）:

--input_dir=<path>：输入数据目录的路径。
--output_dir=<path>：输出目录的路径。
--draw_dot：是否在叠加图上绘制细胞核质心，默认为False。
--save_qupath：是否以QuPath v0.2.3兼容格式输出，默认为False。
--save_raw_map：是否保存原始预测结果，默认为False。

全切片图像处理选项（WSI Processing Options）:

--input_dir=<path>：输入数据目录的路径。
--output_dir=<path>：输出目录的路径。
--cache_path=<path>：缓存路径，应放置在至少有100GB空间的SSD上，默认为’cache’。
--mask_dir=<path>：包含组织掩膜的目录路径，应与相应的WSIs同名，默认为空。
--proc_mag=<n>：用于WSI处理的放大倍数，默认为40。
--ambiguous_size=<int>：在平铺网格上定义模糊区域的大小，以便进行重新后处理，默认为128。
--chunk_shape=<n>：处理的块的形状，默认为10000。
--tile_shape=<n>：处理的瓦片的形状，默认为2048。
--save_thumb：是否保存缩略图，默认为False。
--save_mask：是否保存掩膜，默认为False。

执行和缓存：

提供了两个示例可执行脚本：一个用于图像块处理，一个用于WSI处理。使用前需要通过chmod +x命令使其可执行，然后通过./run_tile.sh和./run_wsi.sh运行。
中间结果存储在缓存中，因此需要确保指定的缓存位置有足够的空间，并且最好是SSD。

模型模式选择：

运行推理时，选择正确的模型模式非常重要。'original’模式指的是原始论文中描述的方法，270x270像素的输入和80x270像素的输出；
'fast’模式使用256x256像素的输入和164x164像素的输出。Kumar、CPM17和CoNSeP的检查点来自原始出版物，因此必须使用’original’模式。对于PanNuke和MoNuSAC，必须选择’fast’模式。
提供的每个检查点的模型模式在文件名中给出。如果使用的模型仅用于分割，nr_types必须设置为0。

类型信息和输出：

type_info.json用于指定叠加图中使用的RGB颜色。根据不同的数据集或一般控制叠加边界颜色的需求进行修改。
作为图像块处理实现的一部分，添加了一个选项，以与QuPath兼容的格式保存输出。

示例和文档：

examples/usage.ipynb提供了如何使用输出的示例。

六、模型权重

在HoVer-Net项目中，模型权重（Model Weights）是训练过程中学习到的参数，它们对于模型的推理能力至关重要。

6-1：模型权重的来源和使用

训练获得的权重：按照项目提供的指南训练HoVer-Net后，所得到的模型权重可以用来处理输入图像或全切片图像（WSIs）。
预训练模型权重：除了自己训练得到的权重外，项目还提供了一些预训练的模型权重，这些可以直接用于数据的处理。

6-2：预训练权重的来源

这些预训练的权重最初是使用TensorFlow框架训练的，后来通过convert_chkpt_tf2pytorch.py脚本转换成了PyTorch框架支持的格式。

6-3：权重训练的类型

分割和分类：一些检查点（checkpoints）是为同时进行分割和分类任务而训练的。
仅分割：对于CPM17和Kumar数据集，由于没有可用的分类标签，因此只提供了仅用于分割任务的模型权重。

6-4：模型模式的重要性

原始模型模式：CoNSeP、Kumar和CPM17的检查点使用的是原始模型模式。
快速模型模式：PanNuke和MoNuSAC使用的是快速模型模式。这两种模式在输入输出尺寸和可能的处理速度上可能有所不同。

6-5：检查点列表

分割和分类任务的检查点包括：
- CoNSeP检查点
- PanNuke检查点
- MoNuSAC检查点
仅分割任务的检查点包括：
- CoNSeP检查点
- Kumar检查点
- CPM17检查点

通过使用这些预训练的模型权重，研究人员和开发人员可以在不进行从头训练的情况下，快速地对新的数据进行细胞核的分割和分类，从而加快研究和开发进程。同时，确保引用原论文是对原作者工作的认可和尊重，也是学术研究的基本规范。

七、叠加预测结果分析

在HoVer-Net项目中，经过训练的模型能够对细胞核进行分割和分类，并在原始图像上以颜色叠加的方式直观地展示这些结果。

7-1：叠加结果（Overlaid results）

HoVer-Net在CoNSeP数据集上训练后，可以生成叠加了分割和分类预测结果的图像。在这种图像中，不同的颜色代表不同类型的细胞核。

7-2：颜色编码（Colour coding）

蓝色（Blue）：上皮细胞（epithelial）。这代表了一种类型的细胞核，通常与上皮组织相关。
红色（Red）：炎症细胞（inflammatory）。这类细胞核与炎症反应相关，可能在病理分析中具有重要意义。
绿色（Green）：梭形细胞（spindle-shaped）。这种类型的细胞核具有特定的形态特征，可能与某些类型的肿瘤相关。
青色（Cyan）：其他类型（miscellaneous）。这个分类可能包括那些不属于上述任何特定类型的细胞核。

7-3：叠加预测的用途

直观展示：颜色叠加提供了一种直观的方式来展示模型的预测结果，使得观察者可以快速识别和区分不同类型的细胞核。
病理分析：在病理学研究和临床诊断中，这种直观的展示方式可以帮助病理学家快速识别和分析病变区域。
模型验证：通过视觉检查叠加结果，研究人员可以评估模型的性能，验证其分割和分类的准确性。

7-4：技术实现

这种颜色叠加是通过在图像处理过程中将预测的细胞核边界与相应的颜色信息相结合来实现的。
通常，这涉及到为每个预测的细胞核实例生成一个遮罩，并根据其分类结果应用相应的颜色。

7-5：结果的应用

叠加结果可以用于进一步的定量分析，例如计算每种类型细胞核的数量、分布等。
它们也可以作为训练和优化模型的反馈，帮助改进模型的性能。

通过这种方式，HoVer-Net不仅能够提供分割和分类的预测，还能够以一种易于理解和解释的形式展示这些信息，从而在医学图像分析中发挥重要作用。

八、数据集

在HoVer-Net项目中，数据集是进行模型训练、验证和测试的基础。

8-1：数据集下载（Datasets）

CoNSeP数据集：一个公开的医学图像数据集，通常用于细胞核分割和分类任务。
其他数据集：Kumar、CPM-15、CPM-17和TNBC数据集同样包含了用于医学图像分析的显微图像。

在这里插入图片描述

8-2：数据集的组成（Ground truth files）

这些数据集包含的真值文件（ground truth files）采用.mat格式存储。
.mat格式是MATLAB的数据文件格式，广泛用于存储数组、矩阵和其他数据结构。

8-3：数据集使用说明（README）

下载数据集时，每个数据集都会附带一个README文件。
这个文件包含了数据集的详细信息和使用说明，如数据集的组织结构、如何访问和使用数据集中的图像和真值文件等。

8-4：数据集的重要性（Importance）:

训练和验证：数据集为模型提供了训练和验证所需的输入数据和真值标签，是模型学习的基础。
性能评估：通过与真值文件的比较，可以评估模型在分割和分类任务上的性能。
科学研究：数据集支持科学研究和算法开发，推动医学图像分析领域的发展。

通过上述信息，用户可以了解如何获取和使用HoVer-Net项目中涉及的数据集，以及如何利用这些数据集进行模型的训练、验证和性能评估。

九、分割结果比较

这段文本提供了HoVer-Net模型在不同深度学习框架（TensorFlow和PyTorch）下训练的分割结果的比较。

9-1：分割结果比较

目的：报告使用当前代码库（基于PyTorch）训练的分割结果与原始手稿中报告的结果（基于TensorFlow）之间的差异。

9-2：分割结果

Kumar数据集：
- 平台：
  - TensorFlow：获得了0.8258的DICE系数、0.5971的PQ（Per-Cell Quality）和0.6412的AJI（Average JI，平均Jaccard指数）。
  - PyTorch：获得了0.8211的DICE系数、0.5904的PQ和0.6321的AJI。
- 这些指标显示PyTorch实现的分割结果与TensorFlow相当，尽管在PQ和AJI上略有下降。
CoNSeP数据集：
- 平台：
  - TensorFlow：获得了0.8525的DICE系数、0.5477的PQ和0.5995的AJI。
  - PyTorch：获得了0.8504的DICE系数、0.5464的PQ和0.6009的AJI。
- 同样，PyTorch实现在CoNSeP数据集上的表现与TensorFlow相似，仅有微小的性能差异。

9-3：F1分数

平台：
- TensorFlow：在不同的细胞类型（F1d、F1e、F1i、F1s、F1m）上分别获得了0.748、0.635、0.631、0.566和0.426的F1分数。
- PyTorch：在相同的细胞类型上分别获得了0.756、0.636、0.559、0.557和0.348的F1分数。
F1分数是精确度和召回率的调和平均值，用于衡量模型在分类任务上的性能。PyTorch实现在某些细胞类型上的F1分数略高于TensorFlow，而在其他类型上则略低或相似。