imaging-data-commons

Imaging Data Commons

概述

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

**预期网络访问：**有三种方式可以访问 IDC 元数据——idc-index Python 软件包附带的本地 DuckDB 索引（无需网络），或通过 MCP 或 REST 访问托管的 IDC 服务（api.imaging.datacommons.cancer.gov，无需身份验证）。文件通过公共 GCS（storage.googleapis.com）和 AWS S3（s3.amazonaws.com）下载，无需身份验证。DICOMweb 访问可使用公共 IDC 代理（proxy.imaging.datacommons.cancer.gov，无需身份验证）或 Google Cloud Healthcare API（healthcare.googleapis.com，需要 GCP 身份验证）。可选的 BigQuery 查询（bigquery.googleapis.com）也需要 GCP 身份验证。本技能不会访问任何凭据或环境变量。

当前 IDC 数据版本：v24（务必核实——参见 最佳实践）

**先选择访问路径。**没有唯一的默认选项：最合适且成本最低的路径取决于会话和任务。

1. **当前会话是否已配置 IDC MCP 服务？**将数据发现和元数据查询交由该服务处理——参见 IDC MCP 服务。
2. **否则，是否已安装 idc-index？**运行 python scripts/check_version.py。如果检查通过，所有操作都使用 idc-index。
3. 未安装，且任务只涉及只读元数据——例如计数、属性值、集合查询、少于 10 000 行的 SQL 查询、许可证、引用或查看器 URL？**使用 curl 访问 REST API；不要安装任何内容。**安装需要约 77 MB 的索引数据，以及 pandas、pyarrow 和 duckdb，而元数据查询并不需要它们。参见 数据访问选项。
4. 未安装，且任务不止涉及元数据——例如下载文件、使用 pandas 或绘图、使用 pydicom/SimpleITK、病理图像切片、获取超过 10 000 行的结果，或编写用户会重新运行且固定版本的脚本？安装 idc-index：check_version.py 会以非零状态码退出，并打印适用于当前 Python 解释器的确切安装命令。建议使用虚拟环境，然后重启 Python。

idc-index（GitHub）仍然是功能最强的访问方式，也是唯一可以传输影像数据的方式；规则只是不要在任务需要它之前为此付出成本。check_version.py 不会自行安装任何内容——如果有更新版本的 idc-index 或技能，也会提示。

idc-index 路径的设置：

from idc_index import IDCClient
client = IDCClient()

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

**核心工作流：**使用 client.sql_query() 查询元数据 → 使用 client.download_from_selection() 下载 → 使用 client.get_viewer_URL() 可视化。以下 Python 示例均假设已使用此 client；数据访问选项中提供 REST 等效方式。要了解当前数据规模，请运行 references/sql_patterns.md 中的汇总查询，或执行 GET /v3/stats。

IDC MCP 服务

IDC 在 https://api.imaging.datacommons.cancer.gov/mcp 运营一个托管 MCP 服务 (streamable HTTP，无需身份验证)。在可用的情况下，它是对下方 idc-index 工作流的补充——而非 替代。

识别它：可通过 MCP 资源 idc://guide，或通过以下工具名称中的三个或更多来识别： build_cohort、get_cohort_urls、list_analysis_results 和 get_idc_version。像 run_sql 这样的通用名称本身并不构成证据。如果识别存在歧义，请使用 idc-index。

如果本次会话中有该服务，请将其视为发现和元数据的权威来源—— IDC 版本、计数、属性值、队列构建、元数据 SQL——并遵循 服务自身的说明，而不是从本文件重新推导。其数据版本以 服务报告的为准：调用 get_idc_version，而不要依赖本文件中固定的版本。

回到这里处理该服务不做的事情：下载文件、本地 pandas/notebook 分析、DICOMweb、BigQuery、数字病理切片、以及可复现脚本。交接方式为 将服务返回的 SeriesInstanceUIDs 传递给 client.download_from_selection(...)，并在 此时运行 scripts/check_version.py。

