• NCRF
• 前提条件
• 数据
  • 全切片图像
  • 标注
  • 补丁图像
• 模型
• 训练
• 测试
  • 组织掩膜
  • 概率图
  • 肿瘤定位
  • FROC评估

NCRF

本仓库包含用于复现论文主要结果的代码和数据：

Yi Li 和 Wei Ping. 基于神经条件随机场的癌症转移检测。医学影像与深度学习（MIDL），2018年。

如果您觉得这些代码或数据有用，请引用上述论文：

@inproceedings{li2018cancer,
    title={Cancer Metastasis Detection With Neural Conditional Random Field},
    booktitle={Medical Imaging with Deep Learning},
    author={Li, Yi and Ping, Wei},
    year={2018}
}

如有任何问题，请在 GitHub 问题页面留言，或发送邮件至 yil8@uci.edu

前提条件

• Python (3.6)

• Numpy (1.14.3)

• Scipy (1.0.1)

• PyTorch (0.3.1)/CUDA 8.0 具体的二进制 wheel 文件为 cu80/torch-0.3.1-cp36-cp36m-linux_x86_64.whl。我尚未在其他版本上进行测试，尤其是 0.4 及以上版本，因此不建议使用其他版本。

• torchvision (0.2.0)

• PIL (5.1.0)

• scikit-image (0.13.1)

• OpenSlide 3.4.1（请勿使用 3.4.0 版本，因为该版本存在一些潜在问题）/openslide-python (1.1.0)

• matplotlib (2.2.2)

• tensorboardX 这是一个与 TensorBoard 兼容且适用于 PyTorch 的工具，主要用于监控训练曲线。

• QuPath 虽然与模型的训练和测试没有直接关系，但我发现它非常有助于可视化全切片图像。

大多数依赖项都可以通过 pip 安装指定版本，例如：

pip install 'numpy==1.14.3'

或者简单地：

pip install numpy

我们还提供了一个 requirements.txt 文件，以便您可以一次性安装大部分依赖项：

pip install -r requirements.txt -i https://pypi.python.org/simple/

对于 PyTorch，请考虑下载特定的 wheel 二进制文件并使用以下命令：

pip install torch-0.3.1-cp36-cp36m-linux_x86_64.whl

数据

全切片图像

主要数据是来自 Camelyon16 挑战赛的 *.tif 格式全切片图像（WSI）。您需要向 Camelyon16 申请数据访问权限，获批后可以从 Google Drive 或百度网盘下载。请注意，一张切片在第 0 层通常约为 10 万 x 10 万像素，占用磁盘空间超过 1GB。总共有 400 张切片，合计约 700GB 以上，因此请确保您有足够的磁盘空间。用于训练的肿瘤切片命名为 Tumor_XXX.tif，其中 XXX 从 001 到 110；用于训练的正常切片命名为 Normal_XXX.tif，其中 XXX 从 001 到 160。用于测试的切片命名为 Test_XXX.tif，其中 XXX 从 001 到 130。

下载所有切片后，请将用于训练的所有肿瘤切片和正常切片放在同一个目录下，例如 /WSI_TRAIN/。

更新

目前，全切片图像 *tif 文件已可在 GigaDB 上免费下载。但为了规范数据使用，请仍与 Camelyon16 组织者联系。

标注

Camelyon16 组织者还提供了每张肿瘤切片的肿瘤区域标注，格式为 XML。我已将其转换为更为简单的 JSON 格式，位于 NCRF/jsons 目录下。每个标注都是一个多边形列表，每个多边形由其顶点表示。其中，正多边形表示肿瘤区域，负多边形表示正常区域。您也可以使用以下命令将 XML 格式转换为 JSON 格式：

python NCRF/wsi/bin/camelyon16xml2json.py Tumor_001.xml Tumor_001.json

补丁图像

