CLAM

全切片图像上的数据高效、弱监督计算病理学。 自然生物医学工程

ArXiv | 期刊链接 | 交互式演示 | 引用

简而言之： CLAM 是一种高通量且可解释的方法，用于在不进行 ROI 提取或补丁级标注的情况下，仅使用切片级标签实现数据高效的全切片图像（WSI）分类，并且能够处理多类别亚型问题。该方法已在三个不同的 WSI 数据集上进行了测试，训练好的模型可以适应独立的 WSI 切除和活检测试队列，以及智能手机显微镜图像（显微照片）。

CLAM：基于深度学习的数据高效、弱监督全切片级分析流程

先决条件 • 安装 • 分割与补丁生成 • 特征提取 • 弱监督训练 • 测试 • 训练好的模型 • 热图可视化 • 示例 • 预印本 • 演示 • 引用

CLAM 是如何工作的？ 聚类约束注意力多实例学习（CLAM）是一种基于深度学习的弱监督方法，它利用注意力机制自动识别具有高诊断价值的子区域，从而准确地对整张切片进行分类；同时，它还对所识别的代表性区域进行实例级聚类，以约束和优化特征空间。

© Mahmood 实验室 - 本代码根据 GPLv3 许可证发布，仅供非商业性学术用途。

更新：

• 2025年4月15日：请查看我们的新仓库 Trident，该仓库支持 25 多种基础模型的全切片图像处理，包括 UNIv2、CONCH、TITAN 等！
• 2024年4月6日：现在可以选择 UNI 和 CONCH 作为预训练编码器。更多详情请参阅 将 CONCH / UNI 用作预训练编码器。请确保已正确安装所有依赖项，方法是安装最新的 env.yml 文件（详情请参阅 安装指南），并使用相应的 clam_latest conda 环境。
• 2024年3月19日：我们发布了 UNI 和 CONCH，这对 SOTA 预训练编码器能够为组织病理学图像生成强大的表示，并提升各种计算病理工作流的表现，包括基于 MIL 的 CLAM 工作流。
• 2021年5月24日：热图可视化脚本现已通过 create_heatmaps.py 提供，配置模板位于 heatmaps/configs 中。详情请参阅 热图可视化演示及说明。
• 2021年3月1日：新的快速补丁生成/特征提取流程现已上线。简而言之： 由于 CLAM 训练仅需图像特征，因此无需保存实际的图像补丁。新流程去除了这一开销，而是在“补丁生成”过程中仅保存图像补丁的坐标，并在特征提取时从 WSI 上按需加载这些区域。相比旧流程，这一新流程显著更快，通常只需 1–2 秒完成“补丁生成”，几分钟即可完成一张 WSI 的特征提取。要使用新流程，请确保调用 create_patches_fp.py 和 extract_features_fp.py，而非旧版的 create_patches.py 和 extract_features.py 脚本。

注意：虽然我们希望最新更新不会对用户的流程造成太大改变，但如有需要，您仍可参考旧版本的代码库 这里。如有任何问题，请在公开论坛中报告。

警告：最新更新默认会在使用预训练编码器提取特征之前，将图像补丁调整为 224 x 224 像素大小。此更改旨在使其与 UNI、CONCH 及其他研究中使用的评估协议保持一致。如果您希望保留补丁生成过程中产生的原始图像尺寸，或使用不同尺寸的图像进行特征提取，则可在 extract_features_fp.py 中指定 --target_patch_size 参数。

2021年3月1日更新：请注意，README 已更新为默认使用新的快速流程。如果您仍希望使用旧流程，请参阅：旧流程指南。该流程会保存组织补丁，速度明显较慢且占用大量存储空间，但如果需要处理原始图像补丁而非特征嵌入，则仍然有用。

安装：

有关如何开始使用的详细说明，请参阅我们的 安装指南。

WSI 分割与补丁生成

第一步重点在于分割组织并排除任何空洞。特定切片的分割可以通过调整各个参数来进行（例如，扩张的血管可能表现为空洞，这对于某些肉瘤来说很重要）。 以下示例假设以常见标准格式（.svs、.ndpi、.tiff 等）数字化的全切片图像数据已存储在名为 DATA_DIRECTORY 的文件夹中：