如果它不可用，同样的服务无需配置即可通过 REST API 访问：https://api.imaging.datacommons.cancer.gov/v3——根据 Overview 中的路由 关卡，请用它进行只读元数据查询，而不是安装 idc-index。最多建议连接 MCP 服务一次，且仅在需要重复的交互式发现时，切勿自行更改用户的 配置。

有关工具清单、交接模式和各类主机说明，请参见 references/mcp_guide.md。

何时使用本技能

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

快速导航

下方内联内容：MCP/REST 路由规则、IDC 数据模型、索引表及其 连接方式、核心 API 模式 (查询、下载、可视化、许可、引用)、最佳实践以及 故障排除。

参考指南 (按需加载)：

指南	何时加载
index_tables_guide.md	复杂 JOIN、模式发现、DataFrame 访问
use_cases.md	端到端工作流：训练数据集、批量下载、使用 pydicom/SimpleITK 读取 DICOM、流水线集成
sql_patterns.md	用于筛选发现、标注、大小估算的快速 SQL 模式
clinical_data_guide.md	临床/表格数据、影像+临床连接、值映射
licensing_and_citation.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、清单文件)
parquet_access_guide.md	通过 GCS 直接进行 Parquet 查询 (无需安装 idc-index)
mcp_guide.md	托管 IDC MCP 服务：工具清单、识别、交接给 idc-index
rest_api_guide.md	托管 IDC REST API：端点、筛选语法、基于 HTTP 的 SQL、清单

IDC 数据模型

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

• collection_id：按疾病、模态或研究重点对患者分组（例如 tcga_luad、nlst）。每位患者恰好属于一个集合。
• analysis_result_id：标识一个或多个原始集合中的衍生对象（分割、注释、影像组学特征）。使用它查找 AI 生成或专家注释；使用 collection_id 查找原始影像数据（其中可能本身就包含已提交的注释）。

查询的关键标识符：

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

索引表

idc-index 包提供多个元数据索引表，可通过 SQL 或 pandas DataFrame 访问。REST API 通过 GET /tables 和 POST /sql 提供相同的表。

重要： client.indices_overview 是当前表说明、可用列及其类型的权威来源——编写 SQL 或探索数据结构时请查询它。它也能回答“列 X 位于哪个表中”；此类搜索模式和完整架构发现方法请参见 references/index_tables_guide.md。

可用表

查询任何索引表之前，务必调用 client.fetch_index("table_name")——对于所有表（包括启动时自动加载的表），此操作都是安全且幂等的。

系列	表	粒度
核心	index（所有当前数据的主要元数据）、collections_index、analysis_results_index	序列／集合／分析结果
模态采集参数	ct_index、mr_index、pt_index、contrast_index	1 行 = 该模态的 1 个序列
衍生对象	seg_index、rtstruct_index、ann_index、ann_group_index	1 行 = 1 个序列（或注释组）
显微镜	sm_index、sm_instance_index	1 行 = 1 个 SM 序列／实例
几何、临床、历史	volume_geometry_index、clinical_index、version_metadata_index、prior_versions_index	参见指南

references/index_tables_guide.md 包含完整清单，列出每个表的列和 内容——需要了解专用表的具体内容时，请加载该文件。

prior_versions_index 仅用于可复现性。 其中包含已从 IDC 永久移除的序列，与 index 完全没有重叠。只有在需要针对较早的 IDC 版本复现工作时才使用它。切勿将其用于版本历史或“有哪些新增内容”之类的问题——这些应使用主 index 表中的 series_init_idc_version / series_revised_idc_version，它们与此表中的 min_idc_version / max_idc_version 并不等同。

连接表

SeriesInstanceUID 是所有系列级专用表的通用连接键：sm_index、sm_instance_index、seg_index、ann_index、ann_group_index、contrast_index、volume_geometry_index、rtstruct_index、ct_index、mr_index、pt_index。始终使用 SeriesInstanceUID 将这些表与 index 连接。以下例外使用不同的列名。

