信息速览

数据集名称NuCLS — 乳腺癌病理核分类数据集 AI-Ready Wikipedia | 千方病案医数集

数据类型222,396 条核标注,125 张 TCGA H&E WSI,13/7/4 三级核分类,CC0 1.0 开放获取,官方五折划分

规模125 名患者（每人 1 张 TCGA H&E 全切片）

接入方式Northwestern University Department of Pathology（NuCLS 研究团队） url: https://sites.google.com/view/nucls/home

AI 就绪度

数据集封面

NuCLS — 乳腺癌病理核分类数据集 AI-Ready Wikipedia

INFOBOX


数据集名称	NuCLS 乳腺癌病理核分类数据集
英文全称	NuCLS: A Scalable Crowdsourcing Approach and Dataset for Nucleus Classification and Segmentation in Breast Cancer
别名/简称	NuCLS Dataset、NuCLS（Amgad et al., GigaScience 2022）
疾病分类（ICD-11）	2C61 乳腺浸润癌 / 2E65 乳腺原位癌 / 2C6Z 乳腺恶性肿瘤未特指（TCGA 乳腺癌队列，详见 §2.1）
SNOMED CT	254837009 乳腺恶性肿瘤 / 82711006 浸润性导管癌 / 399753008 病理学所见（详见 §2.1b）
数据模态	乳腺 H&E 全切片图像（TCGA）逐核标注：边界框 + 多边形边界 + 实例掩码
AI 任务类型	核检测、核分类（raw 13 类/main 7 类/super 4 类）、核实例分割、sTIL 量化、评分者间一致性研究
样本总数	222,396 条核标注；修正单评分者子集 1,744 个 FOV / 59,485 个核
数据大小	官方修正单评分者 QC 包镜像约 3.1 GB（截至 2026-09）
数据格式	CSV（坐标 + 三级标签）+ PNG（RGB/实例掩码/可视化叠加）
许可证	CC0 1.0（数据集）；MIT（官方代码）
访问级别	开放（官方页直接下载，无需注册）
DUO 标签	NRES（无限制使用，CC0 公共领域贡献）
语言	英文（标签体系与文档）
首发日期	2021-02-18（arXiv:2102.09099 预印本）
最后更新	2022-05-17（GigaScience 11: giac037 正式版）
发布机构	西北大学（Northwestern University）病理系牵头，联合 Emory 大学、Kitware、开罗大学等 28 家机构
官方主页	sites.google.com/view/nucls
下载地址	nucls.grand-challenge.org（官方入口，含 Google Drive/Dropbox 分发）
DOI	10.1093/gigascience/giac037
引用次数	117+（Semantic Scholar，截至 2026-09）
AI 就绪度评分	⭐⭐⭐⭐（4/5）— 官方五折划分、三级标签与实例掩码齐全，但无官方 PyTorch 加载器，需自行处理 rectangle/polyline 混合与坐标尺度换算
页面状态	published

§0 E-E-A-T 审核与免责

医学审核者：[千方病案医学编辑部] 交叉审核：§2 医学背景（乳腺癌 ICD-11/SNOMED CT 映射、sTIL 临床意义、金标准描述）、§7 偏倚分析。

数据工程审核者：[千方病案医学编辑部交叉审核] 医疗 AI 数据工程师，审核范围：§4 DAIMS 数据字典、§5 数据划分策略、§6 预处理 Pipeline 和坑点。

审核日期：2026-09-05

医疗免责声明：本页面提供的医学信息仅供研究和教育目的，不构成医疗建议、诊断或治疗方案。数据集的医学描述基于公开发表的文献，未经逐一临床验证。任何基于该数据集训练的 AI 模型在应用于临床决策前，必须经过独立的临床验证和监管审批。

技术免责声明：本页面的代码示例、预处理建议和基准性能数据基于公开资料整理，不保证在特定环境下的准确性和适用性。使用者应自行验证代码安全性和数据预处理流程的正确性。千方病案医数集不对因使用本页面信息而导致的任何直接或间接损失承担责任。

数据使用合规：使用本页面描述的数据集前，请务必阅读并遵守数据集原始许可协议。NuCLS 以 CC0 1.0 公共领域贡献发布，但仍建议遵循学术引用规范并遵守 TCGA 原始数据的脱敏与使用条款。DUO 标签仅供参考，具体使用限制以数据集官方协议为准。

§1 数据集概览

§1.0 📌 30 秒速览

这是什么？ NuCLS（发音同 “new-C-L-S”，Nucleus Classification, Localization and Segmentation 的缩写）是一个乳腺癌病理图像的"细胞核级"标注数据集：研究团队从癌症基因组图谱（TCGA）中取出 125 名患者的 H&E 染色全切片，在其中约 1 mm² 的小视野（FOV）里，一个一个地圈出了 222,396 个细胞核，每个核都带有"是什么细胞"的标签，其中很多还带有精确的多边形轮廓 Amgad et al., GigaScience 2022。

为什么重要？ 给病理图像里的每一个细胞核贴标签，恰恰是最费病理医师时间的活儿。NuCLS 用"医学生众包 + 算法建议辅助 + 病理学家把关修正"的流水线，把这件事做到了 22 万条规模——是乳腺癌领域最大的逐核标注资源之一，并且系统回答了"非专家标注到底靠不靠谱"这个众包方法学核心问题（32 名非病理学家 + 7 名病理学家、跨 5 国的评分者实验）。

我能用它做什么？ 训练核检测/分类/分割模型（13 类细粒度、4 类超粒度任选）；做肿瘤浸润淋巴细胞（sTIL）自动定量——这是乳腺癌预后与免疫治疗反应的热门标志物；研究标注方法学本身：算法建议会不会"带偏"标注者、多少个评分者才能凑出可靠共识，NuCLS 的多评分者子集就是为此设计的。

§1.1 摘要

NuCLS 由西北大学病理系 Lee A.D. Cooper 团队牵头，联合 Emory 大学、Kitware 与多所埃及医学院等 28 家机构完成，2021 年以 arXiv 预印本首发、2022 年正式发表于 GigaScience（giac037）。数据层面，团队从 TCGA 18 家机构的乳腺癌病例中选取 125 张全切片（每位患者 1 张），在约 1 mm² 的 ROI 内通过 Digital Slide Archive/HistomicsUI 平台组织标注：32 名非病理学家（医学生为主）与 7 名病理学家（3 资深 + 4 初级）来自 5 个国家，产出单评分者 128,000 条（3,944 个 FOV）与多评分者 97,300 条（Evaluation/Bootstrap/Unbiased 三套）共 222,396 条核标注 Amgad et al., PMC。

方法层面的三个设计至今仍被引用：其一，弱算法（图像处理自举 + Mask R-CNN 精炼）先生成边界与类别建议，标注者单击确认即可获得高质量多边形分割，Evaluation 数据集中 41.7±17.3% 的分割由此单击产生、其分割精度达 Dice 85.0±5.9；其二，用约束聚类 + 期望最大化（Dawid-Skene）从多评分者标注中推断共识真值，并区分非病理学家共识（NP-labels）与病理学家真值（P-truth）；其三，配套 DTALE（Decision Tree Approximation of Learned Embeddings）方法把神经网络嵌入近似为决策树以解释核分类。官方随包提供按来源医院分组的五折训练/测试划分文件，数据以 CC0 1.0 公共领域贡献开放。

§1.2 战略价值

维度一：规模 × 标注形态的稀缺组合。 在 NuCLS 之前，乳腺癌逐核标注资源要么规模小（MoNuSeg 30 个 patch、约 2.2 万个核），要么只有像素级掩码而无多级类别。NuCLS 用 222,396 条标注同时覆盖"检测框、多边形边界、实例掩码、三级类别"四种形态，且修正单评分者子集（59,485 个核、1,744 个 FOV）规模即接近同类数据集总和，使数据饥饿型检测模型（Faster/Mask R-CNN、DETR 系）与分割模型（HoVer-Net、StarDist）都能吃饱。对乳腺癌这一单一癌种而言，它把"逐核"任务从 patch 级演示推进到了全队列规模。

维度二：sTIL 定量的临床接口。 肿瘤浸润淋巴细胞（尤其间质 TIL，sTIL）是三阴性及 HER2 阳性乳腺癌的预后与预测标志物，国际 TIL 工作组已发布标准化评估指南。NuCLS 的 super_classification 直接内置 sTIL / nonTIL_stromal / tumor_any / AMBIGUOUS 四值超类，等于把"哪些淋巴细胞算进 TIL 评分"这一临床规则编码进了标签体系。后续工作 MuTILs（npj Breast Cancer 2024）正是以 NuCLS + BCSS 为训练底座，把全切片级 TIL 评分与病理医师视觉评分做到 Spearman 相关 0.55-0.61（Nature 系论文），验证了这条数据到临床的路。

维度三：标注方法学的"活标本"。 NuCLS 不只是数据，还是一套可复用的众包流程证据：算法建议如何把非专家的标注质量拉起来（即使建议本身很噪）、评分者间一致性（Krippendorff alpha）如何系统度量、多少个评分者足够推断共识——官方仓库公开了全部分析脚本。任何计划自建病理标注管线的团队，都可以把它当作"参考实现"来抄作业。

维度四：区域级 + 核级同源对齐的稀缺生态位。 绝大多数公开病理数据集只在单一粒度上标注：要么区域（BCSS、GlaS），要么细胞（MoNuSeg、Lizard）。NuCLS 与 BCSS 共享同批 125 张 TCGA 切片，一个给"区域语义"（肿瘤/间质/淋巴浸润），一个给"逐核身份 + 位置"，且区域掩码可以直接作为核分类的结构先验（官方建议生成管线正是这么做的）。对多任务学习、跨粒度蒸馏、可解释性研究而言，这种同源双层标注在公开资源里屈指可数，也是它区别于"更大但更扁平"数据集的根本价值。

§1.3 同类数据集横向对比

数据集	规模	模态/分辨率	标注形态	类别体系	与 NuCLS 的差异
NuCLS	222,396 个核；125 张 TCGA WSI	乳腺 H&E WSI，修正子集 0.2 µm/px	矩形框 + 多边形 + 实例掩码	raw 13 类 / main 7 类 / super 4 类（含 sTIL）	规模最大；含单/多评分者两套体系与 sTIL 超类
MoNuSeg	30 个 patch（1,000×1,000，40×），约 2.2 万个核	7 器官 TCGA	像素级实例掩码	单一"核"类（MoNuSAC 扩展 4 类）	跨器官泛化基准，规模小约一个数量级
PanNuke	7,904 个 patch（256×256），约 20 万个核	19 种组织	半自动实例掩码	5 类（肿瘤/炎症/结缔/坏死/上皮）	覆盖多癌种，但为半自动标注、无评分者分析
Lizard	约 50 万个核；291 个 patch	结肠 H&E，20×	多边形 + 6 类核型标签	6 类细胞	结肠专用、类别更细；无多评分者体系
BCSS（前作）	与 NuCLS 同批切片的区域级标注	乳腺 H&E WSI，0.25 MPP 掩码	区域语义掩码	肿瘤/间质/淋巴浸润等区域类	NuCLS 的姊妹集：区域级 vs 核级，可联合训练
BACH	500 张显微图 + 40 张 WSI	乳腺 H&E，0.42-0.467 µm/px	图像级 + 像素级	4 类（正常/良性/原位/浸润）	病变级分类基准，不做逐核标注

§1.4 版本时间轴

时间	版本/事件	说明
2019-07	BCSS 框架论文发表	Amgad et al., Bioinformatics（doi:10.1093/bioinformatics/btz083），结构化众包框架与区域级标注，NuCLS 的方法学前身
2021-02-18	NuCLS 预印本首发	arXiv:2102.09099，数据随官方站点开放下载
2021-09-29	DTALE 论文	Explainable nucleus classification using DTALE，Bioinformatics，配套 NuCLS 模型代码
2022-05-17	GigaScience 正式版	DOI 10.1093/gigascience/giac037，随论文补充材料定稿官方数据包与五折划分
2024-01	MuTILs 模型论文	基于 NuCLS + BCSS 的全切片 TIL 评分模型（npj Breast Cancer），展示数据集的临床下游价值

