alterlab-imaging-data-commons

Imaging Data Commons

概述

使用 idc-index Python 包查询并下载美国国家癌症研究所 Imaging Data Commons（IDC）的公开癌症影像数据。访问数据无需身份验证。

当前 IDC 数据版本：v24（请始终使用 IDCClient().get_idc_version() 验证）

主要工具： idc-index（GitHub）

请先检查已安装的包版本。 每次 IDC 数据发布都会推出新版本的 idc-index，因此旧版本安装会悄无声息地查询过时数据；此外，0.12.4 及更早版本会将 pandas 固定为 <=2.2.4，这与 pandas 3 冲突（0.12.5 将限制放宽为 pandas<4）。

from importlib.metadata import version as _v
from packaging.version import Version

REQUIRED_VERSION = "0.12.5"  # keep in sync with the compatibility field of this file
installed = _v("idc-index")

# Compare as versions, not strings ("0.9.0" < "0.11.0" is False as a string).
if Version(installed) < Version(REQUIRED_VERSION):
    print(f"idc-index {installed} is older than {REQUIRED_VERSION}; upgrade with:")
    print("    uv pip install --upgrade idc-index   # or: pip install --upgrade idc-index")
    print("Then restart Python to load the new version.")
else:
    print(f"idc-index {installed} meets requirement ({REQUIRED_VERSION})")

验证 IDC 数据版本并检查当前数据规模：

from idc_index import IDCClient
client = IDCClient()

# Verify IDC data version (should be "v24")
print(f"IDC data version: {client.get_idc_version()}")

# Get collection count and total series
stats = client.sql_query("""
    SELECT
        COUNT(DISTINCT collection_id) as collections,
        COUNT(DISTINCT analysis_result_id) as analysis_results,
        COUNT(DISTINCT PatientID) as patients,
        COUNT(DISTINCT StudyInstanceUID) as studies,
        COUNT(DISTINCT SeriesInstanceUID) as series,
        SUM(instanceCount) as instances,
        SUM(series_size_MB)/1000000 as size_TB
    FROM index
""")
print(stats)

核心工作流：

1. 查询元数据 → client.sql_query()
2. 下载 DICOM 文件 → client.download_from_selection()
3. 在浏览器中查看 → client.get_viewer_URL(seriesInstanceUID=...)

脚本

scripts/query_imaging_data_commons.py — idc-index 包的 CLI 封装（将 JSON 输出到 stdout；uv pip install --upgrade idc-index）：

python scripts/query_imaging_data_commons.py version                 # IDC data version
python scripts/query_imaging_data_commons.py collections --limit 50   # collections + counts
python scripts/query_imaging_data_commons.py sql "SELECT * FROM index LIMIT 5"   # raw SQL

何时使用此技能

• 查找公开可用的放射影像（CT、MR、PET）或病理影像（切片显微镜图像）
• 按癌症类型、成像模态、解剖部位或其他元数据筛选图像子集
• 从 IDC 下载 DICOM 数据
• 在研究或商业应用中使用前检查数据许可
• 无需本地 DICOM 查看器软件，即可在浏览器中查看医学图像

不适用场景

场景	改用
读取、匿名化或转换已有的 DICOM 文件	alterlab-pydicom
对本地切片进行全切片图像分块和组织检测	alterlab-histolab
TCGA 或其他癌症队列的体细胞突变／拷贝数	alterlab-cbioportal
癌症突变特征和普查基因	alterlab-cosmic

快速导航

核心章节（内联）：

• IDC 数据模型 — 集合与分析结果层级结构
• 索引表 — 可用表及其连接模式
• 安装 — 包设置和版本验证
• 核心功能 — 基本 API 用法（查询、下载、可视化、许可、引用、批处理）
• 最佳实践 — 使用指南
• 故障排除 — 常见问题及解决方案

参考指南（按需加载）：

