Scientific Agent SkillsIDC 数字病理数据查询实战指南SM / ANN / SEG 索引表与 SQL 模式【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills本篇围绕 NCI 影像数据共同体Imaging Data CommonsIDC中的数字病理数据讲解如何用idc-index客户端的本地 DuckDB 索引表对全切片显微图像Slide MicroscopySM、显微批量简单标注Microscopy Bulk Simple AnnotationsANN与病理分割SEG做元数据发现、肿瘤/正常组织区分和预计算分析结果的检索。读完后你将能够脱离 BigQuery直接对 IDC v24 数据版本执行病理相关的 SQL 查询并掌握从索引发现到下载、测量提取的完整工作流。以下内容继承自技能包中的数字病理参考文档 skills/imaging-data-commons/references/digital_pathology_guide.md并结合本仓库 skills/imaging-data-commons/SKILL.md 的索引表总览与 scripts/check_version.py 的版本校验逻辑进行了扩充说明。版本基线idc-index 0.12.5 与 IDC 数据版本 v24原指南在开头明确标注Tested with: idc-index 0.12.5IDC 数据 version v24。这是一个必须重视的前提——所有查询列名如min_PixelSpacing_2sf、primaryAnatomicStructureModifier_CodeMeaning和示例结果如 TCGA-BRCA 的幻灯片计数都以该版本为准版本升级后列结构可能变化。仓库中这一版本约束有双重佐证skills/imaging-data-commons/SKILL.md 的 frontmatter 元数据中固定了idc-index: 0.12.5与idc-data-version: v24scripts/check_version.py 中MIN_VERSION 0.12.5、SKILL_VERSION 1.8.1脚本本身从不执行安装仅在版本不满足时打印面向当前解释器的安装命令并以非零码退出把环境选择权留给调用者。因此开始数字病理查询前的标准动作是# 在技能包根目录运行校验 idc-index 是否安装且版本不低于 0.12.5 python skills/imaging-data-commons/scripts/check_version.py会话内则用客户端确认数据版本from idc_index import IDCClient client IDCClient() # 校验 IDC 数据版本应为 v24 print(fIDC data version: {client.get_idc_version()})对于通用查询与下载非病理专属主技能文档 SKILL.md 提供了完整的路由规则MCP / REST / 本地索引三选一本篇只聚焦其中的病理分支SM、ANN、SEG 三类对象。五张病理专用索引表数字病理的核心是五张专门化的索引表。它们携带人工整理的curated元数据无需 BigQuery即可完成绝大多数发现工作表行粒度说明sm_index1 行 1 个 SM 系列全切片显微系列元数据容器/玻片 ID、组织类型、解剖结构、诊断、物镜倍数、像素间距、图像尺寸sm_instance_index1 行 1 个 SM 实例单张切片图像的实例级SOPInstanceUID元数据seg_index1 行 1 个 SEG 系列DICOM 分割元数据算法名、segment 数量、源系列引用。放射与病理共用——需按源 Modality 过滤出病理分割ann_index1 行 1 个 ANN 系列显微批量简单标注系列元数据含referenced_SeriesInstanceUID指向被标注的切片ann_group_index1 行 1 个标注组标注组细节AnnotationGroupLabel、GraphicType、NumberOfAnnotations、AlgorithmName、属性编码这些表与本仓库 references/index_tables_guide.md 中的完整索引表清单一致该文档的Join Column Reference小节还给出了一致性更强的连接键约定与病理相关的四条是表 A表 B连接条件indexsm_indexindex.SeriesInstanceUID sm_index.SeriesInstanceUIDindexseg_indexindex.SeriesInstanceUID seg_index.segmented_SeriesInstanceUIDindexann_indexindex.SeriesInstanceUID ann_index.SeriesInstanceUID取标注系列自身ann_index.referenced_SeriesInstanceUID index.SeriesInstanceUID取被标注的源系列ann_indexann_group_indexann_index.SeriesInstanceUID ann_group_index.SeriesInstanceUID两条硬性规则贯穿所有后续示例查询任何索引表之前先client.fetch_index(table_name)。该调用对所有表包括启动时自动加载的都安全且幂等。写 SQL 前先查 schema用client.indices_overview程序化检查列名与类型或client.get_index_schema(table)读取缓存的元数据。不要凭记忆假设列名——这是 IDC 查询返回空结果的第一大原因主技能文档在 Discovery 一节反复强调同一模式先枚举值再过滤。Slide MicroscopySM查询基本 SM 元数据sm_index是病理元数据最丰富的表。下面按集合统计切片数量与最高分辨率min_PixelSpacing_2sf保留两位小数的最小像素间距间距越小分辨率越高from idc_index import IDCClient client IDCClient() # sm_index 元数据详尽与 index 连接可取 collection_id client.fetch_index(sm_index) client.sql_query( SELECT i.collection_id, COUNT(*) as slides, MIN(s.min_PixelSpacing_2sf) as min_resolution FROM sm_index s JOIN index i ON s.SeriesInstanceUID i.SeriesInstanceUID GROUP BY i.collection_id ORDER BY slides DESC )按物镜倍数找高分辨率系列ObjectiveLensPower记录物镜倍率。找 40 倍及以上、按分辨率排序的高清切片client.fetch_index(sm_index) client.sql_query( SELECT i.collection_id, i.PatientID, s.ObjectiveLensPower, s.min_PixelSpacing_2sf FROM sm_index s JOIN index i ON s.SeriesInstanceUID i.SeriesInstanceUID WHERE s.ObjectiveLensPower 40 ORDER BY s.min_PixelSpacing_2sf LIMIT 20 )按标本制备方式过滤染色 / 包埋 / 固定sm_index包含染色staining、包埋介质embedding、固定液fixative三类元数据。注意这些列是数组类型——例如 HE 切片会是[hematoxylin stain, water soluble eosin stain]因此过滤要用array_to_string()配LIKE或用list_contains()直接对数组列做等值匹配会漏掉多值行# 在指定集合中找 HE 染色切片 client.fetch_index(sm_index) client.sql_query( SELECT i.PatientID, s.staining_usingSubstance_CodeMeaning as staining, s.embeddingMedium_CodeMeaning as embedding, s.tissueFixative_CodeMeaning as fixative FROM sm_index s JOIN index i ON s.SeriesInstanceUID i.SeriesInstanceUID WHERE i.collection_id tcga_brca AND array_to_string(s.staining_usingSubstance_CodeMeaning, , ) LIKE %hematoxylin% LIMIT 10 )跨集合比较 FFPE 石蜡切片与冷冻切片client.sql_query( SELECT i.collection_id, s.embeddingMedium_CodeMeaning as embedding, COUNT(*) as slide_count FROM sm_index s JOIN index i ON s.SeriesInstanceUID i.SeriesInstanceUID GROUP BY i.collection_id, embedding ORDER BY i.collection_id, slide_count DESC )区分肿瘤与正常切片sm_index提供了两条互补的组织类型识别路径列适用场景primaryAnatomicStructureModifier_CodeMeaning来自 DICOM 标本元数据的结构化组织类型如Neoplasm, Primary、Normal、Tumor、Neoplasm, Metastatic。在所有含 SM 数据的集合上通用。ContainerIdentifier切片/容器标识。TCGA 集合中该字段是 TCGA 条形码其中第 14–15 位的样本类型码编码组织来源01–09 肿瘤10–19 正常。两条路径各有所长结构化元数据跨集合通用但可能为 NULL条形码方法仅适用于 TCGA 集合却能兜底结构化元数据缺失的情况。路径一结构化组织类型元数据先枚举全库组织类型取值再按集合统计。以下结果基于 idc-index 0.12.5 / IDC v24 数据from idc_index import IDCClient client IDCClient() client.fetch_index(sm_index) # 发现所有 SM 数据中的组织类型取值 client.sql_query( SELECT s.primaryAnatomicStructureModifier_CodeMeaning as tissue_type, COUNT(*) as slide_count FROM sm_index s WHERE s.primaryAnatomicStructureModifier_CodeMeaning IS NOT NULL GROUP BY tissue_type ORDER BY slide_count DESC )以 TCGA-BRCA 为例# TCGA-BRCA 的组织类型分布 client.sql_query( SELECT s.primaryAnatomicStructureModifier_CodeMeaning as tissue_type, COUNT(*) as slide_count, COUNT(DISTINCT i.PatientID) as patient_count FROM sm_index s JOIN index i ON s.SeriesInstanceUID i.SeriesInstanceUID WHERE i.collection_id tcga_brca GROUP BY tissue_type ORDER BY slide_count DESC ) # 指南记录的结果Neoplasm, Primary2704 张、Normal399 张路径二TCGA 条形码仅限 TCGA 集合TCGA 集合中ContainerIdentifier即切片条形码如TCGA-E9-A3X8-01A-03-TSC第 4 段的前两位就是样本类型码# 从 TCGA 条形码解析样本类型码 client.sql_query( SELECT SUBSTRING(SPLIT_PART(s.ContainerIdentifier, -, 4), 1, 2) as sample_type_code, s.primaryAnatomicStructureModifier_CodeMeaning as tissue_type, COUNT(*) as slide_count FROM sm_index s JOIN index i ON s.SeriesInstanceUID i.SeriesInstanceUID WHERE i.collection_id tcga_brca GROUP BY sample_type_code, tissue_type ORDER BY sample_type_code ) # 指南记录的结果01 → Neoplasm, Primary270406 → None811 → Normal399条形码方法的价值在最后一行数据上类型码06转移灶对应的 8 张切片在 TCGA-BRCA 中primaryAnatomicStructureModifier_CodeMeaning为 NULL——只依赖结构化元数据的查询会静默丢掉这些切片。实践建议是两条路径并用用条形码兜底 NULL 情况。标注ANN查询DICOM Microscopy Bulk Simple AnnotationsModality ANN是画在显微切片图像之上的标注对象。它们分两级出现在索引中ann_index系列级与ann_group_index标注组级。每个 ANN 系列通过referenced_SeriesInstanceUID指向它标注的那张切片——这是做标注 ↔ 原图关联的唯一桥梁。基础标注发现# 找标注系列及其引用的原图系列 client.fetch_index(ann_index) client.fetch_index(ann_group_index) client.sql_query( SELECT a.SeriesInstanceUID as ann_series, a.AnnotationCoordinateType, a.referenced_SeriesInstanceUID as source_series FROM ann_index a LIMIT 10 )标注组统计按图形类型汇总标注总量点、线、多边形等client.sql_query( SELECT GraphicType, SUM(NumberOfAnnotations) as total_annotations, COUNT(*) as group_count FROM ann_group_index GROUP BY GraphicType ORDER BY total_annotations DESC )带源切片上下文的标注检索三级连接标注组 → 标注系列 → 被引用的源系列从而拿到集合归属与算法名client.sql_query( SELECT i.collection_id, g.GraphicType, g.AnnotationPropertyType_CodeMeaning, g.AlgorithmName, g.NumberOfAnnotations FROM ann_group_index g JOIN ann_index a ON g.SeriesInstanceUID a.SeriesInstanceUID JOIN index i ON a.referenced_SeriesInstanceUID i.SeriesInstanceUID WHERE g.AlgorithmName IS NOT NULL LIMIT 10 )全切片显微图像上的分割SEGDICOM SegmentationModality SEG同时服务放射CT 器官分割与病理WSI 组织区域分割。隔离病理分割的关键是用seg_index.segmented_SeriesInstanceUID找到源系列再按源的 Modality 过滤为SM# 找源为显微切片的分割 client.fetch_index(seg_index) client.fetch_index(sm_index) client.sql_query( SELECT seg.SeriesInstanceUID as seg_series, seg.AlgorithmName, seg.total_segments, src.collection_id, src.Modality as source_modality FROM seg_index seg JOIN index src ON seg.segmented_SeriesInstanceUID src.SeriesInstanceUID WHERE src.Modality SM LIMIT 20 )注意这里seg_index连接的是index源系列而不是sm_index——index_tables_guide.md 的连接键参考表明确index.SeriesInstanceUID seg_index.segmented_SeriesInstanceUID。sm_index的 fetch 是为后续需要切片级属性分辨率、物镜时再连接做准备。查找预计算分析结果Analysis ResultsIDC 托管派生数据集——核分割、TIL肿瘤浸润淋巴细胞图、AI 标注——在主index表中以analysis_result_id标识。analysis_results_index表用于发现病理方向上有哪些现成结果可用from idc_index import IDCClient client IDCClient() client.fetch_index(analysis_results_index) # 找包含病理标注或分割的分析结果 client.sql_query( SELECT ar.analysis_result_id, ar.analysis_result_title, ar.modalities, ar.subjects, ar.collections FROM analysis_results_index ar WHERE ar.modalities LIKE %ANN% OR ar.modalities LIKE %SEG% ORDER BY ar.subjects DESC )区分两个 ID 的职责主技能文档 IDC Data Model 一节的定义collection_id定位原始影像数据其中可能自带入库时的标注analysis_result_id定位跨一个或多个原始集合的派生对象。找 AI/专家生成的标注用后者。为特定切片找全部派生数据# 找 TCGA-BRCA 切片的全部派生数据标注、分割 client.fetch_index(ann_index) client.sql_query( SELECT i.analysis_result_id, i.PatientID, a.referenced_SeriesInstanceUID as source_slide, g.AnnotationGroupLabel, g.NumberOfAnnotations, g.AlgorithmName FROM ann_group_index g JOIN ann_index a ON g.SeriesInstanceUID a.SeriesInstanceUID JOIN index i ON a.SeriesInstanceUID i.SeriesInstanceUID WHERE i.collection_id tcga_brca LIMIT 10 )索引表之外的测量值标注对象内还可携带逐条标注的测量如核面积、偏心率它们存在于 DICOM 文件内部而不在索引表中。指南给出的处理方式是下载后用 IDC 官方维护的 highdicom 库提取调用链为ann.get_annotation_groups()→group.get_measurements()。原指南同时指向了 IDC-Tutorials 中的microscopy_dicom_ann_intro教程含空间分析与细胞密度计算的完整示例——该教程位于仓库外部这里仅说明这条提取路径存在具体 API 以 highdicom 官方文档为准。按 AnnotationGroupLabel 过滤AnnotationGroupLabel是按名称或语义内容找标注组最直接的列用LIKE通配做文本检索配合LOWER()做大小写不敏感匹配简单标签过滤# 按标签找标注组如包含 blast 的组 client.fetch_index(ann_group_index) client.sql_query( SELECT g.SeriesInstanceUID, g.AnnotationGroupLabel, g.GraphicType, g.NumberOfAnnotations, g.AlgorithmName FROM ann_group_index g WHERE LOWER(g.AnnotationGroupLabel) LIKE %blast% ORDER BY g.NumberOfAnnotations DESC )带集合上下文的标签过滤# 在特定集合内按标签找标注组 client.fetch_index(ann_index) client.fetch_index(ann_group_index) client.sql_query( SELECT i.collection_id, g.AnnotationGroupLabel, g.GraphicType, g.NumberOfAnnotations, g.AnnotationPropertyType_CodeMeaning FROM ann_group_index g JOIN ann_index a ON g.SeriesInstanceUID a.SeriesInstanceUID JOIN index i ON a.SeriesInstanceUID i.SeriesInstanceUID WHERE i.collection_id your_collection_id AND LOWER(g.AnnotationGroupLabel) LIKE %keyword% ORDER BY g.NumberOfAnnotations DESC )这个模式与 references/sql_patterns.md 中 Query Slide Microscopy and Annotation Data 一节的示例相互印证——该文档把更完整的 SM 查询、ANN 过滤、SMANN 交叉引用统一指向本篇指南可见本篇是技能包内病理 SQL 模式的权威落点。SM ANN 交叉引用要找显微切片数据上有哪些标注需要 SM 与 ANN 两张表同时参与。连接枢纽仍是ann_index.referenced_SeriesInstanceUID只不过这一次把它接到sm_index而非index上从而直接携带源切片的物镜信息# 找集合中显微切片及其标注 client.fetch_index(sm_index) client.fetch_index(ann_index) client.fetch_index(ann_group_index) client.sql_query( SELECT i.collection_id, s.ObjectiveLensPower, g.AnnotationGroupLabel, g.NumberOfAnnotations, g.GraphicType FROM ann_group_index g JOIN ann_index a ON g.SeriesInstanceUID a.SeriesInstanceUID JOIN sm_index s ON a.referenced_SeriesInstanceUID s.SeriesInstanceUID JOIN index i ON a.SeriesInstanceUID i.SeriesInstanceUID WHERE i.collection_id your_collection_id ORDER BY g.NumberOfAnnotations DESC )注意两个 JOIN 的语义区别JOIN sm_index s ON a.referenced_SeriesInstanceUID s.SeriesInstanceUID走的是引用方向标注 → 被标注的原图而JOIN index i ON a.SeriesInstanceUID i.SeriesInstanceUID走的是标注系列自身的归属用于取collection_id。混用这两个键是此类查询最常见的错误。Join 模式速查原指南给出的两个基础连接模式SM 连接切片显微细节 集合上下文client.fetch_index(sm_index) result client.sql_query( SELECT i.collection_id, i.PatientID, s.ObjectiveLensPower, s.min_PixelSpacing_2sf FROM index i JOIN sm_index s ON i.SeriesInstanceUID s.SeriesInstanceUID LIMIT 10 )ANN 连接标注组 集合上下文client.fetch_index(ann_index) client.fetch_index(ann_group_index) result client.sql_query( SELECT i.collection_id, g.AnnotationGroupLabel, g.GraphicType, g.NumberOfAnnotations, a.referenced_SeriesInstanceUID as source_series FROM ann_group_index g JOIN ann_index a ON g.SeriesInstanceUID a.SeriesInstanceUID JOIN index i ON a.SeriesInstanceUID i.SeriesInstanceUID LIMIT 10 )配套工具生态原指南末尾列出与数字病理工作流配套、基于 DICOM 格式的工具链按用途分三类工具名保留供读者自行检索其官方仓库Python 库highdicomIDC 官方开发高层 DICOM 抽象用于创建和读取 DICOM SegmentationSEG、Structured ReportSR与 parametric map覆盖病理与放射场景也是提取前文提到的逐条标注测量的推荐路径。wsidicom读取 DICOM WSI 数据集的 Python 包把元数据解析为易用的 dataclass面向全切片图像分析。TIA-Toolbox端到端计算病理库通过DICOMWSIReader支持 DICOM提供 tile 提取、特征提取与预训练深度学习模型。EZ-WSI-DICOMweb通过 DICOMweb 从 DICOM 全切片图像中抽取图像块面向云 DICOM 存储的 AI/ML 工作流。查看器SlimIDC 开发基于 Web 的 DICOM 显微切片查看器与标注工具通过 DICOMweb 支持明场与多重免疫荧光成像。主技能文档也提到client.get_viewer_URL()对 SM 系列会自动路由到 SLIM。QuPath跨平台开源全切片图像分析软件经 Bio-Formats 与 OpenSlidev0.4.0 起支持 DICOM WSI主技能文档的故障排查一节同样把 QuPath 列为病理 DICOM 打不开时的备选查看器。格式转换dicom_wsi将专有 WSI 格式转换为符合 DICOM 规范的文件的 Python 实现。实践清单与排错要点综合本篇与技能包其余文档数字病理会话的标准实践是先验版本check_version.py通过 client.get_idc_version()返回v24再开始查询先 fetch 后查询sm_index、sm_instance_index、seg_index、ann_index、ann_group_index、analysis_results_index全部需要client.fetch_index(...)前置先查 schema 后写 SQL用client.indices_overview核对列名病理列名如staining_usingSubstance_CodeMeaning带 CodeMeaning 后缀且可能是数组类型先小后大探索期一律LIMIT确认集合规模再考虑下载——主技能文档提醒部分集合以 TB 计区分连接方向referenced_SeriesInstanceUID/segmented_SeriesInstanceUID指向源系列SeriesInstanceUID自身连接指向对象自身的归属打不开下载文件时主技能文档的 Troubleshooting 建议先检查Modality与SOPClassUID用pydicom.dcmread(file, forceTrue)验证SEG、RTSTRUCT、SR 与显微切片都需要专用工具3D Slicer、QuPath 等而非普通放射查看器。需要完整索引表清单、临床数据连接或下载工作流时可继续参阅 index_tables_guide.md、sql_patterns.md、cli_guide.md 与 use_cases.md——它们与本篇指南同属 skills/imaging-data-commons/ 技能包按主文档 Quick Navigation 表的触发条件按需加载即可。【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Scientific Agent Skills：IDC 数字病理数据查询实战指南（SM / ANN / SEG 索引表与 SQL 模式）
Scientific Agent SkillsIDC 数字病理数据查询实战指南SM / ANN / SEG 索引表与 SQL 模式【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills本篇围绕 NCI 影像数据共同体Imaging Data CommonsIDC中的数字病理数据讲解如何用idc-index客户端的本地 DuckDB 索引表对全切片显微图像Slide MicroscopySM、显微批量简单标注Microscopy Bulk Simple AnnotationsANN与病理分割SEG做元数据发现、肿瘤/正常组织区分和预计算分析结果的检索。读完后你将能够脱离 BigQuery直接对 IDC v24 数据版本执行病理相关的 SQL 查询并掌握从索引发现到下载、测量提取的完整工作流。以下内容继承自技能包中的数字病理参考文档 skills/imaging-data-commons/references/digital_pathology_guide.md并结合本仓库 skills/imaging-data-commons/SKILL.md 的索引表总览与 scripts/check_version.py 的版本校验逻辑进行了扩充说明。版本基线idc-index 0.12.5 与 IDC 数据版本 v24原指南在开头明确标注Tested with: idc-index 0.12.5IDC 数据 version v24。这是一个必须重视的前提——所有查询列名如min_PixelSpacing_2sf、primaryAnatomicStructureModifier_CodeMeaning和示例结果如 TCGA-BRCA 的幻灯片计数都以该版本为准版本升级后列结构可能变化。仓库中这一版本约束有双重佐证skills/imaging-data-commons/SKILL.md 的 frontmatter 元数据中固定了idc-index: 0.12.5与idc-data-version: v24scripts/check_version.py 中MIN_VERSION 0.12.5、SKILL_VERSION 1.8.1脚本本身从不执行安装仅在版本不满足时打印面向当前解释器的安装命令并以非零码退出把环境选择权留给调用者。因此开始数字病理查询前的标准动作是# 在技能包根目录运行校验 idc-index 是否安装且版本不低于 0.12.5 python skills/imaging-data-commons/scripts/check_version.py会话内则用客户端确认数据版本from idc_index import IDCClient client IDCClient() # 校验 IDC 数据版本应为 v24 print(fIDC data version: {client.get_idc_version()})对于通用查询与下载非病理专属主技能文档 SKILL.md 提供了完整的路由规则MCP / REST / 本地索引三选一本篇只聚焦其中的病理分支SM、ANN、SEG 三类对象。五张病理专用索引表数字病理的核心是五张专门化的索引表。它们携带人工整理的curated元数据无需 BigQuery即可完成绝大多数发现工作表行粒度说明sm_index1 行 1 个 SM 系列全切片显微系列元数据容器/玻片 ID、组织类型、解剖结构、诊断、物镜倍数、像素间距、图像尺寸sm_instance_index1 行 1 个 SM 实例单张切片图像的实例级SOPInstanceUID元数据seg_index1 行 1 个 SEG 系列DICOM 分割元数据算法名、segment 数量、源系列引用。放射与病理共用——需按源 Modality 过滤出病理分割ann_index1 行 1 个 ANN 系列显微批量简单标注系列元数据含referenced_SeriesInstanceUID指向被标注的切片ann_group_index1 行 1 个标注组标注组细节AnnotationGroupLabel、GraphicType、NumberOfAnnotations、AlgorithmName、属性编码这些表与本仓库 references/index_tables_guide.md 中的完整索引表清单一致该文档的Join Column Reference小节还给出了一致性更强的连接键约定与病理相关的四条是表 A表 B连接条件indexsm_indexindex.SeriesInstanceUID sm_index.SeriesInstanceUIDindexseg_indexindex.SeriesInstanceUID seg_index.segmented_SeriesInstanceUIDindexann_indexindex.SeriesInstanceUID ann_index.SeriesInstanceUID取标注系列自身ann_index.referenced_SeriesInstanceUID index.SeriesInstanceUID取被标注的源系列ann_indexann_group_indexann_index.SeriesInstanceUID ann_group_index.SeriesInstanceUID两条硬性规则贯穿所有后续示例查询任何索引表之前先client.fetch_index(table_name)。该调用对所有表包括启动时自动加载的都安全且幂等。写 SQL 前先查 schema用client.indices_overview程序化检查列名与类型或client.get_index_schema(table)读取缓存的元数据。不要凭记忆假设列名——这是 IDC 查询返回空结果的第一大原因主技能文档在 Discovery 一节反复强调同一模式先枚举值再过滤。Slide MicroscopySM查询基本 SM 元数据sm_index是病理元数据最丰富的表。下面按集合统计切片数量与最高分辨率min_PixelSpacing_2sf保留两位小数的最小像素间距间距越小分辨率越高from idc_index import IDCClient client IDCClient() # sm_index 元数据详尽与 index 连接可取 collection_id client.fetch_index(sm_index) client.sql_query( SELECT i.collection_id, COUNT(*) as slides, MIN(s.min_PixelSpacing_2sf) as min_resolution FROM sm_index s JOIN index i ON s.SeriesInstanceUID i.SeriesInstanceUID GROUP BY i.collection_id ORDER BY slides DESC )按物镜倍数找高分辨率系列ObjectiveLensPower记录物镜倍率。找 40 倍及以上、按分辨率排序的高清切片client.fetch_index(sm_index) client.sql_query( SELECT i.collection_id, i.PatientID, s.ObjectiveLensPower, s.min_PixelSpacing_2sf FROM sm_index s JOIN index i ON s.SeriesInstanceUID i.SeriesInstanceUID WHERE s.ObjectiveLensPower 40 ORDER BY s.min_PixelSpacing_2sf LIMIT 20 )按标本制备方式过滤染色 / 包埋 / 固定sm_index包含染色staining、包埋介质embedding、固定液fixative三类元数据。注意这些列是数组类型——例如 HE 切片会是[hematoxylin stain, water soluble eosin stain]因此过滤要用array_to_string()配LIKE或用list_contains()直接对数组列做等值匹配会漏掉多值行# 在指定集合中找 HE 染色切片 client.fetch_index(sm_index) client.sql_query( SELECT i.PatientID, s.staining_usingSubstance_CodeMeaning as staining, s.embeddingMedium_CodeMeaning as embedding, s.tissueFixative_CodeMeaning as fixative FROM sm_index s JOIN index i ON s.SeriesInstanceUID i.SeriesInstanceUID WHERE i.collection_id tcga_brca AND array_to_string(s.staining_usingSubstance_CodeMeaning, , ) LIKE %hematoxylin% LIMIT 10 )跨集合比较 FFPE 石蜡切片与冷冻切片client.sql_query( SELECT i.collection_id, s.embeddingMedium_CodeMeaning as embedding, COUNT(*) as slide_count FROM sm_index s JOIN index i ON s.SeriesInstanceUID i.SeriesInstanceUID GROUP BY i.collection_id, embedding ORDER BY i.collection_id, slide_count DESC )区分肿瘤与正常切片sm_index提供了两条互补的组织类型识别路径列适用场景primaryAnatomicStructureModifier_CodeMeaning来自 DICOM 标本元数据的结构化组织类型如Neoplasm, Primary、Normal、Tumor、Neoplasm, Metastatic。在所有含 SM 数据的集合上通用。ContainerIdentifier切片/容器标识。TCGA 集合中该字段是 TCGA 条形码其中第 14–15 位的样本类型码编码组织来源01–09 肿瘤10–19 正常。两条路径各有所长结构化元数据跨集合通用但可能为 NULL条形码方法仅适用于 TCGA 集合却能兜底结构化元数据缺失的情况。路径一结构化组织类型元数据先枚举全库组织类型取值再按集合统计。以下结果基于 idc-index 0.12.5 / IDC v24 数据from idc_index import IDCClient client IDCClient() client.fetch_index(sm_index) # 发现所有 SM 数据中的组织类型取值 client.sql_query( SELECT s.primaryAnatomicStructureModifier_CodeMeaning as tissue_type, COUNT(*) as slide_count FROM sm_index s WHERE s.primaryAnatomicStructureModifier_CodeMeaning IS NOT NULL GROUP BY tissue_type ORDER BY slide_count DESC )以 TCGA-BRCA 为例# TCGA-BRCA 的组织类型分布 client.sql_query( SELECT s.primaryAnatomicStructureModifier_CodeMeaning as tissue_type, COUNT(*) as slide_count, COUNT(DISTINCT i.PatientID) as patient_count FROM sm_index s JOIN index i ON s.SeriesInstanceUID i.SeriesInstanceUID WHERE i.collection_id tcga_brca GROUP BY tissue_type ORDER BY slide_count DESC ) # 指南记录的结果Neoplasm, Primary2704 张、Normal399 张路径二TCGA 条形码仅限 TCGA 集合TCGA 集合中ContainerIdentifier即切片条形码如TCGA-E9-A3X8-01A-03-TSC第 4 段的前两位就是样本类型码# 从 TCGA 条形码解析样本类型码 client.sql_query( SELECT SUBSTRING(SPLIT_PART(s.ContainerIdentifier, -, 4), 1, 2) as sample_type_code, s.primaryAnatomicStructureModifier_CodeMeaning as tissue_type, COUNT(*) as slide_count FROM sm_index s JOIN index i ON s.SeriesInstanceUID i.SeriesInstanceUID WHERE i.collection_id tcga_brca GROUP BY sample_type_code, tissue_type ORDER BY sample_type_code ) # 指南记录的结果01 → Neoplasm, Primary270406 → None811 → Normal399条形码方法的价值在最后一行数据上类型码06转移灶对应的 8 张切片在 TCGA-BRCA 中primaryAnatomicStructureModifier_CodeMeaning为 NULL——只依赖结构化元数据的查询会静默丢掉这些切片。实践建议是两条路径并用用条形码兜底 NULL 情况。标注ANN查询DICOM Microscopy Bulk Simple AnnotationsModality ANN是画在显微切片图像之上的标注对象。它们分两级出现在索引中ann_index系列级与ann_group_index标注组级。每个 ANN 系列通过referenced_SeriesInstanceUID指向它标注的那张切片——这是做标注 ↔ 原图关联的唯一桥梁。基础标注发现# 找标注系列及其引用的原图系列 client.fetch_index(ann_index) client.fetch_index(ann_group_index) client.sql_query( SELECT a.SeriesInstanceUID as ann_series, a.AnnotationCoordinateType, a.referenced_SeriesInstanceUID as source_series FROM ann_index a LIMIT 10 )标注组统计按图形类型汇总标注总量点、线、多边形等client.sql_query( SELECT GraphicType, SUM(NumberOfAnnotations) as total_annotations, COUNT(*) as group_count FROM ann_group_index GROUP BY GraphicType ORDER BY total_annotations DESC )带源切片上下文的标注检索三级连接标注组 → 标注系列 → 被引用的源系列从而拿到集合归属与算法名client.sql_query( SELECT i.collection_id, g.GraphicType, g.AnnotationPropertyType_CodeMeaning, g.AlgorithmName, g.NumberOfAnnotations FROM ann_group_index g JOIN ann_index a ON g.SeriesInstanceUID a.SeriesInstanceUID JOIN index i ON a.referenced_SeriesInstanceUID i.SeriesInstanceUID WHERE g.AlgorithmName IS NOT NULL LIMIT 10 )全切片显微图像上的分割SEGDICOM SegmentationModality SEG同时服务放射CT 器官分割与病理WSI 组织区域分割。隔离病理分割的关键是用seg_index.segmented_SeriesInstanceUID找到源系列再按源的 Modality 过滤为SM# 找源为显微切片的分割 client.fetch_index(seg_index) client.fetch_index(sm_index) client.sql_query( SELECT seg.SeriesInstanceUID as seg_series, seg.AlgorithmName, seg.total_segments, src.collection_id, src.Modality as source_modality FROM seg_index seg JOIN index src ON seg.segmented_SeriesInstanceUID src.SeriesInstanceUID WHERE src.Modality SM LIMIT 20 )注意这里seg_index连接的是index源系列而不是sm_index——index_tables_guide.md 的连接键参考表明确index.SeriesInstanceUID seg_index.segmented_SeriesInstanceUID。sm_index的 fetch 是为后续需要切片级属性分辨率、物镜时再连接做准备。查找预计算分析结果Analysis ResultsIDC 托管派生数据集——核分割、TIL肿瘤浸润淋巴细胞图、AI 标注——在主index表中以analysis_result_id标识。analysis_results_index表用于发现病理方向上有哪些现成结果可用from idc_index import IDCClient client IDCClient() client.fetch_index(analysis_results_index) # 找包含病理标注或分割的分析结果 client.sql_query( SELECT ar.analysis_result_id, ar.analysis_result_title, ar.modalities, ar.subjects, ar.collections FROM analysis_results_index ar WHERE ar.modalities LIKE %ANN% OR ar.modalities LIKE %SEG% ORDER BY ar.subjects DESC )区分两个 ID 的职责主技能文档 IDC Data Model 一节的定义collection_id定位原始影像数据其中可能自带入库时的标注analysis_result_id定位跨一个或多个原始集合的派生对象。找 AI/专家生成的标注用后者。为特定切片找全部派生数据# 找 TCGA-BRCA 切片的全部派生数据标注、分割 client.fetch_index(ann_index) client.sql_query( SELECT i.analysis_result_id, i.PatientID, a.referenced_SeriesInstanceUID as source_slide, g.AnnotationGroupLabel, g.NumberOfAnnotations, g.AlgorithmName FROM ann_group_index g JOIN ann_index a ON g.SeriesInstanceUID a.SeriesInstanceUID JOIN index i ON a.SeriesInstanceUID i.SeriesInstanceUID WHERE i.collection_id tcga_brca LIMIT 10 )索引表之外的测量值标注对象内还可携带逐条标注的测量如核面积、偏心率它们存在于 DICOM 文件内部而不在索引表中。指南给出的处理方式是下载后用 IDC 官方维护的 highdicom 库提取调用链为ann.get_annotation_groups()→group.get_measurements()。原指南同时指向了 IDC-Tutorials 中的microscopy_dicom_ann_intro教程含空间分析与细胞密度计算的完整示例——该教程位于仓库外部这里仅说明这条提取路径存在具体 API 以 highdicom 官方文档为准。按 AnnotationGroupLabel 过滤AnnotationGroupLabel是按名称或语义内容找标注组最直接的列用LIKE通配做文本检索配合LOWER()做大小写不敏感匹配简单标签过滤# 按标签找标注组如包含 blast 的组 client.fetch_index(ann_group_index) client.sql_query( SELECT g.SeriesInstanceUID, g.AnnotationGroupLabel, g.GraphicType, g.NumberOfAnnotations, g.AlgorithmName FROM ann_group_index g WHERE LOWER(g.AnnotationGroupLabel) LIKE %blast% ORDER BY g.NumberOfAnnotations DESC )带集合上下文的标签过滤# 在特定集合内按标签找标注组 client.fetch_index(ann_index) client.fetch_index(ann_group_index) client.sql_query( SELECT i.collection_id, g.AnnotationGroupLabel, g.GraphicType, g.NumberOfAnnotations, g.AnnotationPropertyType_CodeMeaning FROM ann_group_index g JOIN ann_index a ON g.SeriesInstanceUID a.SeriesInstanceUID JOIN index i ON a.SeriesInstanceUID i.SeriesInstanceUID WHERE i.collection_id your_collection_id AND LOWER(g.AnnotationGroupLabel) LIKE %keyword% ORDER BY g.NumberOfAnnotations DESC )这个模式与 references/sql_patterns.md 中 Query Slide Microscopy and Annotation Data 一节的示例相互印证——该文档把更完整的 SM 查询、ANN 过滤、SMANN 交叉引用统一指向本篇指南可见本篇是技能包内病理 SQL 模式的权威落点。SM ANN 交叉引用要找显微切片数据上有哪些标注需要 SM 与 ANN 两张表同时参与。连接枢纽仍是ann_index.referenced_SeriesInstanceUID只不过这一次把它接到sm_index而非index上从而直接携带源切片的物镜信息# 找集合中显微切片及其标注 client.fetch_index(sm_index) client.fetch_index(ann_index) client.fetch_index(ann_group_index) client.sql_query( SELECT i.collection_id, s.ObjectiveLensPower, g.AnnotationGroupLabel, g.NumberOfAnnotations, g.GraphicType FROM ann_group_index g JOIN ann_index a ON g.SeriesInstanceUID a.SeriesInstanceUID JOIN sm_index s ON a.referenced_SeriesInstanceUID s.SeriesInstanceUID JOIN index i ON a.SeriesInstanceUID i.SeriesInstanceUID WHERE i.collection_id your_collection_id ORDER BY g.NumberOfAnnotations DESC )注意两个 JOIN 的语义区别JOIN sm_index s ON a.referenced_SeriesInstanceUID s.SeriesInstanceUID走的是引用方向标注 → 被标注的原图而JOIN index i ON a.SeriesInstanceUID i.SeriesInstanceUID走的是标注系列自身的归属用于取collection_id。混用这两个键是此类查询最常见的错误。Join 模式速查原指南给出的两个基础连接模式SM 连接切片显微细节 集合上下文client.fetch_index(sm_index) result client.sql_query( SELECT i.collection_id, i.PatientID, s.ObjectiveLensPower, s.min_PixelSpacing_2sf FROM index i JOIN sm_index s ON i.SeriesInstanceUID s.SeriesInstanceUID LIMIT 10 )ANN 连接标注组 集合上下文client.fetch_index(ann_index) client.fetch_index(ann_group_index) result client.sql_query( SELECT i.collection_id, g.AnnotationGroupLabel, g.GraphicType, g.NumberOfAnnotations, a.referenced_SeriesInstanceUID as source_series FROM ann_group_index g JOIN ann_index a ON g.SeriesInstanceUID a.SeriesInstanceUID JOIN index i ON a.SeriesInstanceUID i.SeriesInstanceUID LIMIT 10 )配套工具生态原指南末尾列出与数字病理工作流配套、基于 DICOM 格式的工具链按用途分三类工具名保留供读者自行检索其官方仓库Python 库highdicomIDC 官方开发高层 DICOM 抽象用于创建和读取 DICOM SegmentationSEG、Structured ReportSR与 parametric map覆盖病理与放射场景也是提取前文提到的逐条标注测量的推荐路径。wsidicom读取 DICOM WSI 数据集的 Python 包把元数据解析为易用的 dataclass面向全切片图像分析。TIA-Toolbox端到端计算病理库通过DICOMWSIReader支持 DICOM提供 tile 提取、特征提取与预训练深度学习模型。EZ-WSI-DICOMweb通过 DICOMweb 从 DICOM 全切片图像中抽取图像块面向云 DICOM 存储的 AI/ML 工作流。查看器SlimIDC 开发基于 Web 的 DICOM 显微切片查看器与标注工具通过 DICOMweb 支持明场与多重免疫荧光成像。主技能文档也提到client.get_viewer_URL()对 SM 系列会自动路由到 SLIM。QuPath跨平台开源全切片图像分析软件经 Bio-Formats 与 OpenSlidev0.4.0 起支持 DICOM WSI主技能文档的故障排查一节同样把 QuPath 列为病理 DICOM 打不开时的备选查看器。格式转换dicom_wsi将专有 WSI 格式转换为符合 DICOM 规范的文件的 Python 实现。实践清单与排错要点综合本篇与技能包其余文档数字病理会话的标准实践是先验版本check_version.py通过 client.get_idc_version()返回v24再开始查询先 fetch 后查询sm_index、sm_instance_index、seg_index、ann_index、ann_group_index、analysis_results_index全部需要client.fetch_index(...)前置先查 schema 后写 SQL用client.indices_overview核对列名病理列名如staining_usingSubstance_CodeMeaning带 CodeMeaning 后缀且可能是数组类型先小后大探索期一律LIMIT确认集合规模再考虑下载——主技能文档提醒部分集合以 TB 计区分连接方向referenced_SeriesInstanceUID/segmented_SeriesInstanceUID指向源系列SeriesInstanceUID自身连接指向对象自身的归属打不开下载文件时主技能文档的 Troubleshooting 建议先检查Modality与SOPClassUID用pydicom.dcmread(file, forceTrue)验证SEG、RTSTRUCT、SR 与显微切片都需要专用工具3D Slicer、QuPath 等而非普通放射查看器。需要完整索引表清单、临床数据连接或下载工作流时可继续参阅 index_tables_guide.md、sql_patterns.md、cli_guide.md 与 use_cases.md——它们与本篇指南同属 skills/imaging-data-commons/ 技能包按主文档 Quick Navigation 表的触发条件按需加载即可。【免费下载链接】scientific-agent-skillsTurn any AI agent into an AI Scientist. The #1 Agent Skills library for science, used by 190,000 scientists worldwide. 165 ready-to-use validated skills plus 100 scientific databases covering biology, chemistry, medicine, and drug discovery. Compatible with Cursor, Claude Code, Codex, Pi, Antigravity, and the open Agent Skills standard.项目地址: https://gitcode.com/GitHub_Trending/cl/scientific-agent-skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考