时间轴解读：从 BCSS（2019）到 NuCLS（2021/2022）再到 MuTILs（2024），官方团队沿"区域标注 → 核标注 → 临床评分"的路径递进，三层资产全部开放且同源——这也是 NuCLS 生态相对同类数据集的独特延续性：你的工作可以自然嫁接到一条有据可查的方法学谱系上，而非孤立数据点。

§1.5 典型应用场景

核检测与分类模型训练：用 raw 13 类或 main 7 类标签训练 Faster/Mask R-CNN、HoVer-Net 等，输出肿瘤核、淋巴细胞、浆细胞等逐核预测，为下游组织学量化提供"细胞清单"。
sTIL 自动评分：基于 super_classification 训练淋巴细胞检测器，按国际 TIL 工作组规则聚合为间质 TIL 评分，服务于三阴性/HER2 阳性乳腺癌的预后研究。
核实例分割：以 19,680 条 polyline 边界与实例掩码训练分割头，评估时需注意框/多边形混合形态（见坑点 1）。
评分者一致性与真值推断方法研究：多评分者三套数据（Evaluation/Bootstrap/Unbiased）专门用于研究算法建议偏倚、评分者数量与共识质量的关系。
教学与弱监督研究：修正/未修正标注的对照可用于噪声标签学习（learning with noisy labels）教学实验。

选型速记：追求规模与标签层级 → 修正单评分者子集；研究标注方法学 → 多评分者三套数据；需要区域上下文 → 叠加 BCSS；要开箱即用 → HF 再托管。四条路径共享同一套 TCGA 切片，成果可互相叠加而非互斥。

§2 医学背景

§2.1 ICD-11 编码表

NuCLS 源自 TCGA 乳腺癌队列（浸润性癌为主），核级标签对应的组织学概念映射到 ICD-11（MMS）如下：

标签/组织场景	ICD-11 编码	ICD-11 中文名
浸润性乳腺癌（TCGA BRCA 主体病例）	2C61	乳腺浸润癌
原位癌成分（部分切片可见）	2E65	乳腺原位癌
恶性肿瘤未特指（队列层面兜底）	2C6Z	乳腺恶性肿瘤未特指
肿瘤坏死相关凋亡体（apoptotic_body 标签）	随 2C61 肿瘤章节管理	细胞凋亡（形态学所见，无独立编码）
sTIL 淋巴细胞浸润（super 类）	随 2C61 肿瘤章节管理	肿瘤间质免疫浸润（预后标志物，非独立疾病）

§2.1b SNOMED CT 映射表

标签/概念	ICD-11	SNOMED CT 码	SNOMED 术语
乳腺癌（数据场景）	2C61	254837009	Malignant tumour of breast（乳腺恶性肿瘤）
浸润性导管癌（TCGA BRCA 最常见类型）	2C61	82711006	Infiltrating duct carcinoma（浸润性导管癌）
肿瘤核（tumor 类）	2C61	119303007	Malignant tumor（恶性肿瘤）
淋巴细胞/免疫浸润（lymphocyte、sTIL）	—	235824008	Inflammatory disorder（炎症性病变，免疫浸润概念域）
成纤维细胞/肌上皮（fibroblast、myoepithelium）	—	272681000	Connective tissue cell（结缔组织细胞）
病理组织学所见（数据总体场景）	—	399753008	Histopathology finding（病理组织学所见）

§2.2 疾病简介与流行病学

乳腺癌是全球女性最常见的恶性肿瘤：据 IARC GLOBOCAN 2022 估计，女性乳腺癌年新发约 230 万例、死亡约 67 万例，发病率居女性癌症首位。病理诊断的基石是 H&E 染色切片的形态学评估，而"细胞"正是形态学的最小单位：肿瘤细胞的核异型性、核分裂象计数（分级依据）、间质与肿瘤内淋巴细胞的浸润密度（TIL 评分）都依赖病理医师在显微镜下逐个识别细胞核。

在这个任务谱系里，NuCLS 覆盖了最有临床味的一环——肿瘤微环境的细胞组成。肿瘤浸润淋巴细胞（TIL）的定量评估已被国际 TIL 工作组（International Immuno-Oncology Biomarker Working Group）写入标准化指南：在三阴性乳腺癌中，高间质 TIL（sTIL）与更好的预后和更高化疗/免疫治疗应答率相关；评估规则要求"只数间质内的单个核免疫细胞，排除肿瘤实质内的"，这条规则正是 NuCLS 把 sTIL 与 nonTIL_stromal、tumor_any 分开作为超类的原因。对 AI 而言，学会"这个淋巴细胞在间质里还是肿瘤里"，比学会"这是不是淋巴细胞"更接近临床可用。

值得强调的背景是：乳腺癌的组织学分级（Nottingham 分级）由腺管形成、核异型性、核分裂象三个成分构成，其中核分裂象计数是唯一需要"逐个数细胞"的成分，自动化收益最大；而 TIL 评分本质上是"间质内免疫核占间质面积的百分比"，同样以核为计数单元。也就是说，乳腺癌诊断工作流里最费人力的两件事——数核分裂、算 TIL——恰好都落在 NuCLS 的标签体系覆盖范围内，这解释了为什么该数据集把 mitotic_figure 与 sTIL 作为一等公民对待，而不是顺带的附加标签。

§2.3 临床任务定义

NuCLS 支撑的临床任务是诊断与分级辅助中的细胞级定量，具体拆为三层：

检测与计数（detection）：找到视野内每一个细胞核并给出边界框——核分裂象计数、有丝分裂指数等分级要素的自动化前提。
分类（classification）：判断核的生物学身份。raw 13 类区分肿瘤、成纤维、淋巴细胞、浆细胞、巨噬细胞、核分裂象、血管内皮、肌上皮、凋亡体、中性粒、导管上皮、嗜酸粒与"无法归类"；main 7 类按临床语义合并（如 tumor_mitotic/tumor_nonMitotic 分开保留了核分裂信息）；super 4 类直接对齐 sTIL 评分规则。
分割（segmentation）：给出核的精确轮廓，用于形态学特征提取（大小、形状、染色质纹理）——DTALE 解释性方法与后续形态计量学的基础。

对应到临床工作流：这三层输出可以聚合为"每张切片的细胞构成报告"，进而支撑分级辅助、TIL 评分、以及肿瘤-免疫空间关系（如三级淋巴结构）的研究。

§2.4 患者人群表

维度	内容
来源	TCGA 乳腺癌（BRCA）队列，18 家美国医疗机构
患者数	125 名（每位患者 1 张 H&E 全切片）
切片类型	诊断性 H&E 染色全切片（40× 扫描倍数）
年龄/性别	TCGA BRCA 队列特征（女性为主）；论文未按年龄/性别分层报告标注分布
种族/地域	美国多机构队列；论文未报告标注 ROI 级别的种族分布
就医类型	肿瘤手术切除标本（TCGA 入组标准）
ROI 选择策略	约 1 mm² ROI，按标注难度分级分配给不同水平参与者

人群解读：该队列的"125 名患者"是标注组织单元而非人群代表性样本；TCGA BRCA 队列本身的临床分层（分子亚型、分级）可经 GDC 合法关联用于分组分析，但 NuCLS 发布包内不含临床协变量，任何亚组结论需自行关联并声明合规路径。

§2.5 临床价值

细胞核级 AI 的临床价值链条是：逐核预测 → 聚合为量化指标 → 辅助分级/预后/治疗反应判断。NuCLS 在这条链上的位置是"训练燃料 + 评估标尺"：

分级辅助：核分裂象（mitotic_figure）与凋亡体的专项标签，为 Notting-ham 分级中的核分裂计数自动化提供了训练样本（尽管该类样本量小，见 §7.1）。
免疫微环境量化：sTIL 超类与淋巴细胞/浆细胞/巨噬细胞的区分，使模型输出可以直接映射到 TIL 工作组的评分规则；MuTILs 的全切片 TIL 评分（与病理医师 Spearman 0.55-0.61）是已发表的概念验证。
报告标准化：间质/肿瘤核的空间区分（nonTIL_stromal vs tumor_any）让"免疫浸润在哪儿"可计算，这是单纯密度统计做不到的。

需要划清的边界：NuCLS 支撑的是研究性量化与辅助指标，不是诊断替代——核分类模型不判读良恶性，TIL 计算评分也不直接进报告。任何临床使用主张（如以 sTIL 评分指导治疗分层）都需要在独立队列上完成分析性能验证与监管路径评估，这超出了数据集本身能提供的内容。

§2.6 金标准表

划分	标注方式	标注者	性质
单评分者（3,944 FOV）	医学生标注，其中约一半经研究协调员依资深病理学家意见修正	32 名非病理学家 + 2 名协调员	修正子集 = 训练主力（59,485 核）；未修正子集 = 噪声标签研究素材
多评分者 Evaluation	同一 FOV 由多人标注，含算法建议	32 NP + 7 病理学家	评分者一致性分析与 NP-labels 共识推断
多评分者 Unbiased 控制集	无算法建议，先于其他集标注	同上	测量"建议偏倚"的实验对照
多评分者 Bootstrap 控制集	建议仅来自图像处理自举（无深度模型）	同上	分离"自举建议"与"Mask R-CNN 建议"的贡献
P-truth	资深病理学家多轮标注 + EM 共识推断	3 名资深病理学家	论文定义的金标准真值，用于评测非专家质量

§3 数据集规格

§3.0 版本抉择矩阵

NuCLS 没有传统意义的"多版本"，但存在三条获取路径与两个数据层级，选择不当会直接踩坑：

你的需求	推荐获取	大小	理由
快速跑通 / 教学	HuggingFace `minhanhto09/NuCLS_dataset`（修正单评分者子集，datasets 库一行加载）	数 GB 内	已封装 RGB/掩码/CSV/六折，无需处理官方包结构
完整研究（多评分者/评分者分析）	官方站点 Google Drive/Dropbox 全量分发包	官方页为准	仅官方包含 multi-rater 三套数据与 P-truth 相关标注
国内网络环境	OpenDataLab 镜像	约 3.1 GB	CLI/SDK 下载，免科学上网
复现论文分析/模型	官方仓库代码 + 官方全量包	同上	`PathologyDataScience/NuCLS` 含建议生成、评分者分析、DTALE 全部脚本
只要"干净标签"训练检测/分类	修正单评分者 CSV（官方包或任一 HF 镜像）	最小	uncorrected 与 multi-rater 适用于噪声标签/一致性研究

§3.1 模态详情

数据模态为乳腺浸润癌 H&E 染色全切片（WSI）的核级标注派生数据。原始 WSI 属于 TCGA 公开资源；NuCLS 发布的不是 WSI 本身，而是三种派生形态：其一，CSV 坐标表——每个核一行，含边界框（xmin/ymin/xmax/ymax）、多边形顶点（coords_x/coords_y）与三级标签；其二，修正单评分者子集的渲染图像——每个 FOV 的 RGB 切片、实例掩码（三通道编码：语义类别/实例 ID）与可视化叠加图，渲染分辨率 0.2 µm/px，坐标与该分辨率像素对齐；其三，官方五折划分文件（按切片/来源医院分组）。ROI 约 1 mm²，图像按扫描倍数（40×）分析；伴随的区域级语义标注由姊妹数据集 BCSS 以 0.25 MPP 提供，两者同源同切片、可联合建模。

§3.2 按子集样本数表

子集	FOV 数	标注数	说明
单评分者（合计）	3,944	128,000（正文一处表述 >125,000）	含修正与未修正两部分
单评分者·修正（QC）	1,744	59,485（其中 19,680 条 polyline 边界）	研究协调员逐核校正后的主力训练集
单评分者·未修正	约 2,200	约 68,515（由 128,000 与修正子集差值推算）	原始医学生标注，带噪声
多评分者·Evaluation	共享 FOV 集	97,300（三套合计）	主要多评分者数据集
多评分者·Bootstrap / Unbiased	同上（子集）	含于上述 97,300	建议偏倚实验对照
总计	—	222,396	论文精确总数

§3.3 格式表