DATA_DIRECTORY/
	├── slide_1.svs
	├── slide_2.svs
	└── ...

基本的全自动运行

python create_patches_fp.py --source DATA_DIRECTORY --save_dir RESULTS_DIRECTORY --patch_size 256 --seg --patch --stitch 

上述命令将使用默认参数对 DATA_DIRECTORY 中的每张切片进行分割，提取分割后组织区域内的所有补丁，并为每张切片利用提取的补丁创建拼接重建图像（可选），同时在指定的 RESULTS_DIRECTORY 中生成以下文件夹结构：

RESULTS_DIRECTORY/
	├── masks
    		├── slide_1.png
    		├── slide_2.png
    		└── ...
	├── patches
    		├── slide_1.h5
    		├── slide_2.h5
    		└── ...
	├── stitches
    		├── slide_1.png
    		├── slide_2.png
    		└── ...
	└── process_list_autogen.csv

其中，masks 文件夹包含分割结果（每张切片一张图像）。
patches 文件夹包含从每张切片中提取的组织补丁数组（每张切片一个 .h5 文件，每个条目对应补丁左上角的坐标）。
stitches 文件夹包含拼接后的组织补丁的下采样可视化图像（每张切片一张图像）（可选，不用于下游任务）。
自动生成的 process_list_autogen.csv 文件则列出了所有已处理的切片及其使用的分割和补丁参数。

此外，还可以传递以下额外参数：

• --custom_downsample：自定义下采样因子（不推荐，建议先检查是否存在原生下采样）。
• --patch_level：从哪个金字塔层级提取补丁（默认为 0，即最高可用分辨率）。
• --no_auto_skip：默认情况下，脚本会跳过目标文件夹中已存在补丁 .h5 文件的文件；此选项可用于覆盖该行为。

此外，还提供了一些参数模板，可作为默认参数的良好选择：

• bwh_biopsy.csv：用于分割在 BWH 扫描的活检切片（使用 Hamamatsu S210 和 Aperio GT450 扫描）。
• bwh_resection.csv：用于分割在 BWH 扫描的切除标本切片。
• tcga.csv：用于分割 TCGA 数据集中的切片。

只需将模板文件名传递给 --preset 参数即可，例如使用活检模板：

python create_patches_fp.py --source DATA_DIRECTORY --save_dir RESULTS_DIRECTORY --patch_size 256 --preset bwh_biopsy.csv --seg --patch --stitch

自定义默认分割参数

对于高级用法，除了使用脚本 create_patches_fp.py 中定义的默认单一参数集外，用户还可以根据数据集定义自定义参数模板。这些模板应存储在 presets 目录下，包含分割和补丁过程中所用各参数的值。

分割参数列表如下：

• seg_level：在哪个下采样层级上进行全切片图像分割（默认为 -1，即使用最接近 64 倍下采样的层级）。
• sthresh：分割阈值（正整数，默认为 8；阈值越高，检测到的前景越少，背景越多）。
• mthresh：中值滤波器大小（正奇数，默认为 7）。
• use_otsu：是否使用 Otsu 方法代替简单二值化阈值法（默认为 False）。
• close：在初始阈值处理后应用的额外形态学闭运算（正整数或 -1，默认为 4）。

轮廓过滤参数列表如下：

• a_t：组织区域面积过滤阈值（正整数，表示检测到的前景轮廓最小尺寸，相对于 0 级别下 512×512 大小的参考补丁而言；例如，值为 10 表示只有大于 10 个 512×512 大小补丁的前景轮廓才会被处理，默认为 100）。
• a_h：空洞面积过滤阈值（正整数，表示要避免的前景轮廓中最小空洞/腔体尺寸，同样相对于 0 级别下 512×512 大小的补丁而言；默认为 16）。
• max_n_holes：每个检测到的前景轮廓最多允许的空洞数量（正整数，默认为 10；最大值越高，补丁提取越准确，但计算成本也会增加）。

分割可视化参数列表如下：