尽管原始的 400 张 WSI 文件包含了所有必要信息，但它们并不适合直接用于训练深度 CNN。因此，我们需要采样更小的图像补丁，例如 256x256，这是典型的深度 CNN 所能处理的尺寸。高效地采样具有信息量且具有代表性的补丁，是实现良好肿瘤检测性能的关键环节之一。 为了简化这一过程，我在本仓库中包含了论文中用于训练的预采样补丁坐标，位于 NCRF/coords 目录下。每个文件都是 CSV 格式，每行的格式类似于 Tumor_024,25417,127565，其中最后两个数字分别是补丁中心在第 0 层的 (x, y) 坐标。tumor_train.txt 和 normal_train.txt 分别包含 20 万个坐标，而 tumor_valid.txt 和 normal_valid.txt 分别包含 2 万个坐标。需要注意的是，硬负样本的坐标，通常位于组织边界区域，也包含在 normal_train.txt 和 normal_valid.txt 中。借助原始 WSI 和预采样的坐标，我们现在可以生成用于训练深度 CNN 模型的图像补丁。运行以下四条命令以生成相应的补丁：

python NCRF/wsi/bin/patch_gen.py /WSI_TRAIN/ NCRF/coords/tumor_train.txt /PATCHES_TUMOR_TRAIN/
python NCRF/wsi/bin/patch_gen.py /WSI_TRAIN/ NCRF/coords/normal_train.txt /PATCHES_NORMAL_TRAIN/
python NCRF/wsi/bin/patch_gen.py /WSI_TRAIN/ NCRF/coords/tumor_valid.txt /PATCHES_TUMOR_VALID/
python NCRF/wsi/bin/patch_gen.py /WSI_TRAIN/ NCRF/coords/normal_valid.txt /PATCHES_NORMAL_VALID/

其中，/WSI_TRAIN/ 是您存放所有用于训练的 WSI 文件的目录路径，如上所述；/PATCHES_TUMOR_TRAIN/ 是用于存储生成的肿瘤训练补丁的目录路径。其他目录命名规则与此类似：/PATCHES_NORMAL_TRAIN/、/PATCHES_TUMOR_VALID/ 和 /PATCHES_NORMAL_VALID/。默认情况下，每条命令会使用 5 个进程生成 768x768 大小的第 0 层补丁，补丁中心对应于提供的坐标。每个 768x768 的补丁将进一步分割成 3x3 的 256x256 小补丁，以便在利用 CRF 的训练算法时使用。

需要注意的是，使用 5 个进程生成 20 万个 768x768 补丁大约耗时 4.5 小时，生成的文件大小约为 202GB。

模型

NCRF 的核心思想是将一个由补丁组成的网格作为输入，例如 3x3 网格，使用 CNN 模块提取补丁的嵌入表示，并利用 CRF 模块建模这些补丁之间的空间相关性。CNN 模块源自 torchvision 发布的标准 ResNet（https://github.com/pytorch/vision/blob/master/torchvision/models/resnet.py）。主要区别在于前向传播过程中：1. 输入张量多了一个维度；2. 使用 CRF 模块通过补丁的嵌入表示对每个补丁的 logits 进行平滑处理。

def forward(self, x):
    """
    Args:
        x: 5D 张量，形状为
        [batch_size, grid_size, 3, crop_size, crop_size],
        其中 grid_size 是网格内补丁的数量（例如 3x3 网格为 9）；crop_size 默认为 ResNet 输入的 224；
    Returns:
        logits，2D 张量，形状为 [batch_size, grid_size]，表示网格内每个补丁属于肿瘤的 logits
    """
    batch_size, grid_size, _, crop_size = x.shape[0:4]
    # 将 grid_size 维度展平并合并到 batch 维度中
    x = x.view(-1, 3, crop_size, crop_size)

    x = self.conv1(x)
    x = self.bn1(x)
    x = self.relu(x)
    x = self.maxpool(x)

    x = self.layer1(x)
    x = self.layer2(x)
    x = self.layer3(x)
    x = self.layer4(x)

    x = self.avgpool(x)
    # feats 表示特征，即来自 ResNet 的补丁嵌入
    feats = x.view(x.size(0), -1)
    logits = self.fc(feats)

    # 恢复 grid_size 维度以便进行 CRF 处理
    feats = feats.view((batch_size, grid_size, -1))
    logits = logits.view((batch_size, grid_size, -1))

    if self.crf:
        logits = self.crf(feats, logits)

    logits = torch.squeeze(logits)

    return logits

CRF 模块仅有一个可训练参数 W，用于补丁之间的成对势能。你可以通过以下命令从已训练 CRF 模型的 ckpt 文件中绘制 W（参见下一节）：

python NCRF/wsi/bin/plot_W.py /PATH_TO_MODEL/best.ckpt

当 CRF 模型训练良好时，W 通常反映了输入网格中不同补丁之间的相对空间位置。有关模型的更多详细信息，请参阅我们的论文。