内容	格式	说明
核标注坐标与标签	CSV（每 FOV 一个或聚合大表）	xmin/ymin/xmax/ymax、coords_x/coords_y、type、三级 classification
FOV RGB 图像	PNG	修正单评分者子集，0.2 µm/px
实例/语义掩码	PNG（三通道 uint8）	ch0 语义类别码、ch1/ch2 编码实例 ID；0=ROI 外、253=ROI 填充
可视化叠加	PNG	RGB + 掩码叠加，供人工核对
训练/测试划分	CSV（fold_X_train/fold_X_test）	按切片名分组，5 折 + fold_999 调试折
类别编码映射	CSV（nucleus_GTcodes.csv）	类别码 ↔ 名称 ↔ 颜色，掩码像素值解释的唯一权威来源
官方代码	Python（TensorFlow/Matterport Mask R-CNN + PyTorch DTALE）	MIT 许可

工程提示：官方 CSV 各列类型为对象/整型混合，pandas 读取后 coords_x/coords_y 需按字符串解析再 split(" ") 转列表；不同再托管版本对这两列的处理方式不同（HF loader 已转为嵌套序列），跨镜像迁移代码时这是最容易出错的一处。

§3.4 存储大小

官方完整分发包大小以官方站点当日清单为准（未在论文中固定声明）；第三方镜像（OpenDataLab）记录约 3.1 GB。实际占用注意两点：其一，若只取修正单评分者子集，体积约为全量的一半以下；其二，若从 TCGA 门户拉取对应 125 张原始 WSI 用于全切片推理，需另计每张数百 MB 至数 GB（.svs），与 NuCLS 包本身无关。

§3.5 标注方式

三段式流水线（人工 + 算法辅助混合）：

算法建议生成：先用经典图像处理自举（HoVer-Flags 风格的核边界检测）产生粗建议，再训练 Matterport Mask R-CNN（ResNet50 主干，128×128 随机裁剪 tile、每 tile 限 30 核）精炼，并融合 BCSS 区域先验（如"间质区域不会出现肿瘤核"）过滤不合理类别。
人工标注/确认：参与者在 HistomicsUI 中看到建议边界与类别，正确者单击确认（Evaluation 集 41.7±17.3% 的分割来自单击确认），无建议者手绘矩形框。
质量控制：单评分者标注中约一半由 2 名研究协调员依资深病理学家反馈逐核修正，形成"修正子集"；多评分者数据经约束聚类 + Dawid-Skene EM 推断共识（NP-labels），资深病理学家另标 P-truth。

§3.6 标注者资质与一致性

标注者构成：32 名非病理学家（医学生为主）+ 7 名病理学家（3 名资深、4 名初级，含病理 resident 背景），分布在美、埃、叙、澳、马尔代夫 5 国；2 名研究协调员负责修正。论文系统报告了评分者间一致性（Krippendorff alpha）与评分者内自一致性，核心结论：对视觉 distinctive 的类别（肿瘤核、淋巴细胞）非专家可达接近专家的准确率；对形态学近邻类（浆细胞 vs 淋巴细胞、巨噬细胞 vs 肿瘤）一致性显著下降——这解释了为什么 main/super 两级聚合标签是必要的。算法建议没有伤害病理学家准确率（盲法 + Unbiased 对照验证），但显著提升了非专家的边界质量。

一致性度量	官方做法	对使用者的含义
评分者间一致性	Krippendorff alpha 按类别分层报告	类别可靠性分级：distinctive 类可信赖，近邻类需聚合
评分者内自一致性	同一参与者隔期重复标注同一 FOV	给出人工标注的"噪声地板"，评测指标应以此为参照
共识真值推断	约束聚类对齐同核 + Dawid-Skene EM 推断 NP-labels	多评分者包内自带可用的聚合标签，不必自己重做
评分者数量模拟	仿真实验回答"几人够"	自建标注管线的资源规划依据

§3.7 采集周期

标注研究随论文周期开展：框架前作 BCSS 论文 2019 年发表，NuCLS 数据随 2021-02-18 arXiv 预印本发布、2022-05-17 GigaScience 正式版定稿。论文未单列标注起止日期，精确时间线以论文补充材料为准。

§3.8 地域覆盖

病例来源为 TCGA 联盟 18 家美国医疗机构（乳腺癌）；标注团队覆盖美、埃、叙、澳、马尔代夫 5 国。需要提醒：这是美国单癌种队列，不包含非 TCGA 人群，跨人群泛化需外推验证（见 §7.3）。

§3.9 设备规格

原始切片为 TCGA 各源机构的诊断扫描 WSI（论文按扫描倍数 40× 组织分析，未统一扫描仪型号；BCSS 仓库 meta 目录提供逐切片放大率清单）。NuCLS 发布的 FOV 渲染图统一为 0.2 µm/px；BCSS 区域掩码为 0.25 MPP。跨数据集联合使用时两套分辨率并存是常见错位来源（见坑点 2）。

§3.10 深度溯源链

TCGA 病例（18 家机构手术标本）→ H&E 染色切片 → TCGA 数字化 WSI → 研究者选约 1 mm² ROI 并按难度分配 → HistomicsUI 平台标注（算法建议 + 人工确认/绘制）→ 协调员修正（修正子集）→ 约束聚类 + EM 共识推断（多评分者）→ CSV/掩码/划分文件发布（CC0 1.0）→ GitHub/HuggingFace/Grand-Challenge 多渠道分发。每一环都有公开脚本或论文对应章节背书。

审计提示：链条中唯一的"黑盒"是官方 Drive 包的更新节奏（无变更日志），其余各环节的输入输出均可在论文补充材料与仓库脚本中逐环复算——做数据审计时，建议从"FOV 文件名 ↔ 切片条码 ↔ TCGA GDC 元数据"这条可机器验证的链路入手。

§4 数据结构

§4.0 目录树

官方修正单评分者 QC 包（官方 Drive/Dropbox 的 NuCLS_dataset.zip，亦是 HF 再托管的母本）解压后结构如下：

NuCLS_dataset/
├── rgb/                        # 每个 FOV 的 H&E RGB 切片（0.2 µm/px）
│   ├── TCGA-A1-A0SP-DX1_1_1024_512_512.png
│   └── ...
├── mask/                       # 三通道实例+语义掩码（与 rgb 同名同尺寸）
│   ├── TCGA-A1-A0SP-DX1_1_1024_512_512.png
│   └── ...
├── visualization/              # RGB+掩码叠加的可视化图（人工核对用）
│   └── ...
├── csv/                        # 每 FOV 一份逐核标注表
│   ├── TCGA-A1-A0SP-DX1_1_1024_512_512.csv
│   └── ...
└── train_test_splits/          # 官方五折划分（按切片分组）
    ├── fold_1_train.csv        # 每行一个 slide 名称
    ├── fold_1_test.csv
    ├── fold_2_train.csv
    ├── fold_2_test.csv
    ├── fold_3_train.csv
    ├── fold_3_test.csv
    ├── fold_4_train.csv
    ├── fold_4_test.csv
    ├── fold_5_train.csv
    ├── fold_5_test.csv
    ├── fold_999_train.csv      # 调试折（21 FOV）
    └── fold_999_test.csv       # 调试折（7 FOV）

文件名编码了溯源信息：{TCGA 切片条码}_{ROI 序号}_{WSI 内裁剪坐标}_{FOV 尺寸}，例如 TCGA-A1-A0SP-DX1_1_1024_512_512 表示切片 TCGA-A1-A0SP-DX1 的第 1 个 ROI、从 WSI 坐标 (1024, 512) 起裁剪的 512×512 FOV。官方完整包另含多评分者三套数据与聚合 CSV，结构以官方页说明为准。

§4.1 DAIMS 字段字典

字段名	类型	说明	示例值	AI 用途	观测误差	信息性缺失编码	取值范围
fov_id	string	FOV 文件名（切片条码+裁剪坐标）	TCGA-A1-A0SP-DX1_1_1024_512_512	切片级分组、防泄漏键	无	无	全体 FOV
slide_name	string	TCGA 切片条码	TCGA-A1-A0SP-DX1-DX1	划分分组、跨数据集去重	无	无	125 张切片
raw_classification	string	13 类细粒度标签	lymphocyte	细粒度核分类	近邻类混淆高	unlabeled	13 个枚举值
main_classification	string	7 值临床聚合标签	tumor_mitotic	分级相关任务	聚合层混淆较低	AMBIGUOUS	7 个枚举值
super_classification	string	4 值超类（对齐 sTIL 规则）	sTIL	TIL 定量	间质/肿瘤边界处波动	AMBIGUOUS	4 个枚举值
type	string	标注形态	polyline	区分分割/检测监督信号	无	无	rectangle, polyline
xmin/ymin/xmax/ymax	int	边界框（FOV 像素坐标）	218, 96, 246, 122	检测模型	框比真实核略大	无	0-511
coords_x/coords_y	int 列表	多边形顶点（仅 polyline 有）	[218, 231, …]	实例分割	观测者间 IoU 随核变小而降低	rectangle 标注为空	0-511
mask ch0	uint8 图像通道	语义类别码	3（lymphocyte）	语义分割	与 CSV 一致	0=ROI 外、253=ROI 填充、99=unlabeled	见官方 GT codes
mask ch1/ch2	uint8 图像通道	编码每核唯一实例 ID	3, 7	实例分割	无	ch1=0 且 ch2∈{0,2} 为非核区	0-255

§4.2 标签分布

类别分布高度不均衡且由生物学决定：肿瘤核与间质细胞（成纤维/内皮）构成主体，淋巴细胞次之，浆细胞、巨噬细胞再次，核分裂象、凋亡体、嗜酸粒细胞属稀有类（论文将其列为一致性最低、最需专家把关的类别）。super 层的分布由 ROI 选取策略放大——ROI 偏向肿瘤-间质交界以覆盖 sTIL 评估场景，因此 lymphocyte-rich 视野占比高于随机采样。官方未在论文正文给出逐类计数表，建议使用者在加载后自行统计（§6.1 代码含统计片段），并以论文图表为准校对。

三级标签体系的层级聚合关系（已确认的代表性映射；完整映射以官方包内 nucleus_GTcodes.csv 为准）：

raw（13 类）	→ main（7 值）	→ super（4 值）	层级逻辑
tumor	tumor_nonMitotic	tumor_any	肿瘤核按是否核分裂拆分，super 层合并
mitotic_figure	tumor_mitotic	tumor_any	核分裂被视为肿瘤类别的高价值子类
lymphocyte	lymphocyte	sTIL	间质淋巴细胞是 sTIL 评分的计数对象
plasma_cell	plasma_cell	sTIL	浆细胞属单个核免疫浸润
fibroblast	nonTILnonMQ_stromal	nonTIL_stromal	间质非免疫细胞（non-TIL、非巨噬细胞）
vascular_endothelium	nonTILnonMQ_stromal	nonTIL_stromal	同上
myoepithelium	nonTILnonMQ_stromal	nonTIL_stromal	同上
其余类（macrophage、ductal_epithelium、neutrophil、eosinophil、apoptotic_body）	见 GT codes	部分归 AMBIGUOUS	共识存疑或近邻混淆时落在 AMBIGUOUS
unlabeled（raw 层）	—	—	"无法归类"的显式编码，非背景

使用建议：sTIL 相关任务锁定 super 层；分级相关任务用 main 层（保留 mitotic 信号）；只有类别资源充足、且做了近邻类合并消融时才上 raw 层。

§4.3 关键统计

统计项	数值	来源
核标注总数	222,396	GigaScience 论文
单评分者标注 / FOV	128,000 / 3,944	同上
修正子集核数 / FOV 数	59,485 / 1,744	HF MedOtter 镜像
修正子集 polyline 边界数	19,680（占 33.1%）	同上
多评分者标注（3 套合计）	97,300	GigaScience 论文
患者/切片/机构	125 / 125 / 18	同上
算法建议单击确认率（Evaluation）	41.7±17.3%	同上
建议边界分割精度（Dice）	85.0±5.9	同上

§4.4 数据层级

