nnunet(十四) readme_--verify_dataset_integrity作用

https://github.com/MIC-DKFZ/nnUNet/blob/master/readme.md

nnU-Net

在三维生物医学图像分割中，数据集属性如图像模态modality、图像尺寸sizes、体素间距spacings、类比class ratios等变化很大。例如， Liver and Liver Tumor Segmentation Challenge dataset中的图像是计算机断层扫描(CT)扫描，约512x512x512体素大，具有各向同性体素间隔，其强度值是定量的(Hounsfield Units)。另一方面， Automated Cardiac Diagnosis Challenge dataset 显示了 cine MRI 中的心脏结构，其典型图像形状为10 × 320 × 320体素，高度各向异性体素spacings 和定性强度值。此外，如果处理不当，ACDC数据集还会遭受切片没对齐和Z轴spacing的异质性，这可能会导致严重的插值伪影。

在目前的研究实践中，分割管道segmentation pipelines是在脑海真的一个特定的数据集手动设计的。许多管道设置直接或间接依赖于数据集的属性,并显示一个复杂的共同依赖:图像大小,例如,影响补丁的大小 patch size,进而影响所需的网络的接受域,一个因素本身影响其他几个管道中的超参hyperparameters in the pipeline。因此，在一个(类型)数据集上开发的管道与领域中的其他数据集固有不兼容。

nnU-Net是第一个针对领域中发现的数据集多样性而设计的分割方法。它压缩和自动化的关键决定设计一个成功的分割管道为任何给定的数据集。它为任何给定的数据集浓缩和自动的设计一个成功的分割管道做一个关键决定。

nnU-Net在该领域的贡献如下:

1. Standardized baseline：nnU-Net是生物医学细分领域第一个标准化的深度学习基准。无需人工操作，研究人员就可以在任意数量的数据集上将他们的算法与nnU-Net进行比较，从而为提出的改善提供有意义的证据。
2. Out-of-the-box segmentation method:nnU-Net是第一个用于最先进的生物医学细分的即插即用工具 plug-and-play tool。没有经验的用户可以使用nnU-Net开箱即用来解决他们的定制3D分割问题，而不需要人工干预。
3. Framework：nnU-Net是一个快速有效发展分割方法的框架。由于它的模块化结构，新的架构和方法可以很容易地集成到nnU-Net。研究人员可以从它的通用特性中受益，在一个标准化的环境中，在任意数量的数据集上推出并评估他们的修改。

有关nnU-Net的更多信息，请阅读以下文章：

Isensee, F., Jaeger, P. F., Kohl, S. A., Petersen, J., & Maier-Hein, K. H. (2020). nnU-Net: a self-configuring method 
for deep learning-based biomedical image segmentation. Nature Methods, 1-9.

如果您正在使用nnU-Net进行研究，也请引用这篇论文!

目录

nnU-Net

安装

Usage

How to run nnU-Net on a new dataset

Dataset conversion

Experiment planning and preprocessing

Model training

Identifying the best U-Net configuration

Run inference

How to run inference with pretrained models

Examples

Extending or Changing nnU-Net

Information on run time and potential performance bottlenecks.

Common questions and issues

安装

nnU-Net已经在Linux (Ubuntu 16, 18和20;centOS, RHEL)测试过来。作者不提供对其他操作系统的支持。

nnU-Net需要GPU!针对推理，GPU应该有4 GB的VRAM。对于nnU-Net模型训练，GPU应该至少有10 GB(流行的非数据中心选项是RTX 2080ti, RTX 3080或RTX 3090)。由于使用了自动混合精度，在以简单的方式安装pytorch时，使用Volta架构(Titan V, V100 gpu)可以实现最快的训练时间。由于pytorch自带cuDNN 7.6.5，本版本不支持 Turing GPUs上用于3D卷积的张量核心加速，因此您将无法在Turing GPUs上获得最佳的训练速度。您可以通过使用cuDNN 8.0.2或从源代码编译pytorch更新版本来解决这个问题。这将解锁Turing GPUs  (RTX 2080ti, RTX 6000)用于3D卷积自动混合精度训练，并加速训练。请注意，pytorch的未来版本，默认情况下可能包括cuDNN 8.0.2或更新版本，不需要从源代码进行编译。作者还不知道使用vanilla和自编译pytorch的Ampere gpu的速度——一旦作者知道了，这部分将会更新。