连接列	表	用例
collection_id	index, prior_versions_index, collections_index, clinical_index	将系列关联到集合元数据或临床数据
analysis_result_id	index, analysis_results_index	将系列关联到分析结果元数据（注释、分割）
source_DOI	index, analysis_results_index	按出版物 DOI 关联
segmented_SeriesInstanceUID	seg_index → index	将分割关联到其源图像系列（seg_index.segmented_SeriesInstanceUID = index.SeriesInstanceUID）
referenced_SeriesInstanceUID	ann_index → index, rtstruct_index → index	将注释或 RTSTRUCT 关联到其源图像系列

注意： subjects、updated 和 description 会出现在多个表中，但含义各不相同（计数与标识符、不同的更新场景）。按 SeriesInstanceUID 将 prior_versions_index 与 index 连接始终会返回零行——请参阅上方的警告。

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

临床数据访问

临床（非影像）属性——分期、人口统计信息、治疗——存储在各集合对应的表中。client.fetch_index("clinical_index") 会加载将列映射到集合的字典；client.get_clinical_table(name) 会以 DataFrame 形式返回一个表。

有关发现工作流、编码值映射以及将临床数据与影像连接的说明，请参阅 references/clinical_data_guide.md。

数据访问选项

方法	身份验证	最适用于	参考
idc-index	否	下载、pandas 分析、不受限查询——功能最全面的方式	本文档
IDC MCP server	否	会话中已有相关数据时，用于发现、队列构建和元数据查询	mcp_guide.md
IDC REST API	否	无需安装，即可通过任何语言或 shell 获取元数据——未安装 idc-index 时的默认选择	rest_api_guide.md
直接访问 Parquet（GCS）	否	固定版本的查询，或 REST 行数上限以外的结果	parquet_access_guide.md
云存储（S3/GCS）	否	直接访问文件、批量传输、自定义管道	cloud_storage_guide.md
通过 IDC 代理访问 DICOMweb	否	工具和 PACS 集成；有每日配额，适合测试和中等用量	dicomweb_guide.md
通过 Google Healthcare 访问 DICOMweb	是（GCP）	生产规模下使用相同的 DICOMweb API，不受代理配额限制	dicomweb_guide.md
SlicerIDCBrowser	否	在 3D Slicer 中进行 3D 可视化和分析	https://github.com/ImagingDataCommons/SlicerIDCBrowser
BigQuery	是（GCP）	完整的 DICOM 元数据、私有元素、SR 测量值——最后的选择	bigquery_guide.md

**IDC Portal（https://portal.imaging.datacommons.cancer.gov/）仅供交互使用**—— 通过浏览器探索、手动选择队列并下载。与上述所有选项不同，它没有编程接口，因此应引导用户前往该门户自行浏览或点击查看数据；切勿将其用作脚本或工作流中的步骤。

REST API——无需安装的元数据访问方式

https://api.imaging.datacommons.cancer.gov/v3，无需身份验证：发现、队列计数和清单、只读 SQL、临床表、查看器 URL、许可证、引用。它与 MCP 服务是同一服务，只是通过普通 HTTP 提供，因此无需配置。它不会传输图像字节——如需下载、获取 DataFrame 或查询超过 10 000 行的结果，请切换到 idc-index。

B=https://api.imaging.datacommons.cancer.gov/v3
curl -s $B/version   # idc_version, idc_index_data_version, api_version
curl -s $B/stats     # collections, patients, studies, series, instances, size_TB
curl -s "$B/attributes/Modality/values?limit=5"   # real filter values, with counts
curl -s $B/sql -H 'content-type: application/json' \
  -d '{"sql":"SELECT collection_id, COUNT(*) n FROM index GROUP BY 1 ORDER BY n DESC LIMIT 3"}'
curl -s $B/cohort/counts -H 'content-type: application/json' \
  -d '{"filters":{"terms":{"collection_id":["rider_pilot"]}}}'