患者（125 名，每人 1 张切片）
└── WSI（125 张 TCGA H&E 全切片）
    └── ROI（约 1 mm²/个，按难度分级分配）
        └── FOV（3,944 个；修正子集 1,744 个，512×512 @0.2 µm/px）
            └── 细胞核（222,396 条标注：框/多边形 + 三级标签）

层级要点：患者层与切片层一一对应（无多切片患者），FOV 层是"同切片多视野"的真实多实例层——防泄漏的分组键应取 slide_name（或其 TSS 医院码），而不是 FOV。

由此派生的三条使用规则：其一，样本量表述应带层级（“222,396 条标注"不等于"222,396 个独立样本”，独立单元是 125 张切片）；其二，显著性检验与置信区间按切片聚类（cluster-robust）；其三，任何"按 FOV 划分"的对比实验只能作为消融参考，不得作为主结果口径。

§4.5 缺失值与信息性缺失编码

编码/形态	位置	含义	处理建议
像素值 0（掩码 ch0）	ROI 外区域	don’t care 区域	训练损失置零权重，不是"other"类（官方 CRITICAL 警告）
像素值 253（掩码 ch1）	ROI 内非核组织	ROI 填充区（ROI-filler）	同样不计入核级损失
ch0=99（unlabeled）	个别核	标注者无法归类的核	可作背景或"unknown"类；勿强行并入近邻类
AMBIGUOUS	main/super 两级	共识推断无法定论	推荐从训练中剔除或在损失中降权
type=rectangle	CSV 行	只有框、无真实轮廓	检测任务可用；分割监督需过滤或用框代理（见坑点 1）
coords 空列表	rectangle 行	多边形顶点缺失	解析代码需判空，勿直接 np.array 转 NaN
FOV 缺失于某折	train_test_splits	该切片不在对应折	按 fov_id 前缀 join 折表时注意单向匹配

§5 划分与使用建议

§5.1 官方划分

官方包随附五折训练/测试划分 CSV（另含 fold_999 调试折），按来源医院（TCGA TSS 码）分组切片后再分折，保证同一张切片（进而同一患者）只出现在一折的一侧。以修正单评分者子集计，各折 train/test FOV 数为：fold_1 1,481/263、fold_2 1,239/505、fold_3 1,339/405、fold_4 1,450/294、fold_5 1,467/277、fold_999 21/7（HF 加载器源码）；fold_1 测试侧对应 22 张切片。

折	train FOV	test FOV	说明
fold_1	1,481	263	测试侧 22 张切片，社区默认 hold-out
fold_2	1,239	505	测试侧占比最大的折
fold_3	1,339	405	—
fold_4	1,450	294	—
fold_5	1,467	277	—
fold_999	21	7	官方调试折（冒烟测试专用，不用于报告指标）

两点值得注意：其一，各折测试侧规模不等（263-505），折间方差应如实报告而非只取均值；其二，划分文件里是切片名而非 FOV 名——使用者需自行按文件名前缀过滤 FOV（HF 再托管版已代劳，官方包需自己写，见 §6.1）。

§5.2 社区惯例划分

社区最常见的两种用法：其一，五折全跑报均值±标准差（方法学论文首选）；其二，单次 hold-out——默认取 fold_1 的 test 侧（22 张切片）作为验证集，训练集用全部 train 折合并。HuggingFace 再托管版直接把六折封装成 train_fold_X/test_fold_X 命名，debug 配置取 fold_999 便于冒烟测试。

§5.3 划分策略建议与泄漏风险

切片内泄漏（最高频）：同一 WSI 的几十个 FOV 形态高度相似，若按 FOV 随机划分，测试集会记住训练切片的"长相"，指标虚高。永远按 slide_name（或 TSS 医院码）做 GroupKFold。
患者层：本数据集每人只有 1 张切片，患者级与切片级划分等价；但若与 TCGA 其他数据混用（如 BCSS 区域标签做多任务），必须确认切片条码一致才可同侧。
跨数据集泄漏：NuCLS 与 BCSS 共享同批切片，且与 MoNuSeg 等取自 TCGA 的乳腺 patch 级数据存在源重叠——把 MoNuSeg 当"外部测试集"而不去重属于隐性泄漏（见坑点 4）。
医院分组已被官方使用：官方按 TSS 码分组而非纯随机，意味着其指标已部分反映跨机构泛化；自建随机划分得到的数字不可与官方口径直接比较。

§5.4 交叉验证建议

五折协议下建议固定：输入分辨率（如 0.25 或 0.5 MPP 重采样）、类别聚合层（raw/main/super 选一并全程统一）、评估匹配阈值（IoU≥0.5 或匈牙利匹配）。稀有类（mitotic_figure 等）在每折测试侧样本极少，建议报告宏平均并附逐类计数，避免只看微平均掩盖稀有类失效。

§5.5 外部验证建议

合理的外部验证序列：TCGA 内五折（官方口径）→ TCGA 乳腺之外的独立乳腺癌队列（如各机构自有切片或非 TCGA 公共集）→ 其他器官/染色协议数据（预期性能下降明显，NuCLS 本身不支撑跨器官声明）。与同为 TCGA 来源的数据集（MoNuSeg 乳腺切片、BCSS）对比时必须先做切片条码去重（见坑点 4）。

操作层面的三条具体建议：

冻结评测脚本：把 §6.9 的 F1 评测连同匹配阈值、标签聚合层一起固化为仓库内脚本，所有论文/报告引用同一份输出，避免"每次评测口径微妙不同"。
报告噪声底线：把多评分者数据算出的评分者间一致性（论文口径）与模型指标并列展示——模型超过人工噪声地板才有说服力。
分机构细分：官方按 TSS 码分折，天然支持"逐医院性能"分析；上线前至少看一眼最差医院的指标，而不是只看全局均值。

§6 AI 就绪指南

§6.0 云端快速启动

Google Colab / Kaggle 均可直接加载 HuggingFace 再托管版（修正单评分者子集，含六折与图像），无需注册申请。Kaggle 用户可搜索社区上传的 NuCLS Dataset 附件直接挂载；Colab 免费档即可完成 §6.4 的 fold_999 冒烟训练（28 个 FOV，CPU 也能跑通流程，GPU 数分钟收敛）。

# Colab 一键体验 NuCLS（修正单评分者子集）
from datasets import load_dataset

# default 配置 = 全部 1,744 个 FOV；debug = fold_999 的 28 个 FOV（冒烟测试用）
ds = load_dataset("minhanhto09/NuCLS_dataset", name="debug")
print(ds)                      # 含 train_fold_999 / test_fold_999
ex = ds["train_fold_999"][0]   # 每条含 rgb_image / mask_image / visualization_image / annotation_coordinates
ex["rgb_image"].resize((512, 512))

§6.1 快速上手

下面的脚本假定你已从官方站点下载并解压了修正单评分者 QC 包。目录结构预期与拼接关系：data_root 指向 NuCLS_dataset/ 目录，其下应有 csv/、rgb/、mask/、train_test_splits/ 四个子目录（见 §4.0 目录树）；代码把 data_root 与 FOV 文件名拼接定位文件。最小可用子集 = fold_999 的 28 个 FOV，先跑通再放大。

import os
import pandas as pd
from pathlib import Path

# 预期目录结构（data_root 拼接关系）：
#   data_root/
#   ├── csv/{fov_id}.csv            # 每 FOV 逐核标注
#   ├── rgb/{fov_id}.png            # RGB 图像（0.2 µm/px）
#   ├── mask/{fov_id}.png           # 三通道掩码
#   └── train_test_splits/fold_{X}_{train|test}.csv
data_root = Path("NuCLS_dataset")

def load_fold(data_root: Path, fold: int = 1, split: str = "train") -> pd.DataFrame:
    """读取官方划分并聚合该折所有 FOV 的逐核标注为一张宽表。"""
    split_file = data_root / "train_test_splits" / f"fold_{fold}_{split}.csv"
    slides = set(pd.read_csv(split_file).iloc[:, 0].astype(str))
    rows = []
    for fov_csv in sorted((data_root / "csv").glob("*.csv")):
        # fov_id 形如 TCGA-A1-A0SP-DX1_1_1024_512_512：前缀即切片条码
        slide = str(fov_csv.stem).split("_")[0]
        if slide not in slides:
            continue
        df = pd.read_csv(fov_csv)
        df["fov_id"] = fov_csv.stem
        df["slide_name"] = slide
        rows.append(df)
    ann = pd.concat(rows, ignore_index=True)
    print(f"fold_{fold}_{split}: {len(rows)} FOVs, {len(ann)} nuclei")
    return ann

ann = load_fold(data_root, fold=1, split="train")

# 三级标签体系一览 + 类别分布（稀有类一眼可见）
for col in ["raw_classification", "main_classification", "super_classification"]:
    print(f"\n== {col} ==")
    print(ann[col].value_counts())

# 分割监督信号的可用性：polyline 才有真实轮廓
print(ann["type"].value_counts(normalize=True))   # rectangle 约 2/3

§6.2 数据获取

渠道	地址	内容	说明
官方主页	sites.google.com/view/nucls	单评分者/多评分者分发包（Google Drive/Dropbox）	唯一含 multi-rater 与 P-truth 相关数据的入口
Grand Challenge 页	nucls.grand-challenge.org	入口导航 + 论文链接	官方镜像门户
官方代码仓库	github.com/PathologyDataScience/NuCLS	建议生成/评分者分析/DTALE 脚本	MIT 许可
HuggingFace 再托管	`minhanhto09/NuCLS_dataset`、`MedOtter/NuCLS`	修正单评分者子集（含六折）	datasets 库加载，非官方维护
OpenDataLab 镜像	opendatalab.com/OpenDataLab/NuCLS	约 3.1 GB 全量镜像	国内网络友好

# 路线 A：官方包（在官方 Drive/Dropbox 页面手动下载 NuCLS_dataset.zip 后）
unzip NuCLS_dataset.zip -d NuCLS_dataset

# 路线 A'：脚本化拉取官方 Drive 文件（需在官方页复制具体文件 ID 后替换）
pip install gdown
gdown --fuzzy "https://drive.google.com/file/d/<官方文件ID>/view" -O NuCLS_dataset.zip

# 路线 B：HuggingFace（Python 环境直接拉取）
pip install datasets
python -c "from datasets import load_dataset; load_dataset('minhanhto09/NuCLS_dataset')"

# 路线 C：下载完整性自检（官方无版本号，务必指纹存档，见 §6.10）
sha256sum NuCLS_dataset.zip | tee NuCLS_dataset.sha256

无需注册、无需数据使用协议；若需从 TCGA 门户拉取原始 WSI 做全切片推理，另遵守 GDC 数据使用规范。

§6.3 预处理全流程

从官方包到可训练张量的四步：解析 CSV → 生成检测/分割目标 → 归一化 → 类别映射。

import numpy as np
import pandas as pd
from PIL import Image

FOV_SIZE = 512          # 修正单评分者 FOV 为 512×512
MPP_RENDER = 0.2        # 官方渲染分辨率（µm/px）

# ---- 第 1 步：CSV → 检测标签（按 main 层聚合，7 类） ----
MAIN_CLASSES = ["lymphocyte", "macrophage", "nonTILnonMQ_stromal",
                "plasma_cell", "tumor_mitotic", "tumor_nonMitotic", "AMBIGUOUS"]

def fov_to_detection_targets(fov_csv: Path):
    df = pd.read_csv(fov_csv)
    keep = df[df["main_classification"] != "AMBIGUOUS"]      # 剔除共识存疑核
    boxes = keep[["xmin", "ymin", "xmax", "ymax"]].to_numpy()
    labels = keep["main_classification"].map(MAIN_CLASSES.index).to_numpy()
    return boxes, labels

# ---- 第 2 步：掩码三通道解析（语义 + 实例） ----
def parse_mask(mask_png: Path):
    m = np.array(Image.open(mask_png))                        # (H, W, 3) uint8，勿转灰度
    nucleus = (m[..., 0] >= 1) & (m[..., 0] <= 99)            # 核像素（排除 0/253）
    instance = m[..., 2].astype(np.int32) * 256 + m[..., 1]   # ch1/ch2 联合解码实例 ID
    semantic = m[..., 0]
    return semantic, instance, nucleus