• vis_level：用于可视化分割结果的下采样层级（默认为 -1，即使用最接近 64 倍下采样的层级）。
• line_thickness：绘制分割结果时的线条粗细（正整数，以 0 级别下线条占用的像素数表示，默认为 250）。

补丁提取参数列表如下：

• use_padding：是否对切片边缘进行填充（默认为 True）。
• contour_fn：用于判断补丁属于前景还是背景的轮廓检查函数（可选“four_pt”——检查补丁中心周围小网格中的四个点是否全部位于轮廓内；“center”——检查补丁中心是否位于轮廓内；“basic”——检查补丁左上角是否位于轮廓内；默认为“four_pt”）。

两步运行（手动调整特定切片的参数）

为确保高质量的分割和相关组织patch的提取，用户可以选择先进行分割（通常每个切片约1秒），检查分割结果，并在必要时针对选定的切片微调参数，然后再使用调整后的参数提取patch。即第一步运行：

python create_patches_fp.py --source DATA_DIRECTORY --save_dir RESULTS_DIRECTORY --patch_size 256 --seg  

上述命令将使用默认参数对DATA_DIRECTORY中的每个切片进行分割，并生成csv文件，但此时不会立即提取patch（patches和stitches文件夹将为空）。

可以针对特定切片对csv文件进行调整，并通过--process_list CSV_FILE_NAME参数将其传递给脚本，以便脚本使用用户更新后的设置。在调整分割参数之前，用户应先复制一份csv文件并重命名（例如：process_list_edited.csv），否则下次运行该命令时会覆盖原文件。随后，用户可以通过修改csv文件中相应切片的字段来微调参数。其中，process列存储一个二进制变量（0或1），用于指示是否对该切片进行处理。这使得用户只需开启少数几个切片，即可快速确认调整后的参数是否达到满意效果。例如，若要使用用户更新后的参数重新分割slide_1.svs，只需对其相关字段做出相应更改，将process单元格更新为1，保存csv文件，并将其名称传递给上述相同命令：

python create_patches_fp.py --source DATA_DIRECTORY --save_dir RESULTS_DIRECTORY --patch_size 256 --seg --process_list process_list_edited.csv

当对分割结果满意时，用户应将所有需要处理的切片的process单元格设置为1，保存csv文件，然后使用保存的csv文件执行patch提取操作（与完全自动化运行用例相同，只是增加了csv文件参数）：

python create_patches_fp.py --source DATA_DIRECTORY --save_dir RESULTS_DIRECTORY --patch_size 256 --seg --process_list CSV_FILE_NAME --patch --stitch

使用CLAM进行基于切片级标签的弱监督学习

特征提取（GPU示例）

CUDA_VISIBLE_DEVICES=0 python extract_features_fp.py --data_h5_dir DIR_TO_COORDS --data_slide_dir DATA_DIRECTORY --csv_path CSV_FILE_NAME --feat_dir FEATURES_DIRECTORY --batch_size 512 --slide_ext .svs

上述命令要求将坐标.h5文件存储在DIR_TO_COORDS目录下，并以512的批量大小从每个切片的每个组织patch中提取1024维特征，最终生成如下文件结构：

FEATURES_DIRECTORY/
    ├── h5_files
            ├── slide_1.h5
            ├── slide_2.h5
            └── ...
    └── pt_files
            ├── slide_1.pt
            ├── slide_2.pt
            └── ...

其中，每个.h5文件包含提取的特征数组及其对应的patch坐标（注意，为了加快训练速度，还会为每个切片创建一个仅包含patch特征的.pt文件）。csv文件应包含待处理切片的文件名列表（不带文件扩展名）。最简单的方法是直接使用前一步分割/patch提取自动生成的csv文件，并删除文件扩展名。

使用CONCH / UNI作为预训练编码器

如果使用UNI或CONCH，首先请参考它们各自的HF页面，申请并下载模型权重（pytorch_model.bin）。

UNI：https://huggingface.co/MahmoodLab/UNI

CONCH：https://huggingface.co/MahmoodLab/CONCH