对于训练，我们建议使用强大的CPU来配合GPU。建议CPU核数至少为6个(12个线程)。CPU需求主要与数据扩充和输入通道数量的放缩有关。因此，对于BraTS这样使用4种图像模式的数据集，它们的值较高，而对于LiTS这样只使用CT图像的数据集，它们的值较低。

作者强烈建议您在虚拟环境中安装nnU-Net。 Here is a quick how-to for Ubuntu如果你选择从源代码编译pytorch，你将需要使用conda而不是pip。在这种情况下，请设置环境变量OMP_NUM_THREADS=1(最好在您的bashrc中使用export OMP_NUM_THREADS=1)。这很重要。

Python 2已弃用且不受支持。请确保您使用的是python3。

1. 安装PyTorch.。您至少需要1.6版本。
2. 安装nnU-Net取决于你的需求:
   1. 用于标准化基线，开箱即用的分割算法或运行推理与预先训练的模型:pip install nnunet
   2. 作为集成框架使用(这将在您的计算机上创建一个nnU-Net代码的副本，以便您可以根据需要修改它):

      git clone https://github.com/MIC-DKFZ/nnUNet.git
      cd nnUNet
      pip install -e .
      

       

3. nnU-Net需要知道您打算在哪里保存原始数据、预处理数据和训练过的模型。为此，您需要设置一些环境变量。请按照下面的说明。(可选)安装hiddenlayer.。hiddenlayer使nnU-net能够生成它生成的网络拓扑图(参见Model training)。安装hiddenlayer，执行如下命令:

pip install --upgrade git+https://github.com/FabianIsensee/hiddenlayer.git@more_plotted_details#egg=hiddenlayer

安装nnU-Net将向您的终端添加几个新命令。这些命令用于运行整个nnU-Net管道。您可以在系统上的任何位置执行它们。所有nnU-Net命令都带有前缀nnUNet_，以便于识别。

请注意，这些命令仅执行python脚本。如果在虚拟环境中安装了nnU-Net，则在执行命令时必须激活该环境。所有nnU-Net命令都有-h选项，该选项提供有关如何使用它们的信息。

nnU-Net的典型安装可以在不到5分钟的时间内完成。如果pytorch需要从源代码编译（这是我们目前建议在使用Turing GPU时的），则可能会延长一个多小时。

Usage

为了使自己熟悉nnU-Net，我们建议您先查看Examples，然后再开始使用自己的数据集。

How to run nnU-Net on a new dataset

给定一些数据集，nnU-Net会完全自动配置与其属性匹配的整个分割管道。nnU-Net涵盖从预处理到模型配置，模型训练，后处理到组装的整个流程。在运行nnU-Net之后，可以将训练后的模型应用于测试用例以进行推断。

Dataset conversion

nnU-Net期望数据集采用结构化格式。这种格式密切(但不完全)遵循Medical Segmentation Decthlon的数据结构。请阅读这篇文章了解如何将数据集转换为nnU-Net兼容的格式。

Experiment planning and preprocessing

作为第一步，nnU-Net提取数据指纹dataset fingerprint (一组数据特定的属性，如图像大小sizes、体素间距spacings、强度intensity信息等)。这些信息用于创建三种U-Net配置:2D U-Net, 3D full resolution  U-Net，以及3D U-Net cascade，其中第一个个U-Net在下采样的图像中创建粗分割图，然后通过第二个U-Net进行细化。

前提是请求的原始数据集位于正确的文件夹中(nnUNet_raw_data_base/nnUNet_raw_data/TaskXXX_MYTASK, 参照此处)，然后可以使用如下命令执行此步骤:

nnUNet_plan_and_preprocess -t XXX --verify_dataset_integrity

XXX是与任务名称TaskXXX_MYTASK相关联的整数标识符。您可以一次传递多个任务id。运行nnUNet_plan_and_preprocess将用预处理数据放入该文件夹。您可以在nnUNet_preprocessed/TaskXXX_MYTASK中找到输出。nnUNet_plan_and_preprocess为2D U-Net和所有适用的3D U-Net创建预处理数据的子文件夹。它还将为2D和3D配置创建“plans”文件(以.pkl结尾)。这些文件包含生成的分割管道配置，nnUNetTrainer将读取这些文件(见下文)。注意，预处理数据文件夹只包含训练集。测试图像没有经过预处理(它们根本看不到!)，它们的预处理是在推理过程中进行的。