# ---- 第 3 步：染色标准化（每图自身零均值/单位方差；跨扫描仪 Macenko 见坑点 7） ----
def stain_normalize(img: np.ndarray) -> np.ndarray:
    img = img.astype(np.float32) / 255.0
    px = img.reshape(-1, 3)
    out = (px - px.mean(axis=0)) / (px.std(axis=0) + 1e-6)
    out = (out - out.min()) / (out.max() - out.min() + 1e-6)
    return (out.reshape(img.shape) * 255).astype(np.uint8)

# ---- 第 4 步：从 TCGA WSI 重切时做 mpp 换算 ----
def px_in_fov_to_mpp(px: float) -> float:
    return px * MPP_RENDER        # FOV 像素 → 微米；与 0.25 MPP 的 BCSS 联用时先统一到此口径

boxes, labels = fov_to_detection_targets(data_root / "csv" / "TCGA-A1-A0SP-DX1_1_1024_512_512.csv")
semantic, instance, nucleus = parse_mask(data_root / "mask" / "TCGA-A1-A0SP-DX1_1_1024_512_512.png")
print(boxes.shape, np.unique(semantic)[:10], nucleus.mean())

§6.4 PyTorch DataLoader 完整代码

import numpy as np
import pandas as pd
import torch
from PIL import Image
from pathlib import Path
from torch.utils.data import Dataset, DataLoader

MAIN_CLASSES = ["lymphocyte", "macrophage", "nonTILnonMQ_stromal",
                "plasma_cell", "tumor_mitotic", "tumor_nonMitotic"]  # 剔除 AMBIGUOUS

class NuCLSDetectionDataset(Dataset):
    """核检测 Dataset：返回 FOV 图像 + 边界框 + main 层类别。

    目录预期（data_root 拼接关系，见 §4.0）：
        data_root/csv/{fov_id}.csv, data_root/rgb/{fov_id}.png,
        data_root/train_test_splits/fold_{f}_{split}.csv
    最小可用子集：fold=999（28 个 FOV）。
    """

    def __init__(self, data_root: str, fold: int = 1, split: str = "train",
                 fov_size: int = 512):
        self.data_root = Path(data_root)
        self.fov_size = fov_size
        slides = set(pd.read_csv(
            self.data_root / "train_test_splits" / f"fold_{fold}_{split}.csv"
        ).iloc[:, 0].astype(str))
        self.samples = []
        for fov_csv in sorted((self.data_root / "csv").glob("*.csv")):
            slide = fov_csv.stem.split("_")[0]
            if slide in slides:
                df = pd.read_csv(fov_csv)
                df = df[df["main_classification"].isin(MAIN_CLASSES)]
                if len(df):
                    self.samples.append((fov_csv.stem, df))

    def __len__(self):
        return len(self.samples)

    def __getitem__(self, idx: int):
        fov_id, df = self.samples[idx]
        img = np.array(Image.open(self.data_root / "rgb" / f"{fov_id}.png").convert("RGB"))
        assert img.shape[:2] == (self.fov_size, self.fov_size), f"{fov_id} 尺寸异常，请检查渲染分辨率"
        boxes = torch.as_tensor(
            df[["xmin", "ymin", "xmax", "ymax"]].to_numpy(), dtype=torch.float32)
        labels = torch.as_tensor(
            df["main_classification"].map(MAIN_CLASSES.index).to_numpy() + 1,  # 0 保留给背景
            dtype=torch.int64)
        area = (boxes[:, 2] - boxes[:, 0]) * (boxes[:, 3] - boxes[:, 1])
        target = {
            "boxes": boxes,
            "labels": labels,
            "image_id": torch.tensor([idx]),
            "area": area,
            "iscrowd": torch.zeros((len(boxes),), dtype=torch.int64),
        }
        img = torch.from_numpy(img).permute(2, 0, 1).float() / 255.0
        return img, target

def collate(batch):
    return tuple(zip(*batch))

if __name__ == "__main__":
    ds = NuCLSDetectionDataset("NuCLS_dataset", fold=999, split="train")
    print(f"FOVs: {len(ds)}, 示例核数: {len(ds[0][1]['labels'])}")
    loader = DataLoader(ds, batch_size=4, shuffle=True, num_workers=2,
                        collate_fn=collate)          # 检测任务必须自定义 collate
    for imgs, targets in loader:
        print(imgs[0].shape, targets[0]["boxes"].shape)
        break

完整训练循环可基于 torchvision 的 fasterrcnn_resnet50_fpn 直接套用上述 Dataset（把 classifier 头替换为 7+1 类），或改用 HoVer-Net/StarDist 等分割框架；官方 DTALE 代码（PathologyDataScience/NuCLS 仓库 nucls_model/）提供了修改版 Mask R-CNN 的参考实现。

<details>
<summary>点击展开：torchvision Faster R-CNN 训练循环参考（约 40 行）</summary>

import torch
from torch.utils.data import DataLoader
from torchvision.models.detection import fasterrcnn_resnet50_fpn, FasterRCNN_ResNet50_FPN_Weights
from torchvision.models.detection.faster_rcnn import FastRCNNPredictor

def build_model(num_classes: int = 7):          # 6 个 main 类 + 背景
    model = fasterrcnn_resnet50_fpn(weights=FasterRCNN_ResNet50_FPN_Weights.DEFAULT)
    in_feat = model.roi_heads.box_predictor.cls_score.in_features
    model.roi_heads.box_predictor = FastRCNNPredictor(in_feat, num_classes)
    return model

def train_one_fold(data_root: str, fold: int = 999, epochs: int = 2,
                   batch_size: int = 4, device: str = "cuda"):
    from NuCLSDetectionDataset import NuCLSDetectionDataset, collate  # §6.4 的类
    model = build_model().to(device)
    params = [p for p in model.parameters() if p.requires_grad]
    opt = torch.optim.SGD(params, lr=5e-3, momentum=0.9, weight_decay=5e-4)
    sched = torch.optim.lr_scheduler.StepLR(opt, step_size=5, gamma=0.5)

    tr = NuCLSDetectionDataset(data_root, fold=fold, split="train")
    va = NuCLSDetectionDataset(data_root, fold=fold, split="test")
    tr_loader = DataLoader(tr, batch_size=batch_size, shuffle=True,
                           num_workers=2, collate_fn=collate)

    for epoch in range(epochs):
        model.train()
        for imgs, targets in tr_loader:
            imgs = [im.to(device) for im in imgs]
            targets = [{k: v.to(device) for k, v in t.items()} for t in targets]
            losses = model(imgs, targets)
            loss = sum(losses.values())
            opt.zero_grad(); loss.backward()
            torch.nn.utils.clip_grad_norm_(params, 10.0)
            opt.step()
        sched.step()
        print(f"fold {fold} epoch {epoch}: loss={loss.item():.4f}")
    torch.save(model.state_dict(), f"fasterrcnn_nucls_fold{fold}.pth")
    return model, va          # 验证集交给 §6.9 的 detection_f1 评测

if __name__ == "__main__":
    train_one_fold("NuCLS_dataset", fold=999, epochs=2)   # fold_999 冒烟测试

</details>

§6.5 坑点 8 个

⚠️ 坑点 1：把 rectangle 当分割真值（分类：预处理陷阱）

问题：修正子集 59,485 个核中只有 19,680 个（33.1%）带真实多边形轮廓，其余 2/3 是"单击确认"产生的矩形框。若把整张掩码当作像素级分割 GT 训练/评测，框内大量背景像素会被当成核，IoU/Dice 被系统性压低，模型也学到错误边界先验。
症状：分割指标明显低于论文量级且调不动；预测掩码呈"方形化"；可视化叠加里核与掩码大面积错位。
解决：

简单方法：训练/评测分割时按 type == "polyline" 过滤，只用 19,680 个有真实轮廓的核；检测任务则全量使用框。

进阶方法：框内先做 Otsu/染色解卷积阈值化生成代理轮廓再训练（弱监督）；评测时框-框用 IoU、多边形-多边形用 IoU，分开报告。

SOTA 方法：以 polyline 核为锚训练 Mask R-CNN/CellViT 类模型，对 rectangle 核只用分类/检测损失（官方论文的 PartialMaskRCNN 思路），既吃下全量标签又不污染分割头。
参考：NuCLS 论文；HF MedOtter 镜像卡

⚠️ 坑点 2：三套分辨率口径混用导致坐标错位（分类：预处理陷阱）

问题：同一研究家族里存在多个"µm/像素"口径——修正单评分者 FOV 渲染与坐标按 0.2 µm/px，BCSS 区域掩码按 0.25 MPP，而 TCQA 原始 WSI 基准分辨率又是另一值。从 TCGA WSI 直接重切 FOV 或与 BCSS 联合训练时，若不做 mpp 换算，标注整体偏移可达 25%。
症状：把 CSV 坐标画到自切 WSI patch 上，核框整体偏移或缩放错位；与 BCSS 掩码叠加时区域与核对不上。
解决：

简单方法：只使用官方提供的 rgb/mask/png 与其配套 CSV，不自行重切，则坐标天然对齐。

进阶方法：重切时统一到物理单位——微米 = 像素 × mpp，任何 patch 重采样后坐标乘 新 mpp/旧 mpp；在 Dataset 里同时缓存 FOV 的 mpp 元数据。

SOTA 方法：以 0.25 MPP（20× 等效）作为管线统一分辨率（MuTILs 采用 0.5 MPP 并在论文中声明），全管线显式携带 OpenSlide 的 MPP 属性做断言校验。
参考：HF minhanhto09 README；BCSS 仓库 MPP 配置；MuTILs 论文

⚠️ 坑点 3：掩码 0 值被当成"other"类训练（分类：标签理解）

问题：掩码像素值 0 表示 ROI 之外（视野外黑色区域），253 表示 ROI 内非核填充区。官方在仓库中用 CRITICAL 字样警告：这些不是类别。把它们当类别训练，损失会被大面积背景主导。
症状：模型训练 loss 很快下降但在测试 FOV 上预测出大片"鬼类别"；语义分割 mIoU 异常高（don’t care 区被计为正确背景）。
解决：

简单方法：生成损失权重图——ch0==0 或 ch1==253 的像素权重置 0。

进阶方法：训练 crop 只从 ROI 内采样，配合 253 填充区加权。

SOTA 方法：使用 per-pixel weight 的 CrossEntropy（如 F.cross_entropy(..., weight=valid_mask)），并在数据质检脚本中断言 0 <= ch0 <= 99 or ch0 == 253。
参考：BCSS 官方仓库警告（NuCLS 掩码沿用同一编码约定）；HF MedOtter 掩码编码说明

⚠️ 坑点 4：与 BCSS/MoNuSeg 等 TCGA 数据的隐性源重叠（分类：数据泄漏）

问题：NuCLS 与 BCSS 来自完全相同的 125 张 TCGA 切片；MoNuSeg 等patch 级基准同样取自 TCGA（含乳腺）。把后者当"外部测试集"而不做切片条码去重，等于用训练切片的亲戚考模型，跨数据集泛化被高估。
症状：模型在"外部"TCGA 系数据上表现好得可疑；在真正独立的机构数据上骤降。
解决：

简单方法：对候选外部集解析 TCGA Patient/Slide 条码，与训练集求交集后剔除。

进阶方法：患者条码（前 12 字符）与切片条码双层去重；patch 级数据集回溯其切片来源清单再比对。

SOTA 方法：外部验证只用非 TCGA 来源队列；若必须在 TCGA 内做，官方五折（按医院分组）+ 论文级声明"非独立外部验证"。
参考：HF MedOtter 镜像卡 overlap 章节；NuCLS 论文

⚠️ 坑点 5：FOV 级随机划分造成切片内泄漏（分类：数据泄漏）

问题：3,944 个 FOV 来自 125 张切片，同一切片的多个 FOV 共享染色风格、扫描特征甚至同一肿瘤区域。按 FOV 随机划分会让测试 FOV 与训练 FOV 同源，指标虚高几个点。
症状：随机划分与官方划分的指标差出明显一截；每折内部指标波动极小（假稳定）。
解决：