成功下载模型检查点后，在运行特征提取脚本之前，需将CONCH_CKPT_PATH和UNI_CKPT_PATH环境变量设置为预训练编码器检查点的路径。例如，若已将UNI和CONCH的预训练检查点分别放置在checkpoints/conch和checkpoints/uni文件夹中，则可按如下方式设置环境变量：

export CONCH_CKPT_PATH=checkpoints/conch/pytorch_model.bin
export UNI_CKPT_PATH=checkpoints/uni/pytorch_model.bin

在运行extract_features_fp.py时，还需将--model_name设置为‘uni_v1’或‘conch_v1’，以使用相应的编码器。

需要注意的是，这些编码器模型（尤其是采用ViT-L的UNI）比默认的ResNet50编码器计算成本更高、所需显存也更多，因此如果显存不足，预计运行时间会更长且批大小会相应减小。UNI将输出1024维特征，而CONCH则输出512维特征。

数据集

用于训练和测试的数据应按以下方式组织：

DATA_ROOT_DIR/
    ├──DATASET_1_DATA_DIR/
        ├── h5_files
                ├── slide_1.h5
                ├── slide_2.h5
                └── ...
        └── pt_files
                ├── slide_1.pt
                ├── slide_2.pt
                └── ...
    ├──DATASET_2_DATA_DIR/
        ├── h5_files
                ├── slide_a.h5
                ├── slide_b.h5
                └── ...
        └── pt_files
                ├── slide_a.pt
                ├── slide_b.pt
                └── ...
    └──DATASET_3_DATA_DIR/
        ├── h5_files
                ├── slide_i.h5
                ├── slide_ii.h5
                └── ...
        └── pt_files
                ├── slide_i.pt
                ├── slide_ii.pt
                └── ...
    └── ...

即，每个数据集应作为 DATA_ROOT_DIR 下的一个子文件夹（例如 DATASET_1_DATA_DIR），而该数据集中每张切片提取的特征则以 .pt 文件的形式存储在该子文件夹的 pt_files 文件夹下。 此外，数据集还应以 CSV 格式准备，至少包含 3 列：case_id、slide_id，以及 1 列或多列用于表示切片级别标签的列。每个 case_id 是患者的唯一标识符，而 slide_id 是与提取的特征 .pt 文件名相对应的切片唯一标识符。这一点非常重要，因为通常一位患者会有多个切片，且这些切片可能具有不同的标签。在创建训练/验证/测试划分时，我们还会确保来自同一患者的切片不会被分配到不同的划分中。切片 ID 应与特征提取步骤中使用的 ID 保持一致。我们在 dataset_csv 文件夹中提供了两个此类数据集 CSV 文件的示例：一个用于二分类肿瘤与正常组织（任务 1），另一个用于多分类肿瘤亚型分类（任务 2）。

用于实际训练/验证/测试的数据集对象可以使用 Generic_MIL_Dataset 类（定义在 datasets/dataset_generic.py 中）来构建。此类数据集对象传递给模型的示例可在 main.py 和 eval.py 中找到。

对于训练，请查看 main.py：

if args.task == 'task_1_tumor_vs_normal':
    args.n_classes=2
    dataset = Generic_MIL_Dataset(csv_path = 'dataset_csv/tumor_vs_normal_dummy_clean.csv',
                            data_dir= os.path.join(args.data_root_dir, 'tumor_vs_normal_feat_resnet'),
                            shuffle = False, 
                            seed = args.seed, 
                            print_info = True,
                            label_dict = {'normal_tissue':0, 'tumor_tissue':1},
                            label_col = 'label',
                            ignore=[])

用户需要传入：

• csv_path：数据集 CSV 文件的路径
• data_dir：保存的 .pt 特征文件的路径
• label_dict：将标签列中的标签映射为数值的字典
• label_col：标签列的名称（可选，默认为 'label'）
• ignore：要忽略的标签（可选，默认为空列表）

最后，用户应在 --task 参数中添加由该数据集对象指定的具体“任务”，如下所示：

parser.add_argument('--task', type=str, choices=['task_1_tumor_vs_normal',  'task_2_tumor_subtyping'])

训练划分