训练

有了生成的补丁图像，我们现在可以使用以下命令训练模型：

python NCRF/wsi/bin/train.py /CFG_PATH/cfg.json /SAVE_PATH/

其中 /CFG_PATH/ 是 JSON 格式的配置文件路径，而 /SAVE_PATH/ 是你希望以 checkpoint (ckpt) 格式保存模型的地方。在 NCRF/configs 中提供了两个配置文件，其中一个适用于带有 CRF 的 ResNet-18：

{
 "model": "resnet18",
 "use_crf": true,
 "batch_size": 10,
 "image_size": 768,
 "patch_size": 256,
 "crop_size": 224,
 "lr": 0.001,
 "momentum": 0.9,
 "data_path_tumor_train": "/PATCHES_TUMOR_TRAIN/",
 "data_path_normal_train": "/PATCHES_NORMAL_TRAIN/",
 "data_path_tumor_valid": "/PATCHES_TUMOR_VALID/",
 "data_path_normal_valid": "/PATCHES_NORMAL_VALID/",
 "json_path_train": "NCRF/jsons/train",
 "json_path_valid": "NCRF/jsons/valid",
 "epoch": 20,
 "log_every": 100
}

请分别将 /PATCHES_TUMOR_TRAIN/、/PATCHES_NORMAL_TRAIN/、/PATCHES_TUMOR_VALID/ 和 /PATCHES_NORMAL_VALID/ 修改为你自己生成的补丁图像路径。同时，请根据你本地 NCRF 仓库的完整路径修改 NCRF/jsons/train 和 NCRF/jsons/valid。另一个配置文件适用于不带 CRF 的 ResNet-18（基准模型）。

默认情况下，train.py 使用 1 个 GPU (GPU_0) 来训练模型，2 个进程加载肿瘤补丁图像，2 个进程加载正常补丁图像。在一台 GTX 1080Ti 上，训练 1 个 epoch 大约需要 5 小时，完成 20 个 epoch 则需要 4 天。你还可以使用 tensorboard 监控训练过程：

tensorboard --logdir /SAVE_PATH/

通常，你会观察到 CRF 模型的训练准确率始终高于基准模型。

train.py 会生成一个 train.ckpt，即最近保存的模型，以及一个 best.ckpt，即验证准确率最高的模型。我们还在 NCRF/ckpt 中提供了预训练的 resnet18_base 和 resnet18_crf 的 best.ckpt。

测试

组织掩膜

经过训练的模型用于 WSI 分析的主要测试结果是概率图，它表示模型认为 WSI 上哪些区域是肿瘤区域。最简单的方法是采用滑动窗口的方式，在整张切片上逐个预测所有补丁是否为肿瘤。但由于 WSI 的大部分区域实际上是白色背景，这种滑动窗口方式会浪费大量计算资源。因此，我们首先计算一个二值组织掩膜，用于标识每个补丁是组织还是背景，然后只在组织区域进行肿瘤预测。典型的 WSI 及其组织掩膜如下所示（Test_026）： 要获取给定输入 WSI 的组织掩膜，例如 Test_026.tif，运行以下命令：

python NCRF/wsi/bin/tissue_mask.py /WSI_PATH/Test_026.tif /MASK_PATH/Test_026.npy

其中 /WSI_PATH/ 是你感兴趣的 WSI 路径，而 /MASK_PATH/ 是你希望以 numpy 格式保存生成的组织掩膜的路径。默认情况下，组织掩膜是在第 6 层生成的，对应于 64 像素的推理步长，即在第 0 层每 64 像素进行一次预测。 这里附上了 Test_026_tissue_mask.npy 在第 6 层的组织掩膜供参考。请注意，使用 matplotlib.pyplot.imshow 绘制时，需先对其进行转置。

概率图

借助生成的组织掩膜，我们现在可以使用训练好的模型为给定的WSI（例如Test_026.tif）获取概率图：

python NCRF/wsi/bin/probs_map.py /WSI_PATH/Test_026.tif /CKPT_PATH/best.ckpt /CFG_PATH/cfg.json /MASK_PATH/Test_026.npy /PROBS_MAP_PATH/Test_026.npy