指南	加载时机
core_api_examples.md	核心功能 §1-§9 的可运行代码（发现、SQL、下载、可视化、许可、批处理、BigQuery、流水线）
index_tables_guide.md	复杂 JOIN、模式发现、DataFrame 访问
use_cases.md	端到端工作流示例（训练数据集、批量下载）
sql_patterns.md	用于筛选条件发现、注释和大小估算的快捷 SQL 模式
clinical_data_guide.md	临床／表格数据、影像与临床数据连接、值映射
cloud_storage_guide.md	直接访问 S3/GCS、版本控制、UUID 映射
dicomweb_guide.md	DICOMweb 端点、PACS 集成
digital_pathology_guide.md	切片显微镜（SM）、注释（ANN）、病理工作流
bigquery_guide.md	完整 DICOM 元数据、私有元素（需要 GCP）
cli_guide.md	命令行工具（idc download、清单文件）

IDC 数据模型

IDC 在标准 DICOM 层级（患者 → 检查 → 序列 → 实例）之上增加了两个分组层级：

• collection_id：按疾病、成像方式或研究重点对患者分组（例如 tcga_luad、nlst）。每位患者恰好属于一个集合。
• analysis_result_id：标识一个或多个原始集合中的衍生对象（分割、注释、影像组学特征）。

使用 collection_id 查找原始成像数据，其中可能包含与图像一同提交的注释；使用 analysis_result_id 查找 AI 生成或专家注释。

查询的关键标识符：

标识符	范围	用途
collection_id	数据集分组	按项目／研究筛选
PatientID	患者	按患者对图像分组
StudyInstanceUID	DICOM 检查	对相关序列分组、可视化
SeriesInstanceUID	DICOM 序列	对相关序列分组、可视化

索引表

idc-index 包提供多个元数据索引表，可通过 SQL 访问，也可作为 pandas DataFrame 使用。

完整索引表文档： 使用 https://idc-index.readthedocs.io/en/latest/indices_reference.html 快速查看可用表和列，无需执行任何代码。

重要： 使用 client.indices_overview 获取当前表说明和列架构。这是可用列及其类型的权威来源——编写 SQL 或探索数据结构时，务必查询此信息。

可用表

表	行粒度	加载方式	说明
index	1 行 = 1 个 DICOM 序列	自动	所有当前 IDC 数据的主要元数据
prior_versions_index	1 行 = 1 个 DICOM 序列	自动	之前 IDC 版本中的序列；用于下载已弃用数据
collections_index	1 行 = 1 个集合	fetch_index()	集合级元数据和说明
analysis_results_index	1 行 = 1 个分析结果集合	fetch_index()	衍生数据集（注释、分割）的元数据
clinical_index	1 行 = 1 个临床数据列	fetch_index()	将临床表列映射到集合的字典
sm_index	1 行 = 1 个玻片显微镜序列	fetch_index()	玻片显微镜（病理学）序列元数据
sm_instance_index	1 行 = 1 个玻片显微镜实例	fetch_index()	玻片显微镜的实例级（SOPInstanceUID）元数据
seg_index	1 行 = 1 个 DICOM 分割序列	fetch_index()	分割元数据：算法、分段数量、对源图像序列的引用
ann_index	1 行 = 1 个 DICOM ANN 序列	fetch_index()	显微镜批量简单注释序列元数据；引用已标注的图像序列
ann_group_index	1 行 = 1 个注释组	fetch_index()	详细的注释组元数据：图形类型、注释数量、属性代码、算法
contrast_index	1 行 = 1 个含对比剂信息的序列	fetch_index()	对比剂元数据：药剂名称、成分、给药途径（CT、MR、PT、XA、RF）
ct_index / mr_index / pt_index	1 行 = 1 个 CT / MR / PET 图像序列	fetch_index()	特定成像方式的采集参数（例如 KVP、ConvolutionKernel；MagneticFieldStrength、EchoTime；Radiopharmaceutical、Units）
volume_geometry_index	1 行 = 1 个单帧 CT/MR/PT 序列	fetch_index()	检查是否为规则间隔的 3D 体积的布尔值（regularly_spaced_3d_volume、方向、间距）——构建体积前先筛选
rtstruct_index	1 行 = 1 个 RTSTRUCT 序列	fetch_index()	ROI 名称／数量、生成算法、referenced_SeriesInstanceUID
version_metadata_index	1 行 = 1 个 IDC 版本	自动	每个 idc_version 的发布时间戳