为了评估算法性能，可以使用多折（例如 10 折）的训练/验证/测试划分。两个示例数据集的 10 折 80/10/10 划分可在 splits 文件夹中找到。这些划分可以使用 create_splits_seq.py 脚本自动生成，只需进行少量修改，就像处理 main.py 一样。例如，肿瘤与正常组织的划分可以通过以下命令创建：

python create_splits_seq.py --task task_1_tumor_vs_normal --seed 1 --k 10

该脚本使用 Generic_WSI_Classification_Dataset 类，其构造函数所需的参数与 Generic_MIL_Dataset 相同（但不包括 data_dir 参数）。有关详细信息，请参阅 datasets/dataset_generic.py 中的数据集定义。

GPU 训练示例：二分类阳性 vs. 阴性（例如淋巴结状态）

注意：对于 CONCH，--embed_dim 应设置为 512；对于 UNI 和 resnet50_trunc，则应设置为 1024。

CUDA_VISIBLE_DEVICES=0 python main.py --drop_out 0.25 --early_stopping --lr 2e-4 --k 10 --exp_code task_1_tumor_vs_normal_CLAM_50 --weighted_sample --bag_loss ce --inst_loss svm --task task_1_tumor_vs_normal --model_type clam_sb --log_data --data_root_dir DATA_ROOT_DIR --embed_dim 1024

GPU 训练示例：亚型分类问题（例如 3 类肾细胞癌亚型分类）

CUDA_VISIBLE_DEVICES=0 python main.py --drop_out 0.25 --early_stopping --lr 2e-4 --k 10 --exp_code task_2_tumor_subtyping_CLAM_50 --weighted_sample --bag_loss ce --inst_loss svm --task task_2_tumor_subtyping --model_type clam_sb --log_data --subtyping --data_root_dir DATA_ROOT_DIR --embed_dim 1024

注意：我们已提供使用单注意力分支 CLAM 模型的选项，在大多数实验中表现良好，可通过 --model_type clam_sb（单分支）或 clam_mb（多分支）进行设置。默认选择是 clam_sb。此外，用户还可以通过 --B 调整用于聚类的补丁数量。

默认情况下，结果将保存到与用户输入的 exp_code 参数对应的 results/exp_code 文件夹中。如果启用了 TensorBoard 日志记录（通过 --log_data 参数开启），用户可以进入特定实验的结果文件夹，运行：

tensorboard --logdir=.

这将打开浏览器窗口，并实时显示记录的训练/验证统计数据。有关每个参数的信息，请参阅：

python main.py -h

测试与评估脚本

用户也可以使用评估脚本来测试已训练模型的性能。以下是对应于上述训练模型的示例：

CUDA_VISIBLE_DEVICES=0 python eval.py --k 10 --models_exp_code task_1_tumor_vs_normal_CLAM_50_s1 --save_exp_code task_1_tumor_vs_normal_CLAM_50_s1_cv --task task_1_tumor_vs_normal --model_type clam_sb --results_dir results --data_root_dir DATA_ROOT_DIR --embed_dim 1024

CUDA_VISIBLE_DEVICES=0 python eval.py --k 10 --models_exp_code task_2_tumor_subtyping_CLAM_50_s1 --save_exp_code task_2_tumor_subtyping_CLAM_50_s1_cv --task task_2_tumor_subtyping --model_type clam_sb --results_dir results --data_root_dir DATA_ROOT_DIR --embed_dim 1024

再次强调，有关每个命令行参数的信息，请参阅：

python eval.py -h

通过以与处理 main.py 相同的方式将您自己的自定义数据集添加到 eval.py 中，您也可以轻松地在独立测试集上测试已训练的模型。

热图可视化

热图可视化可以通过 create_heatmaps.py 脚本批量计算。只需填写配置文件并将其存储在 /heatmaps/configs 目录下，然后使用 --config NAME_OF_CONFIG_FILE 标志运行 create_heatmaps.py 即可。我们提供了一个演示模板（config_template.yaml），用于对来自 CPTAC 的两张全切片图像进行肺部亚型分类。

要运行演示（原始结果保存在 heatmaps/heatmap_raw_results，最终结果保存在 heatmaps/heatmap_production_results）：

CUDA_VISIBLE_DEVICES=0 python create_heatmaps.py --config config_template.yaml