筛选器对象始终放在 filters 下——无论是 cohort/counts、cohort/manifest、 cohort/manifest.txt、licenses 还是 citations。直接传入筛选器或使用无法识别的键会返回 422，并指出修正方式；枚举序列但未应用筛选的请求会返回 400，而不是整个归档。 每个经过筛选的响应都会返回 filters_applied 和 warnings——请查看它们，因为其中会列出服务端丢弃的任何谓词。因此，计数为 0 且 warnings 为空，表示筛选器没有匹配项，而不是值的大小写有误；大小写有误时会产生相应警告。

POST /sql 接受一条针对 idc-index 所公开的表以及 clinical.<table> 执行的只读 SELECT/WITH 语句；max_rows 默认为 5 000，上限为 10 000，截断时会将 truncated 标记为 true。 GET /attributes 列出 19 个可筛选属性——临床值、分段解剖结构和采集参数不在其中，需使用 SQL。没有速率限制或配额。仅使用 v3： V1 和 V2 已被取代，并计划关闭，因此用户提供任何 /v1/ 或 Modality_btw 风格的示例时，应将其迁移，而不是继续扩展。

两端都基于 idc-index-data 构建，因此混用前请比较 API 的 idc_index_data_version 和本地的 idc_index_data.__version__：主版本号对应 IDC 数据发布版本（24.x.y 对应 v24），所以次版本号或补丁版本号不同，表示序列相同。如果 API 领先一个完整发布版本，idc-index 无法下载额外的序列——它会静默跳过自身索引中未列出的内容——因此请升级它（运行 scripts/check_version.py 获取正确命令），或使用 s5cmd --no-sign-request 直接从存储桶传输。

端点参考、筛选器依据、限制和基于清单的下载流程，请参阅 references/rest_api_guide.md。

云存储组织方式

所有 DICOM 文件都存储在 AWS S3 和 GCS 之间镜像的公开存储桶中，并按 CRDC UUID（而非 DICOM UID）组织，以支持版本管理，路径格式为 <crdc_series_uuid>/<crdc_instance_uuid>.dcm。 可通过 AWS CLI、gsutil 或启用匿名访问的 s5cmd 免费访问（无出口流量费用）；S3 URL 请使用 series_aws_url 列。请注意，idc-open-data-cr / idc-open-cr（约占数据的 4%）限制商业用途（CC BY-NC）。完整的存储桶列表和 UUID 映射请参阅 references/cloud_storage_guide.md。

DICOMweb 访问

IDC 数据可通过 DICOMweb（Google Cloud Healthcare API）访问，以便集成 PACS 和使用兼容 DICOMweb 的工具：测试和中等规模查询可使用公开代理（无需身份验证，有每日配额）；生产规模则使用 Google Healthcare（GCP 身份验证）。请参阅 references/dicomweb_guide.md。

直接访问 Parquet

idc-index 元数据表也以 Parquet 格式发布在公开 GCS 存储桶 （idc-index-data-artifacts）中，可使用 DuckDB 或 pandas 查询。此方式需要安装 DuckDB，且无法访问按集合划分的临床表，因此临时查询元数据时优先使用 REST /sql； 若要固定数据版本或获取超过 REST 行数上限的结果，则选择 Parquet。请参阅 references/parquet_access_guide.md。

核心功能

详情、代码示例和参数表见：references/core-capabilities.md。此步骤适用时请阅读。

最佳实践

• 编写查询前先检查架构 — 使用 client.get_index_schema('index')（读取缓存的元数据，不会执行 SQL）或 client.indices_overview，查看所有可用列及其说明。主 index 表中的版本跟踪列 series_init_idc_version 和 series_revised_idc_version，可以直接回答“有哪些新内容／何时添加”之类的问题，无需访问 prior_versions_index。
• IDC 数据内容问题绝不使用网络搜索 - 始终直接查询 IDC 索引：在本地使用 client.sql_query()，或通过 HTTP 使用 POST /v3/sql。网络来源（发行说明、博客文章、文档页面）往往已经过时，会导致答案错误。索引是权威来源，即使可以使用网络搜索，也应以索引为准。
• 在会话开始时验证 IDC 数据版本 - 根据所用方式，使用 client.get_idc_version()、GET /v3/version 或 MCP get_idc_version 工具（当前为 v24）。如果本地索引过期，请运行 scripts/check_version.py，并使用它打印出的升级命令
• 检查许可并生成引用 - 查询 license_short_name 并遵守 CC BY 与 CC BY-NC 条款；使用 citations_from_selection() 根据出版物的 source_DOI 生成引用
• 先小规模探索，再执行 - 探索时使用 LIMIT（或较低的 max_rows），下载前检查集合大小——有些集合达数 TB。请参阅 references/cli_guide.md
• 确保下载可复现 - 使用 dirTemplate 组织文件（例如 %collection_id/%PatientID/%Modality），并保存所构建数据集对应的 Series UID 或清单