简单方法：直接使用官方 train_test_splits（按 TSS 医院分组）。

进阶方法：自建划分时按 slide_name 做 GroupKFold；若与 BCSS 联合训练，按患者条码统一分组。

SOTA 方法：按医院（TSS 码）分组的五折并报告折间均值±标准差，附带 “hospital-held-out” 声明，与官方口径可比。
参考：官方划分文件；HF MedOtter 划分说明

⚠️ 坑点 6：选错标签层级——13 类直接硬训（分类：标签理解）

问题：raw 13 类里浆细胞 vs 淋巴细胞、巨噬细胞 vs 肿瘤核是论文实测评分者一致性最低的近邻类对；直接在 raw 层训练会把这些系统性混淆当"模型错误"去优化，白烧算力还可能过拟合标注者个人风格。
症状：混淆矩阵集中在 {lymphocyte, plasma_cell} 与 {macrophage, tumor_nonMitotic} 两个块；宏 F1 低但微 F1 尚可。
解决：

简单方法：任务只关心免疫/肿瘤时用 super 4 类或 main 7 类训练，与临床规则对齐。

进阶方法：层级分类（先 super 再 main 再 raw）或结构化损失，让粗层兜底细层。

SOTA 方法：参考 MuTILs 的做法——把评分者一致性低的粒度类聚合为可靠组（epithelium/stroma/TILs）再评测，并在论文中报告聚合依据。
参考：NuCLS 论文评分者分析；MuTILs 论文

⚠️ 坑点 7：染色归一化用错对象或引入新偏移（分类：预处理陷阱）

问题：H&E 染色的扫描仪/实验室差异使颜色分布漂移，是病理 AI 最经典的泛化杀手。但 NuCLS 的 FOV 仅 512×512、来自 125 张切片，若把全部 FOV 塞进一个归一化估计器，估计会被切片级聚集污染（同一切片的几十个 FOV 高度相关）。
症状：归一化后部分切片颜色反而异常；跨折指标抖动变大。
解决：

简单方法：仅做每张图像自身的灰度/对比度标准化（零均值方差），避免跨图统计。

进阶方法：按切片级估计 Macenko/Reinhard 染色矩阵，训练/测试各折内部归一；或用 torchstain 对齐到固定目标模板。

SOTA 方法：随机染色增广（H/E 通道扰动）+ 跨扫描仪验证集监控（如折内按扫描仪分层评估），替代激进全局归一化。
参考：NuCLS 论文 ROI/难度设计；通用实践见 staintools/torchstain 文档

⚠️ 坑点 8：用 Panoptic Quality 给小核排名（分类：评估误用）

问题：核分割社区曾流行用 PQ 评测；后续研究用 NuCLS 多评分者数据实证：小核的观测者间 IoU 天然偏低——肉眼"同样好"的轮廓 IoU 可低至 0.45-0.78，而 PQ 以 IoU≥0.5 为匹配阈值，导致排名被轮廓模糊性而非真实质量主导。
症状：模型排名在加入一行"边缘平滑"后剧烈变化；小核类（淋巴细胞）得分被系统性压低。
解决：

简单方法：检测式评测——预测中心与 GT 中心匹配后算分类 F1（NuCLS 原论文口径），回避轮廓阈值敏感性。

进阶方法：报告 IoU 匹配阈值曲线（0.3/0.5/0.7 三档）而非单点 PQ。

SOTA 方法：多指标并列（F1@0.5、AJI、HD95）+ 评分者间 IoU 分布作为噪声底线上下文一起报告。
参考：Panoptic quality 批判论文（Sci Rep 2023）；NuCLS 多评分者数据

§6.6 数据增强

增强方式	安全性	说明
水平/垂直翻转、90° 旋转	✅ 安全	病理图像无方向语义，收益最大
0.8-1.25× 随机缩放 + 平移裁剪	✅ 安全	模拟观察倍率变化；注意同步变换框/多边形坐标
H/E 通道染色扰动	✅ 安全（推荐）	对抗扫描仪色差的最有效手段
小角度（≤15°）旋转、轻度高斯噪声	✅ 安全	幅度控制在形态不变范围
90° 以上任意角度旋转的插值	⚠️ 谨慎	对掩码必须用最近邻插值，否则类别码被污染
灰度化、直方图均衡	❌ 危险	破坏 H&E 染色信息——染色本身就是类别的证据
大幅弹性形变	❌ 危险	核形态（核分裂 vs 肿瘤）是分类依据，形变会伪造病理特征
颜色反转/通道置换	❌ 危险	H&E 双染色通道有固定化学含义

增强实现的两条纪律：其一，框/多边形/掩码必须与图像经同一随机变换（torchvision RandomPhotometricDistort 之外的几何增广需自行同步坐标）；其二，染色扰动幅度应在多评分者数据的"染色一致性范围"内校准——超出评分者之间本来就有的染色差异水平，等于给模型喂不存在于真实分布的样本。

§6.7 模型推荐表

模型	任务适配	起步配置	备注
Faster R-CNN (torchvision)	检测 + 分类	ResNet50-FPN，7+1 类	全量框标注可用，最快跑通
Mask R-CNN（官方 Partial 变体）	检测 + 分类 + 部分分割	ResNet50，框/多边形混合监督	论文同款思路，适合复现
HoVer-Net	实例分割 + 分类	0.25-0.5 MPP 输入	核分割 SOTA 常客，需自行生成密集标签
StarDist	实例分割	星凸半径回归	对凸形核拟合好、速度快
CellViT / ViT 检测头	大规模预训练 + 微调	需较多算力	数据饥饿型，22 万标注正好合适

§6.8 硬件需求表

场景	GPU	显存	说明
fold_999 冒烟测试	任意现代 GPU	≥4 GB	28 个 FOV，CPU 也可跑通流程
检测/分类训练（512×512）	单卡 RTX 3090/4090 级	11-24 GB	batch 4-8，num_workers 2-4
分割训练（0.25 MPP 密集标签）	单卡 A100/4090	≥24 GB	HoVer-Net 类模型吃显存
全切片推理（125 张 WSI）	单卡即可	8 GB+	瓶颈在 WSI 读取 IO，建议多进程 tiling

§6.9 评估指标代码

import numpy as np
import torch

@torch.no_grad()
def detection_f1(pred_boxes, pred_labels, gt_boxes, gt_labels,
                 iou_thresh: float = 0.5, num_classes: int = 6):
    """NuCLS 论文口径的检测式评测：中心/框匹配后按类算 F1。
    pred/gt: tensors of shape (N, 4) 与 (N,)，标签从 1 开始（0=背景）。
    """
    results = np.zeros(num_classes)
    ious = torchvision_boxes_iou(pred_boxes, gt_boxes) if len(pred_boxes) and len(gt_boxes) \
        else torch.zeros((len(pred_boxes), len(gt_boxes)))
    matched_gt = set()
    pairs = []
    for p in range(len(pred_boxes)):
        for g in torch.argsort(ious[p], descending=True):
            if g.item() in matched_gt or ious[p, g] < iou_thresh:
                break
            if pred_labels[p] == gt_labels[g]:
                matched_gt.add(g.item()); pairs.append((pred_labels[p].item(), True))
                break
        else:
            pairs.append((pred_labels[p].item(), False))   # FP
    for c in range(1, num_classes + 1):
        tp = sum(1 for lab, ok in pairs if lab == c and ok)
        fp = sum(1 for lab, ok in pairs if lab == c and not ok)
        fn = sum(1 for g, lab in enumerate(gt_labels.tolist())
                 if lab == c and g not in matched_gt)
        denom = 2 * tp + fp + fn
        results[c - 1] = 2 * tp / denom if denom else np.nan
    return results          # 逐类 F1；宏平均 = np.nanmean(results)

def torchvision_boxes_iou(boxes1, boxes2):
    from torchvision.ops import box_iou
    return box_iou(boxes1, boxes2)

注意：此处刻意采用 NuCLS 论文的"匹配后分类 F1"口径而非 PQ——理由见坑点 8。

五折全跑时的聚合方式（折间不等权，需如实报告）：

import numpy as np

def run_five_folds(data_root: str, train_fn, eval_fn):
    """train_fn/eval_fn 由使用者的模型代码提供；eval_fn 返回逐类 F1 数组。"""
    per_fold = []
    for fold in [1, 2, 3, 4, 5]:                     # fold_999 仅调试，不参与
        model = train_fn(data_root, fold=fold)
        per_fold.append(eval_fn(model, data_root, fold=fold))
    arr = np.stack(per_fold)                         # (5, num_classes)
    print("逐折宏 F1:", np.nanmean(arr, axis=1))
    print("五折宏 F1 = %.3f ± %.3f" % (np.nanmean(arr), np.nanstd(arr)))
    return arr

报告规范：五折结果给 均值±标准差 而非最优折；逐类 F1 附各折该类样本数（稀有类的折间波动是采样噪声而非模型不稳定）。

§6.10 MLOps 笔记

数据版本化：官方无正式版本号，建议把下载包的 SHA256 与获取日期写进实验配置（DVC/LakeDB 均可），防止"Drive 包悄悄更新"导致不可复现。
标签层级即超参：把 raw/main/super 的选择写进配置而非硬编码，论文对比时才能对齐口径。
评测口径固化：匹配阈值、标签聚合、宏/微平均三要素进配置文件；复现 NuCLS 论文数字时用其原始口径（F1@0.5、main/super 层）。
监控漂移：上线后监控预测类别分布 vs 训练分布（§4.2 的不均衡基线），淋巴细胞占比突变往往提示染色或扫描协议漂移。
许可传播：CC0 意味着衍生数据集可自由分发，但引用 giac037 论文是学术礼仪也是可追溯性要求。
再托管一致性：若你的管线同时消费官方包与 HF 镜像，务必在 CI 里加一个一致性冒烟检查（抽 3 个 FOV 比对核数与标签集合），社区镜像偶尔滞后于官方更新。
标注溯源入库：把 type（rectangle/polyline）与 main_classification 是否为 AMBIGUOUS 存入预测结果旁路，后期做误差分析时能快速区分"模型错"与"标签先天不可靠"。
失败案例回放：保存每折最优模型的验证集错误样本（框错位、近邻类混淆、稀有类漏检），NuCLS 的 visualization 叠加图格式可以直接复用做人工复核材料。

§7 质量评估与局限性

§7.1 已知偏倚表

偏倚类型	描述	严重程度	缓解措施
算法建议偏倚	多评分者数据（除 Unbiased 控制集）的边界与类别建议来自弱算法，标注质量可能向建议生成器风格收敛	中	用 Unbiased/Bootstrap 控制集对比；训练分割模型时优先 Unbiased 口径评测
非专家标签噪声	主要标注力来自医学生，近邻类（浆细胞/淋巴细胞）一致性低	中	用修正子集训练；AMBIGUOUS 降权或剔除
稀有类稀缺	mitotic_figure、apoptotic_body、eosinophil 样本极少	高（对相应任务）	罕见类过采样/ focal loss；诚实报告逐类指标
单癌种单队列	仅 TCGA 18 家机构乳腺癌，每人 1 张切片	高（对外推）	外部验证（§5.5）；避免跨器官声明
ROI 选择偏倚	约 1 mm² ROI 偏向肿瘤-间质交界（sTIL 场景），不代表全切片核分布	中	全切片推理时按 tissue 先验加权采样
患者级聚集	125 张切片贡献全部标注，有效独立单元远小于 22 万	中	所有显著性检验按切片聚类稳健标准误

§7.2 标注质量

官方质量证据链在同类数据集中属于最完整的梯队：修正子集经过协调员逐核校正（资深病理学家反馈闭环）；多评分者数据用 Krippendorff alpha 与评分者内自一致性双指标系统量化；P-truth 由 3 名资深病理学家标注并用 EM 共识推断。可以引用的硬数字：算法建议边界的分割精度 Dice 85.0±5.9；Evaluation 集 41.7±17.3% 分割由单击确认产生；建议精炼（高倍 Mask R-CNN）使 sTIL 召回从 76.6 提升到 96.8（MCC 52.7→67.6，区域级 vs 高倍建议对比）。整体判断：肿瘤核/淋巴细胞等 distinctive 类可达高置信；近邻形态类须依赖聚合层级与专家复核。