有关每个可配置选项的说明，请参阅 /heatmaps/configs/config_template.yaml 文件。

与特征提取类似，如果使用 UNI 或 CONCH 作为预训练编码器，在运行脚本之前需要设置相应的环境变量。更多详细信息请参阅 将 CONCH / UNI 用作预训练编码器 部分。

训练好的模型检查点

为确保实验的可重复性，所有使用的训练模型均可在此处获取：Google Drive。

三个主要文件夹（tcga_kidney_cv、tcga_cptac_lung_cv 和 camelyon_40x_cv）分别对应于以下任务的模型：基于 TCGA 数据训练的肾癌亚型分类模型、基于 TCGA 和 CPTAC 数据训练的非小细胞肺癌亚型分类模型，以及基于 Camelyon16+17 数据训练的乳腺淋巴结转移检测模型。在每个主文件夹中，每个子文件夹对应一组 10 折交叉验证实验。例如，子文件夹 tcga_kidney_cv_CLAM_50_s1 包含针对 TCGA 肾癌亚型分类的 10 个交叉验证折次的检查点，这些模型使用 CLAM 方法，并采用多注意力分支架构，仅利用完整训练集中 50% 的病例进行训练。

为了实现可重复性，可以按照上述章节中描述的相同流程准备数据，然后通过调用 eval.py 脚本评估这些模型。评估时需指定适当的参数，包括模型类型（应设置为 --model_type clam_mb 或 --model_type mil；对于仅评估而言，--subtyping 标志并无影响），以及模型检查点和数据的存储路径（--results_dir、--models_exp_code、--data_root_dir 和 --task）。

示例

有关三种不同问题的详细结果以及跨数据源、成像设备和组织内容的适应性，请参阅我们的预印本和交互式演示。

更多示例请访问：http://clam.mahmoodlab.org

问题

• 请在公共论坛上报告所有问题。

许可证

© Mahmood 实验室 - 本代码根据 GPLv3 许可证发布，仅供非商业性的学术用途。

资助

本研究由美国国立卫生研究院 NIGMS R35GM138216 资助。

参考文献

如果您在研究中使用了我们的工作成果，或引用了本代码的部分内容，请考虑引用我们的论文：

Lu, M.Y., Williamson, D.F.K., Chen, T.Y. 等. 基于全切片图像的数据高效且弱监督的计算病理学. Nature Biomedical Engineering 5, 555–570 (2021). https://doi.org/10.1038/s41551-020-00682-w

@article{lu2021data,
  title={Data-efficient and weakly supervised computational pathology on whole-slide images},
  author={Lu, Ming Y and Williamson, Drew FK and Chen, Tiffany Y and Chen, Richard J and Barbieri, Matteo and Mahmood, Faisal},
  journal={Nature Biomedical Engineering},
  volume={5},
  number={6},
  pages={555--570},
  year={2021},
  publisher={Nature Publishing Group}
}

CLAM 快速上手指南

CLAM (Clustering-constrained Attention Multiple Instance Learning) 是一个基于深度学习的弱监督学习框架，专为全切片病理图像（WSI）分类设计。它无需手动标注感兴趣区域（ROI）或补丁级标签，仅利用幻灯片级别的标签即可高效训练模型，并自动识别高诊断价值的子区域。

1. 环境准备

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

• 操作系统: Linux (推荐 Ubuntu 18.04/20.04) 或 macOS。Windows 用户建议使用 WSL2。
• Python: 3.8 或更高版本。
• GPU: 推荐使用 NVIDIA GPU 以加速特征提取和模型训练（需安装对应的 CUDA 驱动）。
• 存储: 确保有足够的磁盘空间存放原始 WSI 数据及生成的中间文件（掩码、坐标文件等）。
• 依赖库: 需要安装 openslide-python 及其底层库 libopenslide 以读取常见的病理图像格式（.svs, .ndpi, .tiff 等）。

提示: 对于国内开发者，建议在配置 Python 环境时使用清华源或阿里源加速包下载。

2. 安装步骤

CLAM 推荐使用 Conda 进行环境管理。请按照以下步骤操作：