故障排除

问题：ModuleNotFoundError: No module named 'idc_index'

• 原因： 未安装 idc-index 软件包
• 解决方案： 如果任务只涉及只读元数据，请勿安装；改用 REST API（参见 数据访问选项）。否则，运行 scripts/check_version.py，并使用它打印出的安装命令；该命令会针对当前运行的解释器，并固定到经过验证的版本。进行数据分析时，还需添加 pandas、numpy 和 pydicom（已使用 pandas>=1.5、numpy>=1.23、pydicom>=2.3 测试）

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

• 原因： 网络不稳定或下载量过大
• 解决方案： 分批下载（每批 10-20 个序列）；有关 --use-s5cmd-sync 的续传和重试指南，请参阅 references/cli_guide.md

问题：BigQuery quota exceeded 或账单错误

• 原因： BigQuery 要求使用已启用账单功能的 GCP 项目
• 解决方案： 简单查询可使用 idc-index mini-index（无需账单），或参阅 references/bigquery_guide.md 了解费用优化技巧

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

• 原因： UID 拼写错误、数据不在当前 IDC 版本中，或字段名称错误
• 解决方案： 先使用 LIMIT 5 测试，根据 client.indices_overview 检查字段名称，并确认该序列属于当前版本（部分旧数据已弃用）

问题：index 表中找不到列（例如 SliceThickness、PixelSpacing、KVP、EchoTime、InjectedDose）

• 原因： index 表只包含序列级元数据；模态特定的采集和重建参数位于专用表（ct_index、mr_index、pt_index）中
• 解决方案： 在 client.indices_overview 中搜索该列以查找其所在的表——相关循环位于 references/index_tables_guide.md 的 查找包含某列的表 一节——然后获取数据并按 SeriesInstanceUID 联接：

  client.fetch_index("ct_index")
  result = client.sql_query("""
      SELECT i.SeriesInstanceUID, i.Modality, c.SliceThickness, c.KVP, c.PixelSpacing_row_mm
      FROM index i
      JOIN ct_index c USING (SeriesInstanceUID)
      WHERE i.collection_id = 'your_collection'
  """)
  

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

• 原因： 下载文件损坏，或查看器无法处理该对象类型——SEG、RTSTRUCT、SR 和切片显微图像都需要专用工具
• 解决方案： 首先检查 Modality 和 SOPClassUID，使用 pydicom.dcmread(file, force=True) 验证，尝试其他查看器（病理图像可使用 3D Slicer、QuPath），然后重新下载

资源

参考指南及其触发条件列于上方的 快速导航 中。

• IDC 门户：https://portal.imaging.datacommons.cancer.gov/explore/
• 文档：https://learn.canceridc.dev/ — 教程：https://github.com/ImagingDataCommons/IDC-Tutorials
• 用户论坛：https://discourse.canceridc.dev/ — idc-index：https://github.com/ImagingDataCommons/idc-index
• indices_reference — 外部索引表文档（内容可能比已安装版本更新）
• 引用：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
• 技能更新：发布页面；关注此代码库（Watch → Custom → Releases）

相关技能

• depmap：查询癌症依赖图谱（DepMap），获取癌细胞系基因依赖评分（CRISPR Chronos）、药物敏感性数据和基因效…
• bids：使用脑影像数据结构（BIDS）标准组织、查询、验证和转换神经科学及生物医学数据集，co…