另一个容易被忽视的质量信号是官方对"标注过程本身"的实验设计：参与者先标单评分者集（相当于训练期），再进入多评分者集；对数据集名称盲法；Unbiased 控制集最先标注以避免经验污染。这意味着数据的可信度不是"声称的"，而是带着实验控制证据的——使用者在论文中引用 NuCLS 时可以放心地把"经协调员修正"作为标签质量表述。

§7.3 泛化性表

目标场景	失效风险	证据
TCGA 内其他乳腺癌切片（未标注 FOV 之外）	低-中	官方划分即按医院分组，模型天然接受跨机构测试
非 TCGA 机构的乳腺癌切片	中-高	队列仅 TCGA；染色/扫描协议差异需染色增广 + 归一化缓解
其他器官 H&E（结肠、前列腺等）	高	数据不含非乳腺组织；跨器官请用 PanNuke/Lizard 类数据
IHC/特殊染色	不适用	NuCLS 仅 H&E 模态
全切片级 TIL 评分	中	MuTILs 已验证可达 Spearman 0.55-0.61，但与视觉评分的一致性仍属"中等"量级

§7.4 伦理

数据全部派生自 TCGA 公开脱敏资源，不含患者身份信息、临床日期或基因组链接；标注任务由专业人员以研究目的完成，无患者接触环节；CC0 1.0 释放了几乎所有再分发限制。使用时仍应遵守 TCGA/GDC 数据使用政策，且不得尝试通过切片条码反向关联基因组/临床敏感数据用于二次识别。

§7.5 公平性

队列层面：TCGA 乳腺癌队列以美国就医人群为主，年龄、种族分布反映其入组结构，论文未提供 ROI 级人口学分层。模型若用于非北美人群，需在目标人群上验证染色与形态分布差异。标注者层面：NuCLS 的跨国标注团队（5 国）反而是研究"标注者背景如何影响一致性"的稀有素材。

公平性审计的两条可行路径：其一，把官方折按 TSS 码细分为单医院测试集，检查是否存在性能系统性偏低的机构（这往往是染色/扫描差异而非人群差异，但要区分清楚）；其二，若你的下游模型将用于临床，应按患者年龄/种族分组重新评测——尽管 NuCLS 自身不带这些标签，TCGA 临床侧表可经 GDC 合法关联（注意合规边界，见 §7.4）。

§7.6 数据漂移

三类潜在漂移：其一，扫描仪代际——TCGA 切片跨 18 家机构与多个扫描批次，模型对新型扫描仪输出需监控（§6.10 分布监控）；其二，染色试剂批间差——H/E 浓度漂移会整体移动颜色空间，建议以染色增广 + Macenko 指标监控；其三，标注协议迭代——官方团队后续工作（MuTILs 等）对类聚合作过调整，跨版本比较时以数据包内 GT codes 文件为准而非论文记忆。

落地为监控指标的建议：训练时把"每切片预测淋巴细胞占比"与"预测肿瘤/间质核比值"存入特征库（如 evidently/自建面板），上线后按周对比训练分布的 PSI（Population Stability Index）；PSI>0.2 通常意味着输入切片的染色或扫描特性已漂出训练分布，此时应触发染色归一化校准或再训练评估，而不是直接怀疑模型退化。

§7.7 DAIMS 24 项检查

#	检查项	状态	说明
1	宽格式	✅	每 FOV 一份 CSV / 可聚合宽表，pandas 直接可用
2	唯一标识	✅	fov_id 编码切片条码+裁剪坐标；核级以 (fov_id, bbox) 唯一
3	特殊字符	⚠️	文件名含下划线分段语义，需按 `_` 解析；无空格/Unicode 风险
4	重复行	✅	逐核一行、无重复；多评分者各评分者独立成行属设计而非重复
5	缺失编码	✅	0/253/99 三种非核编码显式定义并有官方 CRITICAL 警告
6	标签标识	✅	raw/main/super 三级体系 + GT codes 文件 + 掩码通道语义文档化
7	罕见类分组	⚠️	稀有类（核分裂象等）官方已聚合到 main 层，但样本量本身不足
8	偏倚评估	✅	算法建议偏倚有 Bootstrap/Unbiased 双控制集，评分者分析系统完整
9	数据字典	✅	GT codes CSV + 论文 + 官方仓库文档三重来源
10	信息性缺失解释	⚠️	rectangle（无轮廓）与 AMBIGUOUS（共识存疑）有语义，但官方未写"应如何处理"的操作指南
11	设备记录	✅	按扫描倍数组织并提供逐切片放大率清单（BCSS meta）
12	共线性	⚠️	图像数据无经典共线性问题；DTALE 形态学特征间存在相关需注意
13	编码映射	✅	官方 nucleus_GTcodes.csv 给出类别码↔名称↔颜色映射
14	时间戳处理	⚠️	静态图像数据无时间戳维度；切片采集日期未随包发布
15	划分建议	✅	官方五折 CSV（按医院分组）+ 调试折，即取即用
16	泄漏讨论	✅	切片级分组设计 + 本百科 §5.3/坑点 4-5 系统梳理跨数据集重叠
17	标签分布	✅	论文报告类别构成与不均衡；可自行复算（§6.1 代码）
18	测量偏倚	⚠️	建议偏倚已被官方识别并设对照，但修正子集的修正者间差异未完全量化
19	外部验证建议	✅	论文与 MuTILs 展示了下游外部评估路径；本百科 §5.5 给出序列
20	版本记录	⚠️	无正式版本号与变更日志；QC 包更新以 Drive 为准，需自行指纹存档
21	预处理脚本	✅	官方仓库含建议生成/训练/分析全链路脚本（MIT）
22	合规要求	✅	CC0 1.0 + TCGA 脱敏，无 DUA 门槛
23	多模态对齐	✅	与 BCSS 区域标注同源同切片，可像素级/区域级联合
24	去标识化	✅	TCGA 公开脱敏切片派生，无身份信息

DAIMS 评分：20.5 / 24

评分解读：优秀——这是标注方法学最透明的一档数据集：偏倚有对照实验、编码有显式定义、划分官方提供、溯源链完整。扣分集中在工程化收尾（无版本号/变更日志、缺失处理缺操作指南）与稀有类先天不足，属于"研究级完备、产品级欠一口气"。

对你意味着什么：（1）可以直接把官方五折 + 修正子集当训练主力，不必自己造划分；（2）动手前先花半小时读 GT codes 与掩码编码（0/253/99），能避免最贵的返工；（3）稀有类任务（核分裂检测）不要以本数据集为主要训练源；（4）如果你的工作要发论文，把 rectangle/polyline 比例与 AMBIGUOUS 处理策略写进方法节——这是审稿人对 NuCLS 的高频追问点；（5）生产部署请自行加版本指纹（§6.10），官方包没有替你做。

§7.8 外部验证矩阵

外部数据集/场景	来源机构	评估任务	性能指标	相对内部变化	关键发现
MuTILs 全切片 TIL 评分（TCGA 队列视觉评分对照）	西北大学等（npj Breast Cancer 2024）	TIL 评分一致性	Spearman 0.55-0.61（p<0.001）	未适用（首建基准）	NuCLS+BCSS 训练的计算评分与病理医师视觉评分中等相关，核分类全面优于对比 Mask R-CNN（TIL 核约 +2%）
观测者间轮廓模糊性分析（NuCLS 多评分者数据）	荷兰 Radboud 团队等（Sci Rep 2023）	小核 IoU 分布	"好"轮廓 IoU 可低至 0.45-0.78	未适用	证明 PQ 阈值对小核不公平，推荐 F1 式评测

§8 基准性能与生态

§8.1 排行榜

NuCLS 没有常设竞赛排行榜（grand-challenge 页面仅作数据门户），以下为已发表的代表性结果：

排名	模型	性能	年份	关键技术	完整引用	代码
1	MuTILs	核分类优于对比 Mask R-CNN（TIL 核约 +2%，全部核类型占优）；全切片 TIL 评分与视觉评分 Spearman 0.55-0.61	2024	全景分割（组织区域 + 核实例联合）、ROI 显著性加权	Amgad M, et al. A panoptic segmentation dataset and deep-learning approach for explainable scoring of tumor-infiltrating lymphocytes. npj Breast Cancer, 2024. DOI 10.1038/s41523-024-00663-1	官方 GitHub（见原文）
2	NuCLS 官方 Mask R-CNN + DTALE	建议边界分割 Dice 85.0±5.9；高倍建议使 sTIL 召回 96.8（vs 76.6）	2021/2022	弱算法建议 + 区域先验融合 + 决策树近似嵌入解释	Amgad M, et al. NuCLS: A scalable crowdsourcing approach and dataset… GigaScience, 11, 2022. DOI 10.1093/gigascience/giac037；Amgad M, et al. Explainable nucleus classification using DTALE. Bioinformatics, 2021	PathologyDataScience/NuCLS
3	社区 YOLOv8 再托管演示	检测框级定性良好（非同行评审）	2023	修正子集 + 官方六折直接训练	minhanhto09, NuCLS Dataset（HuggingFace 数据卡）	HF 仓库

数值不可直接比较的原因：三行结果的类别层级（super/main/raw）、监督形态（框 vs 多边形 vs 全景）、评测口径（Dice vs F1 vs Spearman）各不相同；第 1、2 行来自论文同行评审，第 3 行仅为社区演示。任何"在 NuCLS 上 SOTA"的声明都应先核对口径。

解读这两行同行评审结果的正确姿势：官方 Mask R-CNN 的数字刻画的是"标注管线质量"（建议边界多准、建议是否带偏），而非"NuCLS 上限"——它用的是 2021 年的弱基线；MuTILs 则给出了"数据 + 现代全景架构"在 TIL 临床任务上的当前水位。两者相减的空隙（例如分割上限、raw 层细粒度分类、跨机构泛化）正是后续工作可以发力的地方。

§8.2 SOTA 总结与选型建议

当前对 NuCLS 的最佳实践可归纳为：以官方五折为评测骨架，检测/分类任务用 main 或 super 层级 + 匹配 F1 口径（官方可比），分割任务以 polyline 子集监督、多指标（F1/AJI/HD95）报告，TIL 下游任务把聚合规则写透明。若目标是刷指标，22 万标注规模更 reward 预训练视觉主干（CellViT 类）而非小模型精调；若目标是方法学贡献，Unbiased 控制集与评分者分析脚本是被低估的研究富矿。

按目标选型的具体建议：

你的目标	推荐路径	理由
快速出 baseline 论文数字	torchvision Faster R-CNN + main 层 + 官方五折	口径官方可比，算力门槛低
追求分割上限	HoVer-Net/CellViT + polyline 子集 + 多指标	polyline 监督质量高，预训练主干收益大
TIL 定量研究	super 层检测 + TIL WG 聚合 + Spearman 对标 MuTILs	有已发表参照系
标注方法学论文	多评分者三套数据 + 官方分析脚本复现	控制集设计罕见且完备
教学演示	HF debug 折 + YOLOv8/快速检测	28 个 FOV 十分钟跑通

§8.3 评测协议

推荐协议（与官方及后续论文可比）：输入重采样至 0.25 MPP 或声明固定值；标签层级三选一并全程统一；训练/测试用官方 fold CSV；检测分类报逐类 + 宏平均 F1@0.5；分割报 F1@{0.3,0.5,0.7} 三档 + AJI；TIL 任务报与视觉评分的 Spearman/Bland-Altman。所有显著性检验按切片聚类。

三份"协议声明清单"（写进论文实验节即可）：输入分辨率与插值方式；标签层级 + AMBIGUOUS/rectangle/unlabeled 的处理策略；匹配阈值与逐类/宏平均选择。这三点口径不同是 NuCLS 上各论文数字不可比的三大主因。