--verify_dataset_integrity至少应该在给定数据集上第一次运行时运行该命令。这将对数据集执行一些检查，以确保它与nnU-Net兼容。如果此检查通过了一次，则可以在以后的运行中忽略它。如果你坚持数据集转换指南(见上面)，那么通过应该没有问题:-)

注意nnUNet_plan_and_preprocess接受几个额外的输入参数。运行-h将会列出所有它们以及一个描述。如果在预处理期间耗尽了RAM，您可能需要调整使用-tl和-tf选项的进程数量。

在nnUNet_plan_and_preprocess完成后，U-Net配置已经创建，数据的预处理副本将位于nnunet_preprocessing/TaskXXX_MYTASK。

提取数据集指纹dataset fingerprint 可能需要几秒到几分钟，这取决于分割任务的属性。对于提取的指纹，管道配置Pipeline configuration 几乎是即时的(几秒钟)。预处理取决于图像大小和CPU的性能。这可能需要几秒钟到几十分钟。

Model training

nnU-Net以5倍交叉验证 5-fold cross-validation训练所有U-Net配置。这使nnU-Net能够确定训练数据集的后处理和集成postprocessing and ensembling (参见下一步)。默认情况下，所有的U-Net配置都需要在给定的数据集上运行。然而，在某些情况下，只需要某些配置(甚至可能不需要运行交叉验证)。有关更多信息，请参见FAQ。

注意，并不是所有的U-Net配置都是为所有的数据集创建的。在图像尺寸较小的数据集中，U-Net级联被省略，因为全分辨率U-Net的patch大小已经覆盖了输入图像的很大一部分。

训练模型使用nnUNet_train命令完成。该命令的一般结构是:

nnUNet_train CONFIGURATION TRAINER_CLASS_NAME TASK_NAME_OR_ID FOLD  --npz (additional options)

CONFIGURATION是标识请求的U-Net配置的字符串。TRAINER_CLASS_NAME是模型训练器的名称。如果您实现了自定义训练器(nnU-Net作为一个框架)，您可以在这里指定您的自定义训练器。TASK_NAME_OR_ID指定应该训练的数据集，FOLD指定训练5- FOLD交叉验证的几个FOLD。

nnU-Net每50个epochs存储一个检查点checkpoint。如果需要继续以前的训练，只需在训练命令中添加一个-c。

IMPORTANT:--npz使模型在最终验证期间保存softmax输出。它应该只用于您计划之后运行nnUNet_find_best_configuration的培训(这是nnU-Nets自动选择最佳性能(集成ensemble)配置configuration，见下文)。如果你正在开发新的 trainer classes，你可能不需要softmax预测，因此应该忽略-npz标志。导出的softmax预测非常大，因此会占用大量磁盘空间。如果您最初运行时没有使用--npz标志，但现在需要softmax预测，那么只需运行即可生成它们。这将只重新运行验证，而不是训练。

nnUNet_train CONFIGURATION TRAINER_CLASS_NAME TASK_NAME_OR_ID FOLD -val --npz

参见nnUNet_train -h了解其他选项。

2D U-Net

对[0,1,2,3,4]的折叠，运行:

nnUNet_train 2d nnUNetTrainerV2 TaskXXX_MYTASK FOLD --npz

3D full resolution U-Net

对[0,1,2,3,4]的折叠，运行:

nnUNet_train 3d_fullres nnUNetTrainerV2 TaskXXX_MYTASK FOLD --npz

 3D U-Net cascade

对[0,1,2,3,4]的折叠，运行:

nnUNet_train 3d_cascade_fullres nnUNetTrainerV2CascadeFullRes TaskXXX_MYTASK FOLD --npz

请注意，级联的3D full resolution U-Net of the cascade需要提前完成low resolution U-Net的五次折five folds!

训练的模型将写入RESULTS_FOLDER/nnUNet文件夹。每次训练得到一个自动生成的输出文件夹名:

nnUNet_preprocessed/CONFIGURATION/TaskXXX_MYTASKNAME/TRAINER_CLASS_NAME__PLANS_FILE_NAME/FOLD
 

例如，对于Task002_Heart(来自MSD)，如下所示:

RESULTS_FOLDER/nnUNet/
├── 2d
│   └── Task02_Heart
│       └── nnUNetTrainerV2__nnUNetPlansv2.1
│           ├── fold_0
│           ├── fold_1
│           ├── fold_2
│           ├── fold_3
│           └── fold_4
├── 3d_cascade_fullres
├── 3d_fullres
│   └── Task02_Heart
│       └── nnUNetTrainerV2__nnUNetPlansv2.1
│           ├── fold_0
│           │   ├── debug.json
│           │   ├── model_best.model
│           │   ├── model_best.model.pkl
│           │   ├── model_final_checkpoint.model
│           │   ├── model_final_checkpoint.model.pkl
│           │   ├── network_architecture.pdf
│           │   ├── progress.png
│           │   └── validation_raw
│           │       ├── la_007.nii.gz
│           │       ├── la_007.pkl
│           │       ├── la_016.nii.gz
│           │       ├── la_016.pkl
│           │       ├── la_021.nii.gz
│           │       ├── la_021.pkl
│           │       ├── la_024.nii.gz
│           │       ├── la_024.pkl
│           │       ├── summary.json
│           │       └── validation_args.json
│           ├── fold_1
│           ├── fold_2
│           ├── fold_3
│           └── fold_4
└── 3d_lowres

注意3d_lowres和3d_cascade_fullres没有被填充，因为这个数据集没有触发级联。在每个模型训练输出文件夹(每个fold_x文件夹，共10个)中，将创建以下文件(为简洁起见，仅显示上面的一个文件夹):

• debug.json：包含用于训练该模型的蓝图blueprint和推断参数 inferred parameters 的摘要。不容易阅读，但对调试非常有用;-)
• model_best.model / model_best.model.pkl: 训练过程中识别的最佳模型的检查点checkpoint文件。现在还没有使用。
• model_final_checkpoint.model / model_final_checkpoint.model.pkl:最终模型的检查点checkpoint文件(训练结束后)。这是用于验证validation和推断inference的。
• network_architecture.pdf (仅当安装了hiddenlayer!):一个带有网络架构图的pdf文档
• progress.png:训练期间训练（蓝色）和验证（红色）损失的图。还显示了评估度量的近似值(绿色)。这个近似值是前景类的平均Dice得分。然而,它并不能全信,因为它是计算验证集随机patch在每个epoch的结束画的,并且补丁来自相同的volume，然后计算这些patch的TP、FP和FN的Dice聚合(“global Dice'”;我们不会对每个验证案例计算一个Dice，然后对所有的情况进行平均，而是假装只有一个验证案例，我们可以从中抽取补丁)。这样做的原因是“global Dice”在训练过程中很容易计算，并且在评估模型是否在训练时仍然非常有用。在训练结束时进行适当的验证。
• validation_raw：在这个文件夹中是培训结束后预测的验证集。summary.json包含验证指标(在文件末尾提供所有案例的平均值)。

CUDA_VISIBLE_DEVICES=0,1,2... nnUNet_train_DP CONFIGURATION nnUNetTrainerV2_DP TASK_NAME_OR_ID FOLD -gpus GPUS --dbs

CUDA_VISIBLE_DEVICES=0,1,2... python -m torch.distributed.launch --master_port=XXXX --nproc_per_node=Y run/run_training_DDP.py CONFIGURATION nnUNetTrainerV2_DDP TASK_NAME_OR_ID FOLD --dbs

nnUNet_find_best_configuration -m 2d 3d_fullres 3d_lowres 3d_cascade_fullres -t XXX --strict

nnUNet_predict -i INPUT_FOLDER -o OUTPUT_FOLDER -t TASK_NAME_OR_ID -m CONFIGURATION --save_npz

nnUNet_ensemble -f FOLDER1 FOLDER2 ... -o OUTPUT_FOLDER -pp POSTPROCESSING_FILE

nnUNet_print_available_pretrained_models

nnUNet_download_pretrained_model Task029_LiTS