其中，/WSI_PATH/是您感兴趣的WSI文件路径；/CKPT_PATH/是您保存训练模型的目录，而best.ckpt对应于验证准确率最高的模型；/CFG_PATH/是训练模型配置文件的路径，格式为JSON，通常与/CKPT_PATH/相同；/MASK_PATH/是您保存生成的组织掩膜的路径；/PROBS_MAP_PATH/则是您希望以NumPy格式保存生成的概率图的路径。

默认情况下，probs_map.py会使用GPU_0进行推理，并启用5个进程加载数据。需要注意的是，尽管我们会加载一个补丁网格（例如3×3），但为了便于实现，仅保留中心补丁的预测概率。由于计算开销较大，生成一张WSI的概率图通常需要0.5至1小时。我们正在考虑开发更高效的推理算法来生成概率图。 该图展示了Test_026在不同设置下的概率图：(a) 原始WSI，(b) 真实标注，(c) 基线方法，(d) 采用困难负样本挖掘的基线方法，(e) 结合困难负样本挖掘的NCRF。我们可以看到，基线方法生成的概率图通常存在大量孤立的假阳性区域。通过引入困难负样本挖掘，基线方法的假阳性数量显著减少，但同时真实肿瘤区域内的概率密度也随之降低，从而削弱了模型的敏感性。相比之下，结合困难负样本挖掘的NCRF不仅能够有效降低假阳性，还能在真实肿瘤区域内保持较高的概率密度，且边界更加清晰。

附上Test_026_probs_map.npy在第6级下的概率图，供对比参考。请注意，使用matplotlib.pyplot.imshow绘制时，需先对其进行转置。

肿瘤定位

我们利用非极大值抑制（NMS）算法，根据概率图在第0级获取每个检测到的肿瘤区域的坐标。

python NCRF/wsi/bin/nms.py /PROBS_MAP_PATH/Test_026.npy /COORD_PATH/Test_026.csv

其中，/PROBS_MAP_PATH/是您保存生成的概率图的路径，而/COORD_PATH/则是您希望以CSV格式保存各肿瘤区域在第0级坐标的路径。该脚本提供了一个可选参数--level，其默认值为6，请确保它与用于生成相应组织掩膜和概率图的级别一致。

FROC评估

有了每张测试WSI中肿瘤区域的坐标后，我们最终可以评估肿瘤定位的平均FROC分数。

python NCRF/wsi/bin/Evaluation_FROC.py /TEST_MASK/ /COORD_PATH/

/TEST_MASK/是存放测试集真实标注TIFF掩膜文件的路径，而/COORD_PATH/则是保存生成的肿瘤坐标文件的路径。Evaluation_FROC.py基于Camelyon16组织方提供的评估代码并进行了少量修改。需要注意的是，根据Camelyon16组织方的说明，Test_049和Test_114不参与本次评估。

NCRF 快速上手指南

NCRF (Neural Conditional Random Field) 是一个用于癌症转移检测的深度学习工具，基于全切片图像（WSI）进行肿瘤定位。本指南将帮助你快速搭建环境并运行模型。

环境准备

在开始之前，请确保你的系统满足以下要求：

• 操作系统: Linux (推荐，官方测试环境为 Linux x86_64)
• Python: 3.6
• GPU: 支持 CUDA 8.0 的 NVIDIA 显卡
• 磁盘空间: 建议预留 800GB+ 空间（原始 WSI 数据约 700GB+，生成的补丁数据约 200GB+）

核心依赖版本说明： 本项目对版本要求严格，特别是 PyTorch，强烈建议使用指定版本，其他版本（尤其是 0.4+）可能导致兼容性问题。

• PyTorch: 0.3.1 (CUDA 8.0)
• torchvision: 0.2.0
• Openslide: 3.4.1 (请勿使用 3.4.0)
• 其他库：Numpy, Scipy, PIL, scikit-image, matplotlib, tensorboardX 等

安装步骤

1. 安装基础依赖

你可以使用提供的 requirements.txt 一键安装大部分 Python 依赖。为了加速下载，推荐使用国内镜像源（如清华源或阿里源）。

pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple/

如果上述命令失败，也可以手动安装关键库：

pip install 'numpy==1.14.3' 'scipy==1.0.1' 'Pillow==5.1.0' 'scikit-image==0.13.1' 'matplotlib==2.2.2' 'tensorboardX' -i https://pypi.tuna.tsinghua.edu.cn/simple/

2. 安装 PyTorch (关键步骤)