自动 = 实例化 IDCClient() 时自动加载 fetch_index() = 需要调用 client.fetch_index("table_name") 加载

连接表

关键列未明确标注，以下列是可用于连接的部分列。

连接列	表	使用场景
collection_id	index, prior_versions_index, collections_index, clinical_index	将序列与集合元数据或临床数据关联
SeriesInstanceUID	index, prior_versions_index, sm_index, sm_instance_index	跨表关联序列；连接到切片显微镜详情
StudyInstanceUID	index, prior_versions_index	关联当前数据和历史数据中的研究
PatientID	index, prior_versions_index	关联当前数据和历史数据中的患者
analysis_result_id	index, analysis_results_index	将序列与分析结果元数据（注释、分割）关联
source_DOI	index, analysis_results_index	根据出版物 DOI 关联
crdc_series_uuid	index, prior_versions_index	根据 CRDC 唯一标识符关联
Modality	index, prior_versions_index	按成像模态筛选
SeriesInstanceUID	index, seg_index, ann_index, ann_group_index, contrast_index	将分割／注释／对比序列与其索引元数据关联
segmented_SeriesInstanceUID	seg_index → index	将分割与其源图像序列关联（连接条件：seg_index.segmented_SeriesInstanceUID = index.SeriesInstanceUID）
referenced_SeriesInstanceUID	ann_index → index	将注释与其源图像序列关联（连接条件：ann_index.referenced_SeriesInstanceUID = index.SeriesInstanceUID）

注意：Subjects、Updated 和 Description 会出现在多个表中，但含义各不相同（计数与标识符、不同的更新上下文）。

有关详细的连接示例、架构发现模式、关键列参考和 DataFrame 访问，请参阅 references/index_tables_guide.md。

临床数据访问

# Fetch clinical index (also downloads clinical data tables)
client.fetch_index("clinical_index")

# Query clinical index to find available tables and their columns
tables = client.sql_query("SELECT DISTINCT table_name, column_label FROM clinical_index")

# Load a specific clinical table as DataFrame
clinical_df = client.get_clinical_table("table_name")

有关详细工作流，包括值映射模式以及将临床数据与成像数据连接的方法，请参阅 references/clinical_data_guide.md。

数据访问选项

方法	需要身份验证	最适合
idc-index	否	关键查询和下载（推荐）
IDC Portal	否	交互式探索、手动选择、基于浏览器的下载
BigQuery	是（GCP 账号）	复杂查询、完整 DICOM 元数据
DICOMweb proxy	否	通过 DICOMweb API 集成工具
云存储（S3/GCS）	否	直接访问文件、批量下载、自定义流水线

云存储组织方式

IDC 将所有 DICOM 文件存储在公共云存储桶中，并在 AWS S3 和 Google Cloud Storage 之间进行镜像。文件按 CRDC UUID（而非 DICOM UID）组织，以支持版本管理。

存储桶（AWS / GCS）	许可	内容
idc-open-data / idc-open-data	无商业限制	>90% 的 IDC 数据
idc-open-data-two / idc-open-idc1	无商业限制	可能包含头部扫描的集合
idc-open-data-cr / idc-open-cr	限制商业用途（CC BY-NC）	约 4% 的数据

文件以 <crdc_series_uuid>/<crdc_instance_uuid>.dcm 的形式存储。通过 AWS CLI、gsutil 或 s5cmd 使用匿名访问即可免费访问（无需出口流量费）。S3 URL 使用索引中的 series_aws_url 列；GCS 使用相同的路径结构。

有关存储桶详情、访问命令、UUID 映射和版本管理，请参阅 references/cloud_storage_guide.md。

DICOMweb 访问