数据集	规模	模态	标注	关系
BCSS	与 NuCLS 同批 125 张切片	乳腺 H&E WSI	区域语义掩码（0.25 MPP）	姊妹集，区域级 ↔ 核级联合
MoNuSeg	30 patch（40×），约 2.2 万核	7 器官 TCGA	像素级实例	跨器官泛化基准；乳腺部分与 NuCLS 源重叠需去重
MoNuSAC	MoNuSeg 扩展，4 类	多器官	实例 + 4 类	多分类分割对照
PanNuke	约 20 万核，19 组织	多癌种 H&E	半自动实例 + 5 类	泛癌核分类对照
Lizard	约 50 万核	结肠 H&E	多边形 + 6 类	大规模核分类对照（结肠）
BACH	500 显微图 + 40 WSI	乳腺 H&E	图像级/像素级 4 类	病变级分类基准
TNBC（Naylor）	50 图 / 11 患者	三阴性乳腺 H&E	像素级实例	高核密度难例分割对照

§8.5 关键论文 Top 6

Amgad M, Atteya LA, Hussein H, et al. NuCLS: A scalable crowdsourcing approach and dataset for nucleus classification and segmentation in breast cancer. GigaScience, 11, 2022. DOI 10.1093/gigascience/giac037 — 数据集主论文：众包框架 + 评分者分析 + 建议策略。
Amgad M, Atteya LA, Hussein H, et al. NuCLS: A scalable crowdsourcing, deep learning approach and dataset… arXiv:2102.09099, 2021 — 预印本版本（含更早期实验数字）。
Amgad M, Elfandy H, et al. Structured crowdsourcing enables convolutional segmentation of histology images. Bioinformatics, 35(18):3461-3467, 2019. DOI 10.1093/bioinformatics/btz083 — 框架前作 BCSS，区域级标注与结构化众包方法论。
Amgad M, et al. Explainable nucleus classification using Decision Tree Approximation of Learned Embeddings. Bioinformatics, 2021 — DTALE 可解释核分类方法（NuCLS 官方模型论文）。
Amgad M, et al. A panoptic segmentation dataset and deep-learning approach for explainable scoring of tumor-infiltrating lymphocytes. npj Breast Cancer, 2024. DOI 10.1038/s41523-024-00663-1 — NuCLS 最大的下游临床应用验证（MuTILs）。
Panoptic quality should be avoided as a metric for assessing cell nuclei segmentation and classification in digital pathology. Scientific Reports, 13, 2023. DOI 10.1038/s41598-023-35605-7 — 用 NuCLS 多评分者数据实证"好"轮廓的 IoU 分布，论证 PQ 指标对小核不公平（作者名单以期刊页面为准）。

§8.6 社区活跃度

官方渠道维护平稳：Grand Challenge 门户 + Google Sites 主页 + GitHub 仓库（代码 MIT、持续可访问）；引用曲线健康（Semantic Scholar 117+，截至 2026-09，且 2024 年仍有 npj Breast Cancer 级别下游工作产出）；HuggingFace 存在多个社区再托管镜像（minhanhto09、MedOtter），说明"开箱即用"需求真实存在。没有活跃的竞赛机制，问题反馈以直接邮件联系作者团队为主（官方页留有联系方式）。

对使用者的实际含义：NuCLS 处于"稳定维护但不再快速迭代"的状态——数据本身已随 GigaScience 正式版定稿，官方团队的精力转向 MuTILs 等下游工作；因此预期不会有"官方 PyTorch 加载器"之类的新增交付物，工程化封装依赖社区镜像或自行实现，选型时请把这一维护预期纳入考量。

§8.7 生态快照表

资源	类型	链接	Star/热度（截至 2026-09）	推荐理由
PathologyDataScience/NuCLS	官方代码仓库	GitHub	—	建议生成/评分者分析/DTALE 全链路脚本
PathologyDataScience/BCSS	姊妹数据集仓库	GitHub	—	区域先验、掩码编码约定、逐切片元数据
nucls.grand-challenge.org	官方门户	Grand Challenge	—	分发链接总入口
minhanhto09/NuCLS_dataset	HF 再托管	HuggingFace	—	datasets 库一行加载 + EDA Notebook
MedOtter/NuCLS	HF 再托管	HuggingFace	—	逐 FOV 打包、折成员保留、文档详尽
OpenDataLab/NuCLS	国内镜像	OpenDataLab	—	约 3.1 GB 全量镜像，国内下载友好

§9 相关资源与引用

§9.1 官方资源

官方主页（下载 + 单评分者/多评分者分页 + FAQ）：sites.google.com/view/nucls
Grand Challenge 数据门户：nucls.grand-challenge.org
官方代码仓库：github.com/PathologyDataScience/NuCLS
姊妹数据集 BCSS 仓库：github.com/PathologyDataScience/BCSS
主论文（开放获取全文）：PMC9112766
数字幻灯片平台（在线浏览标注）：Digital Slide Archive 公共实例
社区再托管（datasets 库加载）：minhanhto09/NuCLS_dataset、MedOtter/NuCLS
国内镜像：OpenDataLab/NuCLS

§9.2 BibTeX 引用块

@article{amgad2022nucls,
  title     = {NuCLS: A scalable crowdsourcing approach and dataset for nucleus
               classification and segmentation in breast cancer},
  author    = {Amgad, Mohamed and Atteya, Lamees A and Hussein, Hagar and
               Mohammed, Kareem Hosny and Hafiz, Ehab and Elsebaie, Maha AT and
               Alhusseiny, Ahmed M and AlMoslemany, Mohamed Atef and
               Elmatboly, Abdelmagid M and Pappalardo, Philip A and Sakr, Rokia Adel and
               Mobadersany, Pooya and Rachid, Ahmad and Saad, Anas M and others},
  journal   = {GigaScience},
  volume    = {11},
  year      = {2022},
  doi       = {10.1093/gigascience/giac037}
}

@article{amgad2019structured,
  title     = {Structured crowdsourcing enables convolutional segmentation of histology images},
  author    = {Amgad, Mohamed and Elfandy, Habiba and Hussein, Hagar and others},
  journal   = {Bioinformatics},
  volume    = {35},
  number    = {18},
  pages     = {3461--3467},
  year      = {2019},
  doi       = {10.1093/bioinformatics/btz083}
}

@article{amgad2021dtale,
  title     = {Explainable nucleus classification using Decision Tree Approximation
               of Learned Embeddings},
  author    = {Amgad, Mohamed and Atteya, Lamees A and Hussein, Hagar and others},
  journal   = {Bioinformatics},
  year      = {2021}
}

@article{amgad2024mutils,
  title     = {A panoptic segmentation dataset and deep-learning approach for
               explainable scoring of tumor-infiltrating lymphocytes},
  author    = {Amgad, Mohamed and others},
  journal   = {npj Breast Cancer},
  year      = {2024},
  doi       = {10.1038/s41523-024-00663-1}
}

§9.3 引用指南

使用数据集引用 amgad2022nucls（GigaScience 正式版，DOI 可解析）；使用官方代码/方法引用对应仓库与 amgad2021dtale；联合使用 BCSS 区域标注引用 amgad2019structured；在 TIL 下游任务上比较则引用 MuTILs。CC0 不豁免学术引用义务——把出处写清楚也是结果可复现的一部分。

引文位置规范建议：数据首次出现的"方法-数据"段落数据集名处挂 giac037；划分口径描述处注明"官方五折（按 TSS 医院分组）"；标签层级选择处引用官方 GT codes；评测指标若采用 F1 口径，同时引用 NuCLS 论文与 PQ 批判论文（Sci Rep 2023），为"为什么不用 PQ"提供文献支撑。

§10 AI 使用声明卡

§10.1 AI 模型列表

模型	用途	版本
CodeBuddy Code（fast-model）	本条目初稿撰写、结构编排、代码示例生成	2026-09
无其他模型	检索与事实核验由 AI Agent 结合 WebSearch/WebFetch 完成，人工复核	—

§10.2 AI 参与范围

本页面的章节文字、表格整理、代码示例由 AI 生成初稿；事实性内容（规模数字、划分、类别体系、license、基准结果）全部经 WebSearch/WebFetch 多源核验并落盘 FACTS.md（共 6 次检索 + 8 次权威页面抓取）；医学映射与临床解读参照平台已发布条目的一致口径编写；最终由千方病案医学编辑部人工审核后发布。

§10.3 输入来源列表

Amgad M, et al. NuCLS: A scalable crowdsourcing approach and dataset for nucleus classification and segmentation in breast cancer. GigaScience, 11, 2022. DOI 10.1093/gigascience/giac037（全文经 PMC9112766 提取）
Amgad M, et al. NuCLS: A scalable crowdsourcing, deep learning approach and dataset… arXiv:2102.09099, 2021. https://arxiv.org/abs/2102.09099
NuCLS 官方主页. https://sites.google.com/view/nucls/home
NuCLS Grand Challenge 门户. https://nucls.grand-challenge.org/
NuCLS 官方代码仓库（含许可与论文列表）. https://github.com/PathologyDataScience/NuCLS
BCSS 官方仓库（掩码编码警告、MPP 配置、许可）. https://github.com/PathologyDataScience/BCSS
Amgad M, et al. Structured crowdsourcing enables convolutional segmentation of histology images. Bioinformatics, 2019. DOI 10.1093/bioinformatics/btz083
minhanhto09/NuCLS_dataset（HuggingFace 数据卡与加载器源码：13/7/4 类枚举、六折划分、0.2 µm/px 渲染说明）. https://huggingface.co/datasets/minhanhto09/NuCLS_dataset
MedOtter/NuCLS（HuggingFace 数据卡：1,744/59,485/19,680 核心计数、划分分组与重叠警示）. https://huggingface.co/datasets/MedOtter/NuCLS
Amgad M, et al. A panoptic segmentation dataset and deep-learning approach for explainable scoring of tumor-infiltrating lymphocytes. npj Breast Cancer, 2024. DOI 10.1038/s41523-024-00663-1. https://www.nature.com/articles/s41523-024-00663-1
Panoptic quality should be avoided as a metric for assessing cell nuclei segmentation and classification in digital pathology. Scientific Reports, 13, 2023. DOI 10.1038/s41598-023-35605-7
OpenDataLab NuCLS 镜像页（约 3.1 GB 大小记录）. https://opendatalab.com/OpenDataLab/NuCLS
Semantic Scholar API 引用计数快照（117，截至 2026-09）. https://api.semanticscholar.org/graph/v1/paper/DOI:10.1093/gigascience/giac037
千方病案医数集已发布条目 BACH_Wikipedia.md（乳腺癌 ICD-11/SNOMED CT 映射一致口径）

§10.4 人工校验表

内容模块	审核者	审核方式	审核状态
§1-§3 规模数字与版本事实	千方病案医学编辑部	与 PMC 全文、arXiv 摘要、官方仓库逐项比对	✅ 已验证
§2 医学背景与 ICD/SNOMED 映射	千方病案医学编辑部	参照平台已发布乳腺条目一致口径复核	✅ 已通过
§4 DAIMS 数据字典与掩码编码	千方病案医学编辑部	与官方 GT codes 及 HF 镜像文档交叉比对	✅ 已验证
§5 划分与泄漏分析	千方病案医学编辑部	对照官方五折文件与论文划分描述	✅ 已通过
§6 坑点与代码示例	千方病案医学编辑部	依据官方仓库警告、HF 文档与论文 limitations 归纳；代码经语法自查	✅ 已验证
§7 DAIMS 评分与偏倚结论	千方病案医学编辑部	逐项对照事实清单复核	✅ 已通过
§8 基准与引用信息	千方病案医学编辑部	与论文原文及 Semantic Scholar 快照核对	✅ 已验证
§9 BibTeX 与资源链接	千方病案医学编辑部	DOI 可解析性与链接可达性抽查	✅ 已通过

§10.5 AI 生成章节标注

本条目全部章节由 AI 生成初稿，人工校验覆盖表见 §10.4；其中 §2.2 流行病学数字（GLOBOCAN 2022）与 §2.5 临床价值表述为 AI 依据公开文献整理，编辑部已重点复核。

§10.6 最后人工审核日期

2026-09-05（与 §0.3 一致）

页面状态：published（全部内容已完成审核并发布）

返回 AI-Ready 数据集