由于官方不再直接提供旧版 wheel 文件的便捷安装命令，你需要先下载特定的二进制文件，然后本地安装。

下载指定版本的 Wheel 文件：

wget http://download.pytorch.org/whl/cu80/torch-0.3.1-cp36-cp36m-linux_x86_64.whl

(注：如果下载速度慢，可尝试寻找国内镜像站点的缓存，或手动下载后上传至服务器)

安装 PyTorch 和 torchvision：

pip install torch-0.3.1-cp36-cp36m-linux_x86_64.whl
pip install 'torchvision==0.2.0' -i https://pypi.tuna.tsinghua.edu.cn/simple/

3. 安装 OpenSlide

OpenSlide 需要系统级安装，请根据你的 Linux 发行版执行相应命令（以 Ubuntu 为例）：

sudo apt-get update
sudo apt-get install libopenslide0 openslide-tools
pip install 'openslide-python==1.1.0' -i https://pypi.tuna.tsinghua.edu.cn/simple/

注意：务必确保 libopenslide 版本为 3.4.1，避免使用 3.4.0。

基本使用

本项目的核心流程包括：数据准备 -> 生成图像补丁 (Patches) -> 训练模型 -> 测试推理。以下是基于已有 Camelyon16 数据的极简操作流程。

1. 数据准备

你需要从 Camelyon16 或 GigaDB 获取 .tif 格式的全切片图像 (WSI)。 假设你将所有训练用的肿瘤切片 (Tumor_XXX.tif) 和正常切片 (Normal_XXX.tif) 放置在 /WSI_TRAIN/ 目录下。

2. 生成训练补丁 (Patch Generation)

WSI 图像过大，无法直接输入 CNN。需利用仓库中预提供的坐标文件 (NCRF/coords/) 截取补丁。

运行以下命令生成训练集和验证集的补丁（默认生成 768x768 的大图，后续会在模型中切割）：

# 生成肿瘤训练补丁
python NCRF/wsi/bin/patch_gen.py /WSI_TRAIN/ NCRF/coords/tumor_train.txt /PATCHES_TUMOR_TRAIN/

# 生成正常训练补丁 (包含硬负样本)
python NCRF/wsi/bin/patch_gen.py /WSI_TRAIN/ NCRF/coords/normal_train.txt /PATCHES_NORMAL_TRAIN/

# 生成肿瘤验证补丁
python NCRF/wsi/bin/patch_gen.py /WSI_TRAIN/ NCRF/coords/tumor_valid.txt /PATCHES_TUMOR_VALID/

# 生成正常验证补丁
python NCRF/wsi/bin/patch_gen.py /WSI_TRAIN/ NCRF/coords/normal_valid.txt /PATCHES_NORMAL_VALID/

提示：生成约 20 万张补丁在 5 进程下耗时约 4.5 小时，占用磁盘约 202GB。

3. 配置与训练

修改配置文件 NCRF/configs/resnet18_crf.json (参考原文中的 JSON 结构)，将数据路径替换为你实际生成的补丁路径，例如：

• data_path_tumor_train: /PATCHES_TUMOR_TRAIN/
• data_path_normal_train: /PATCHES_NORMAL_TRAIN/
• ...以及其他验证集路径。

启动训练（默认使用 GPU 0）：

python NCRF/wsi/bin/train.py NCRF/configs/resnet18_crf.json /SAVE_PATH/

• /SAVE_PATH/ 是模型检查点保存目录。
• 可使用 tensorboard --logdir /SAVE_PATH/ 监控训练曲线。
• 训练完成后会生成 best.ckpt (验证集最佳模型)。

4. 测试与推理

测试阶段主要生成组织掩膜 (Tissue Mask) 和肿瘤概率图。

步骤 A: 生成组织掩膜 排除白色背景区域，仅对组织区域进行预测，以提高效率。

python NCRF/wsi/bin/tissue_mask.py /WSI_PATH/Test_026.tif /MASK_PATH/Test_026.npy

步骤 B: 生成概率图与肿瘤定位 (注：具体测试脚本命令在原文截断部分之前未完全展示，通常遵循类似 test.py 的模式，加载 best.ckpt 和生成的 mask 进行推理。请参考仓库中完整的 testing 章节或源码获取后续具体命令。)

---

更多细节（如 FROC 评估、可视化权重矩阵 W 等）请参阅项目原始 README 或相关论文。