IDC 数据可通过 DICOMweb 接口（Google Cloud Healthcare API 实现）访问，适用于与 PACS 系统和兼容 DICOMweb 的工具集成。

端点	身份验证	使用场景
公共代理	否	测试、适量查询、每日配额
Google Healthcare	是（GCP）	生产环境使用、更高配额

有关端点 URL、代码示例、支持的操作和实现详情，请参阅 references/dicomweb_guide.md。

安装和设置

必需（用于基本访问）：

uv pip install --upgrade idc-index   # or: pip install --upgrade idc-index

重要： IDC 发布新数据时，始终会推出新版本的 idc-index。安装时始终使用 --upgrade 标志，除非为了保证可复现性而需要使用旧版本。

截至 2026-09，当前 IDC 数据版本为 v24。请在会话开始时确认你的版本：

print(client.get_idc_version())  # "v24"

如果看到的是旧版本，请使用以下命令升级：uv pip install --upgrade idc-index

已测试： idc-index 0.12.5 与 pandas 3.0（IDC 数据版本 v24）；参考文件基于 0.12.3 编写，使用相同的数据发布版本。

可选（用于数据分析）：

uv pip install pandas numpy pydicom

核心功能

以下各项功能的可运行 Python/SQL/CLI 示例均位于 references/core_api_examples.md（编号 §1-§9，与此处标题对应）。 需要可复制粘贴的代码时，请加载该文件；此处的概要介绍了路由方式和关键决策。所有示例均假设已执行 from idc_index import IDCClient; client = IDCClient()。

1. 数据发现和探索

查找可用的集合和衍生数据集：

• 汇总主索引 index（每个 collection_id 的患者数、序列数和大小）。
• fetch_index 后的 collections_index 提供整理好的集合级元数据 （CancerTypes、TumorLocations、Species、Subjects），无需汇总。
• analysis_results_index 列出衍生数据集（AI 分割、专家注释、影像组学），以及其来源集合和模态。

示例见 core_api_examples.md §1。

2. 使用 SQL 查询元数据

分两步进行：先探索筛选值（SELECT DISTINCT Modality …、 BodyPartExamined …），再使用经验证的值进行查询。将结果作为 pandas DataFrame 访问。若要按癌症类型筛选，请将 index 与 collections_index 进行 JOIN（癌症类型位于 collections_index.CancerTypes，而非主 index）。使用 client.indices_overview 查看完整的列清单。示例见 core_api_examples.md §2。

3. 下载 DICOM 文件

使用 client.download_from_selection(...)，按 collection_id 或 seriesInstanceUID 下载，并指定 downloadDir 和可选的 dirTemplate（默认值为 %collection_id/%PatientID/%StudyInstanceUID/%Modality_%SeriesInstanceUID；设为 "" 可使用平铺目录结构）。文件名采用 CRDC 实例 UUID（<uuid>.dcm），而非 DICOM UID。idc download CLI 提供相同功能，并可自动检测标识符与 清单文件。示例、CLI 选项和清单格式见 core_api_examples.md §3； 更详细的 CLI 说明见 references/cli_guide.md。

4. 可视化 IDC 图像

client.get_viewer_URL(seriesInstanceUID=...)（多序列检查可使用 studyInstanceUID=...）会返回浏览器 URL，无需下载。该方法会自动为放射学图像选择 OHIF v3，为切片显微镜图像选择 SLIM。示例见 core_api_examples.md §4。

5. 了解和检查许可证

使用前请先查询 license_short_name。CC BY 4.0/3.0（约 97%）允许 商业用途，但需注明出处；CC BY-NC 4.0/3.0（约 3%）仅限非商业用途； 少数数据使用自定义许可证。注明出处时，citations_from_selection() 会根据 source_DOI 生成格式化引文（默认使用 APA；也支持通过 IDCClient.CITATION_FORMAT_* 生成 BibTeX、JSON、Turtle 格式）。示例见 core_api_examples.md §5。

6. 批量处理和筛选