第一步：克隆仓库

git clone https://github.com/mahmoodlab/CLAM.git
cd CLAM

第二步：创建并激活 Conda 环境

使用项目提供的最新配置文件 env.yml 创建环境。该文件已包含所有必要的依赖（包括 PyTorch, OpenSlide, Scikit-learn 等）。

conda env create -f env.yml
conda activate clam_latest

注意: 如果下载 env.yml 中的包速度较慢，可以在创建环境后，手动使用 pip 国内源更新关键包，或者在运行 conda create 时添加 -c https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/ 等镜像源参数（具体取决于 conda 配置）。

第三步：验证安装

确保 openslide 能够正常加载。您可以尝试运行一个简单的帮助命令来检查脚本是否可执行：

python create_patches_fp.py --help

3. 基本使用

CLAM 的核心工作流程分为三个阶段：分割与分块 (Segmentation & Patching) -> 特征提取 (Feature Extraction) -> 弱监督训练 (Training)。

假设您的原始 WSI 数据存放在 DATA_DIRECTORY 文件夹中，结果将保存到 RESULTS_DIRECTORY。

步骤一：组织数据

将您的全切片图像（.svs, .tiff 等）放入一个文件夹：

DATA_DIRECTORY/
    ├── slide_1.svs
    ├── slide_2.svs
    └── ...

步骤二：组织分割与分块 (Segmentation and Patching)

此步骤会自动分割组织区域，排除背景，并提取组织内的补丁坐标。这是最快且最常用的自动化流程。

python create_patches_fp.py --source DATA_DIRECTORY --save_dir RESULTS_DIRECTORY --patch_size 256 --seg --patch --stitch

参数说明：

• --source: 输入 WSI 文件夹路径。
• --save_dir: 输出结果文件夹路径。
• --patch_size: 补丁大小（像素），默认为 256。
• --seg: 执行组织分割。
• --patch: 执行分块（仅保存坐标，不保存图像本身，节省空间）。
• --stitch: 生成拼接后的可视化预览图（可选）。

输出结构： 执行完成后，RESULTS_DIRECTORY 将包含：

• masks/: 分割掩码图像。
• patches/: 包含每个幻灯片补丁坐标的 .h5 文件。
• process_list_autogen.csv: 处理列表，后续步骤需用到此文件。

进阶提示: 如果针对特定数据集（如 TCGA 或 BWH 活检），可使用预设参数模板加速调整： --preset tcga.csv 或 --preset bwh_biopsy.csv

步骤三：特征提取 (Feature Extraction)

利用预训练编码器（如 ResNet, UNI, CONCH 等）将上一步生成的补丁坐标转换为特征向量。

python extract_features_fp.py --data_h5_dir RESULTS_DIRECTORY/patches --save_dir RESULTS_DIRECTORY/features --csv_path RESULTS_DIRECTORY/process_list_autogen.csv --batch_size 256

关键点：

• 该脚本会按需从原始 WSI 中加载区域并提取特征，无需预先保存大量图像补丁。
• 若要使用最新的 SOTA 编码器（如 UNI 或 CONCH），请确保在命令中指定相应的模型参数（参考官方文档中 "Using CONCH / UNI as Pretrained Encoders" 部分）。

步骤四：弱监督训练 (Training)

准备好特征文件和对应的幻灯片级别标签（需整理为 CSV 格式，包含 slide_id 和 label），即可开始训练。

python main.py --drop_out --early_stopping --lr 2e-4 --k 10 --subtyping --bag_loss ce --model clam_sb --weighted_sample --inst_loss svm --max_epochs 30 --results_dir results_directory_name --data_root_dir RESULTS_DIRECTORY/features --csv_path your_labels.csv

常用参数简述：

• --subtyping: 开启多分类亚型分析。
• --model clam_sb: 使用单分支 CLAM 模型（也可选 clam_mb 多分支）。
• --csv_path: 指向包含标签的 CSV 文件。
• --data_root_dir: 指向步骤三生成的特征目录。

训练完成后，模型权重将保存在 results_directory_name 中，您可以使用提供的脚本生成注意力热力图（Heatmap）以解释模型决策。