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在该领域的贡献如下:
- Standardized baseline：nnU-Net是生物医学细分领域第一个标准化的深度学习基准。无需人工操作，研究人员就可以在任意数量的数据集上将他们的算法与nnU-Net进行比较，从而为提出的改善提供有意义的证据。
- Out-of-the-box segmentation method:nnU-Net是第一个用于最先进的生物医学细分的即插即用工具 plug-and-play tool。没有经验的用户可以使用nnU-Net开箱即用来解决他们的定制3D分割问题，而不需要人工干预。
- 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进行研究，也请引用这篇论文!
目录
How to run nnU-Net on a new dataset
Experiment planning and preprocessing
Identifying the best U-Net configuration
How to run inference with pretrained models
Information on run time and potential performance bottlenecks.
安装
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。
- 安装PyTorch.。您至少需要1.6版本。
- 安装nnU-Net取决于你的需求:
- 用于标准化基线，开箱即用的分割算法或运行推理与预先训练的模型:
pip install nnunet - 作为集成框架使用(这将在您的计算机上创建一个nnU-Net代码的副本，以便您可以根据需要修改它):
git clone https://github.com/MIC-DKFZ/nnUNet.git cd nnUNet pip install -e .
- 用于标准化基线，开箱即用的分割算法或运行推理与预先训练的模型:
- 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_integrityXXX是与任务名称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包含验证指标(在文件末尾提供所有案例的平均值)。
Multi GPU training
Multi GPU training is experimental and NOT RECOMMENDED!
nnU-Net支持两种不同的多gpu实现:DataParallel (DP) and Distributed Data Parallel (DDP) (但目前只在一个主机上!)DDP比DP快，如果可能的话应该是首选。但是，如果您没有将nnunet作为一个框架安装(这意味着您使用了pip install nnunet变体)，则DDP不可用。它需要一种不同的方式来调用正确的python脚本(见下文)，这是我们无法从终端命令中支持的。
分布式培训当前仅适用于基本培训（2D, 3D full resolution and 3D low resolution），不适用于级联的第二个high resolution U-Net 。原因是分布式训练需要对网络和损失函数做一些改变，需要一个新的nnUNet trainer class.到目前为止，这还没有为级联实现，但将来可能会添加。
要运行分布式培训（DP），请使用以下命令：
CUDA_VISIBLE_DEVICES=0,1,2... nnUNet_train_DP CONFIGURATION nnUNetTrainerV2_DP TASK_NAME_OR_ID FOLD -gpus GPUS --dbs
注意，nnUNetTrainerV2被nnUNetTrainerV2_DP替换。与以前一样，CONFIGURATION可以是2d、3d_lowres或3d_fullres。TASK_NAME_OR_ID是你想要训练的任务，FOLD是交叉验证的折叠。GPUS(integer value)指定要训练的gpu数量。要指定你想使用的GPUs，请使用CUDA_VISIBLE_DEVICES环境变量来指定GPU ids(使用-gpus 来指定多个gpu)。--dbs，如果设置，将在gpu上分配批处理大小batch size。因此，如果nnUNet配置批处理大小为2，并且运行在2个GPU上，那么每个GPU运行的批处理大小 batch size为1。如果你忽略-dbs，每个GPU将以完整的批处理大小运行(在这个例子中每个GPU 2个批处理大小为4)。
要运行DDP训练，您必须将nnU-Net作为一个框架安装。您当前的工作目录必须是nnunet文件夹(包含dataset_conversion, evaluation, experiment_planning，…子文件夹)。然后，您可以使用以下命令运行DDP训练:
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
XXXX必须是一个用于process-process通信的开放端口(在大多数系统上是4321)。Y是您希望使用的GPUs数量。请记住，我们(还)不支持跨计算节点的分布式培训。这些都发生在同一个系统上。同样，您可以使用CUDA_VISIBLE_DEVICES=0,1,2来控制所使用的gpu。如果在同一个系统上运行多个DDP训练(假设您有4个gpu，运行两个训练，每个都有2个gpu)，则需要为每个培训指定一个不同的 --master_port !
IMPORTANT! 多gpu训练产生的模型不能轻易用于推理(如上所述，所有这些都是实验性的;-))。完成所有折叠的训练后，在训练模型所在的文件夹上运行nnUNet_change_trainer_class(参见nnUNet_change_trainer_class -h获取说明)。然后就可以运行推断了。
Identifying the best U-Net configuration
一旦所有的模型都训练好了，使用下面的命令来自动决定使用什么样的U-Net配置来进行测试集预测:
nnUNet_find_best_configuration -m 2d 3d_fullres 3d_lowres 3d_cascade_fullres -t XXX --strict
(所有指定的配置都需要完成所有的5 folds!)，对于未配置级联的数据集，请使用-m 2d 3d_fullres代替。如果您希望只研究配置的某些子集，可以使用-m命令指定。我们建议设置--strict(如果请求的某个配置缺失将导致崩溃)标志。可以使用其他选项(使用-h获得帮助)。
Run inference
请记住，位于输入文件夹中的数据必须遵循这里指定的格式。
nnUNet_find_best_configuration将用您需要使用的推断命令将一个字符串打印到终端。运行推断的最简单方法是使用这些命令。
如果您希望手动指定用于推理的配置，可以使用以下命令:
对于每个需要的配置，运行:
nnUNet_predict -i INPUT_FOLDER -o OUTPUT_FOLDER -t TASK_NAME_OR_ID -m CONFIGURATION --save_npz
仅当您打算使用集成ensembling时才指定--save_npz。--save_npz将使命令保存softmax概率以及预测的分割掩码需要大量的磁盘空间。
请为每个配置选择单独的OUTPUT_FOLDER !
如果您希望运行ensembling，您可以使用以下命令从几个配置集成预测:
nnUNet_ensemble -f FOLDER1 FOLDER2 ... -o OUTPUT_FOLDER -pp POSTPROCESSING_FILE
您可以指定任意数量的文件夹，但是请记住，每个文件夹都需要包含nnUNet_predict生成的npz文件。对于集成ensembling，还可以指定一个文件，该文件告诉命令如何后处理。这些文件是在运行nnUNet_find_best_configuration时创建的，并且位于相应的训练模型目录中。(RESULTS_FOLDER/nnUNet/CONFIGURATION/TaskXXX_MYTASK/TRAINER_CLASS_NAME__PLANS_FILE_IDENTIFIER/postprocessing.json or RESULTS_FOLDER/nnUNet/ensembles/TaskXXX_MYTASK/ensemble_X__Y__Z--X__Y__Z/postprocessing.json)
How to run inference with pretrained models
作者参与的所有挑战的训练模型都是公开的。它们可以通过nnU-Net直接下载和安装。请注意，下载一个预先训练过的模型将覆盖使用完全相同的configuration(2d、3d_fullres，…)、trainer(nnUNetTrainerV2)和plans训练过的其他模型。
要获得可用模型的列表，以及简短的描述，请运行
nnUNet_print_available_pretrained_models
然后，您可以通过指定模型的任务名称来下载模型。以 Liver and Liver Tumor Segmentation Challenge为例，这将是:
nnUNet_download_pretrained_model Task029_LiTS
下载完成后，您可以使用该模型来运行推断。请记住，每个模型都有特定的数据需求(Task029_LiTS运行在腹部CT扫描上，其他模型需要以特定顺序输入多个图像形态)。
当使用预先训练的模型时，您必须遵守它们所训练的数据集的许可，如果您运行nnUNet_download_pretrained_model，您将找到一个链接，可以在其中找到每个数据集的许可证。
Examples
为了让您入门，作者编译了两个简单易懂的示例：
Extending or Changing nnU-Net
请参考本指南。
Information on run time and potential performance bottlenecks.
我们在许多不同的gpu上编制了一个标准化数据集的预期epoch时间列表。您可以使用它们来验证您的系统是否按照预期运行。还有一些关于如何识别瓶颈以及如何解决瓶颈的提示。参照此处。
Common questions and issues
作者收集了常见问题和问题的解决方案。开新问题前请查阅这些文件。
扫一扫
2705
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