使用筛选条件查询 → 保存为清单 CSV → 分批下载（例如，每次下载 10 个序列），以避免超时。示例见 core_api_examples.md §6。

7. 使用 BigQuery 进行高级查询

仅在需要完整 DICOM 元数据、复杂 JOIN 或私有 DICOM 元素（OtherElements）时使用 BigQuery。首先检查专用索引 （seg_index、ann_index/ann_group_index、sm_index、 collections_index）中是否已有所需字段；本地 sql_query 免费且无需 GCP 账户。 数据集为 bigquery-public-data.idc_current.*，主表为 dicom_all。参见 references/bigquery_guide.md；快速参考见 core_api_examples.md §7。

8. 工具选择指南

任务	工具	参考
以编程方式查询和下载	idc-index	本文档
交互式探索	IDC Portal	https://portal.imaging.datacommons.cancer.gov/
复杂元数据查询	BigQuery	references/bigquery_guide.md
3D 可视化与分析	SlicerIDCBrowser	https://github.com/ImagingDataCommons/SlicerIDCBrowser

默认选择： 大多数任务使用 idc-index（无需身份验证、API 简单、支持批量下载）。

9. 与分析管道集成

下载后，使用 pydicom 读取 DICOM，按 ImagePositionPatient[2] 排序并堆叠 pixel_array 来构建 3D 体数据；也可以使用 SimpleITK.ImageSeriesReader 读取序列，以进行处理并导出 NIfTI。参见 core_api_examples.md §9 中的示例。

常见用例

完整的端到端工作流示例请参阅 references/use_cases.md，包括：

• 从肺部 CT 扫描构建深度学习训练数据集
• 比较不同扫描仪制造商的图像质量
• 下载前在浏览器中预览数据
• 符合许可要求的商业用途批量下载

最佳实践

• 生成响应前验证 IDC 版本 - 每次会话开始时，务必调用 client.get_idc_version()，确认使用的是预期的数据版本（当前为 v24）。如果使用的是较旧版本，建议运行 uv pip install --upgrade idc-index
• 使用前检查许可 - 务必查询 license_short_name 字段，并遵守许可条款（CC BY 与 CC BY-NC）
• 生成引用以注明出处 - 使用 citations_from_selection() 根据 source_DOI 值生成格式规范的引用；在出版物中包含这些引用
• 从小型查询开始 - 探索时使用 LIMIT 子句，以避免长时间下载并了解数据结构
• 简单查询使用 mini-index - 仅在需要全面的元数据或复杂 JOIN 时使用 BigQuery
• 使用 dirTemplate 整理下载文件 - 使用有意义的目录结构，例如 %collection_id/%PatientID/%Modality
• 缓存查询结果 - 将 DataFrame 保存为 CSV 文件，以避免重复查询并确保可复现性
• 先估算大小 - 下载前检查数据集大小——有些数据集的大小以 TB 计！
• 保存清单 - 务必保存包含 Series UID 的查询结果，以确保可复现性并记录数据来源
• 阅读文档 - IDC 数据结构和元数据字段的文档见 https://learn.canceridc.dev/
• 使用 IDC 论坛 - 在 https://discourse.canceridc.dev/ 搜索问题及解答，并向 IDC 维护者和用户提问

故障排查

问题：ModuleNotFoundError: No module named 'idc_index'

• 原因： 未安装 idc-index 软件包
• 解决方案： 使用 uv pip install --upgrade idc-index 安装

问题：依赖解析器拒绝在 pandas 3 环境中安装 idc-index

• 原因： idc-index ≤ 0.12.4 固定要求 pandas<=2.2.4
• 解决方案： 升级到 idc-index ≥ 0.12.5

问题：下载因连接超时而失败

• 原因： 网络不稳定或下载量过大
• 解决方案：
  • 分批下载较小的数据（例如，每次下载 10-20 个序列）
  • 检查网络连接
  • 使用 dirTemplate 按批次整理下载内容
  • 实现带延迟的重试逻辑

问题：BigQuery quota exceeded 或账单错误

• 原因： BigQuery 要求使用已启用结算功能的 GCP 项目
• 解决方案： 对于简单查询，请使用 idc-index mini-index（无需结算）；或者参阅 references/bigquery_guide.md，了解费用优化建议

问题：找不到序列 UID 或未返回数据

• 原因： UID 拼写错误、当前 IDC 版本中没有该数据，或字段名称错误
• 解决方案：
  • 检查当前 IDC 版本中是否有该数据（某些旧数据可能已弃用）
  • 先使用 LIMIT 5 测试查询
  • 对照元数据架构文档检查字段名称

问题：下载的 DICOM 文件无法打开

• 原因： 下载文件损坏或查看器不兼容
• 解决方案：
  • 检查 DICOM 对象类型（Modality 和 SOPClassUID 属性）——某些对象类型需要专用工具
  • 验证文件完整性（检查文件大小）
  • 使用 pydicom 验证：pydicom.dcmread(file, force=True)
  • 尝试其他 DICOM 查看器（3D Slicer、Horos、RadiAnt、QuPath）
  • 重新下载该序列

常见 SQL 查询模式

请参阅 references/sql_patterns.md，了解快速参考 SQL 模式，包括：

• 筛选值发现（成像模态、身体部位、制造商）
• 注释和分割查询（包括 seg_index、ann_index 连接）
• 玻片显微镜查询（sm_index 模式）
• 下载大小估算
• 临床数据关联

有关分割和注释的详细信息，也请参阅 references/digital_pathology_guide.md。

相关技能

以下技能可配合 IDC 工作流，用于下游分析和可视化：

DICOM 处理

• alterlab-pydicom —— 读取、写入和处理下载的 DICOM 文件。可用于提取像素数据、读取元数据、匿名化和格式转换。处理 IDC 放射学数据（CT、MR、PET）时必不可少。

病理学与玻片显微镜

请参阅 references/digital_pathology_guide.md，了解兼容 DICOM 的工具（highdicom、wsidicom、TIA-Toolbox、Slim viewer）。

元数据可视化

• alterlab-matplotlib —— 用于完全自定义的底层绘图。可用于创建静态图表，总结 IDC 查询结果（模态柱状图、序列数量直方图等）。
• alterlab-seaborn —— 与 pandas 集成的统计可视化工具。可用于快速探索 IDC 元数据分布、变量之间的关系和类别对比，并提供美观的默认样式。
• alterlab-plotly —— 交互式可视化工具。需要通过悬停信息、缩放和平移来探索 IDC 元数据，或创建可嵌入网页的集合统计仪表板时可使用。

数据探索

• alterlab-eda —— 用于科学数据文件的全面 EDA。下载 IDC 数据后，可在分析前了解文件结构、质量和特征。

资源

架构参考（主要来源）

请始终使用 client.indices_overview 获取当前列架构。 这能确保信息与已安装的 idc-index 版本一致：

# Get all column names and types for any table
schema = client.indices_overview["index"]["schema"]
columns = [(c['name'], c['type'], c.get('description', '')) for c in schema['columns']]

参考文档

请参阅顶部的“快速导航”部分，查看参考指南完整列表及其适用条件。

• indices_reference —— 索引表的外部文档（可能比已安装的版本更新）

外部链接

• IDC 门户：https://portal.imaging.datacommons.cancer.gov/explore/
• 文档：https://learn.canceridc.dev/
• 教程：https://github.com/ImagingDataCommons/IDC-Tutorials
• 用户论坛：https://discourse.canceridc.dev/
• idc-index GitHub：https://github.com/ImagingDataCommons/idc-index
• 引用：Fedorov, A., et al. “National Cancer Institute Imaging Data Commons: Toward Transparency, Reproducibility, and Scalability in Imaging Artificial Intelligence.” RadioGraphics 43.12 (2023). https://doi.org/10.1148/rg.230180

技能更新

此技能版本可在技能元数据中查看。检查更新：

• 访问版本发布页面
• 在 GitHub 上关注此代码库（Watch → Custom → Releases）