影像数据共享 是做什么的？
概述
查询和下载来自美国国家癌症研究所影像数据共享（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（务必验证——请参见最佳实践）
首先选择访问路径。 没有单一的默认路径：最经济且正确的路径取决于会话和任务。
- 会话已存在 IDC MCP 服务器？ 将数据发现和元数据路由到那里——请参见 IDC MCP 服务器。
- 否则，是否已安装
idc-index？ 运行python scripts/check_version.py。如果通过，则对所有操作使用idc-index。 - 未安装，且任务仅涉及只读元数据——计数、属性值、数据集查找、少于 10000 行的 SQL、许可证、引用、查看器 URL？使用
curl通过 REST API；不要安装任何东西。 安装会消耗约 77 MB 的打包索引数据以及 pandas、pyarrow 和 duckdb，而元数据查询并不需要这些。请参见数据访问选项。 - 未安装，且任务需要超出元数据范围的功能——下载文件、pandas 或绘图、pydicom/SimpleITK、病理学切片、超过 10000 行的结果、或用户重复运行的版本固定脚本？安装
idc-index：check_version.py将以非零退出并打印针对当前运行解释器的精确安装命令。建议使用虚拟环境，然后重启 Python。
idc-index（GitHub）仍然是最强大的路径，也是唯一能够传输图像字节的路径；规则只是不要在任务需要它之前为其付费。check_version.py 本身从不安装任何东西——它还会在存在更新的 idc-index 或技能版本时进行标记。
idc-index 路径的设置：
from idc_index import IDCClient
client = IDCClient()
# 验证 IDC 数据版本（应为 "v24"）
print(f"IDC 数据版本: {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 服务器（可流式 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、数字病理学切片和可重现脚本。通过将服务器中的 SeriesInstanceUID 传递给 client.download_from_selection(...) 进行交接，并在此时运行 scripts/check_version.py。
如果不可用，相同的服务可以无需配置，通过 REST API 在 https://api.imaging.datacommons.cancer.gov/v3 访问——根据概述中的路由规则，使用它进行只读元数据查询，而不是安装 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 DataFrames 访问。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 出现在多个表中，但含义不同（计数与标识符不同、不同的更新上下文）。将 prior_versions_index 与 index 在 SeriesInstanceUID 上连接始终返回零行——请参阅上面的警告。
有关详细的连接示例、模式发现模式、关键列参考和 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 服务器 | 否 | 当会话已拥有它时，用于数据发现、队列构建、元数据 | 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 |
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 # 数据集, 患者, 检查, 序列, 实例, size_TB
curl -s "$B/attributes/Modality/values?limit=5" # 带计数的真实过滤器值
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":[{"attribute":"Modality","values":["CT"]}]}'
通过 idc-index 下载
client.download_from_selection() 是主要的下载函数，接受 SeriesInstanceUID 和可选的 downloadDir 和 dry_run。
from idc_index import IDCClient
client = IDCClient()
# 查询
results = client.sql_query("SELECT SeriesInstanceUID, collection_id, Modality FROM index WHERE Modality='MR' LIMIT 5")
print(type(results), len(results)) # pandas DataFrame
# 查看 IDC 查看器中的序列
uid = results['SeriesInstanceUID'][0]
print(f"查看器 URL: {client.get_viewer_URL(uid)}")
# 下载（预览）
dl = client.download_from_selection(uid, dry_run=True)
print(f"将下载 {dl['fileCount']} 个文件 ({dl['sizeGB']:.2f} GB) 到 {dl['downloadDir']}")
# 实际下载：client.download_from_selection(uid, downloadDir="./downloads")
许可证检查
client.get_collection_license(collection_id) 返回许可证名称和 URL。如果值为 NULL，请使用 client.get_license_restful(collection_id)。
license_info = client.get_collection_license("tcga_luad")
print(f"许可证: {license_info}")
查看器 URL 生成
client.get_viewer_URL(SeriesInstanceUID) 返回一个指向 IDC 门户中 OHIF 查看器的链接。对于病理学图像，使用 https://portal.imaging.datacommons.cancer.gov/slim/study?studyInstanceUID={uid}。在生成查看器 URL 之前，始终检查 Modality：SM（玻片显微镜）使用 SLIM 查看器；所有其他模态（CT、MR、PT、SEG 等）使用 OHIF。
引用和出版
client.get_collection_citation(collection_id) 以 BibTeX 格式返回引用。
最佳实践
-
版本固定： 始终显式检查
client.get_idc_version()。当前版本是 v24。将结果脚本与特定版本固定。不要假设版本是最新的。 -
许可证优先方法： 在下载或处理任何数据之前，始终检查
client.get_collection_license(collection_id)。IDC 数据集具有不同的许可证，包括需要归属的 Creative Commons 许可证和商业限制。切勿假设所有 IDC 数据都用于研究用途。 -
文件大小意识： 始终使用
dry_run=True检查大小和文件计数，然后再批量下载。单个序列可以轻松超过 1 GB，尤其是病理学玻片。对于大型数据集，考虑使用download_from_selection，它尊重downloadDir并支持增量下载。 -
路径可用性： 在项目之间，IDC 上的文件路径可能会更改。即使对于看似相同的请求，也始终使用
client.download_from_selection(...)或client.get_download_paths(...)获取当前路径。不要缓存文件路径。 -
将 MCP/REST 用于元数据，将
idc-index用于字节： 遵守概述中的路由规则。MCP 服务器和 REST API 在探索时更轻量——仅当需要下载或 pandas 时才切换到idc-index。 -
代码块和脚本应使用
idc-index： 即使当前会话使用 MCP 或 REST，可重现的脚本、notebook 和管道应使用idc-index，因为它是唯一独立工作的路径。 -
使用
indices_overview进行模式发现： 不要猜测列名——查询client.indices_overview以获取确切的列名、类型和表描述。这是最准确的模式文档。 -
使用
list_analysis_results查找注释： 在使用idc-index或 REST API 之前，使用 MCP 服务器查找注释数据和 AI 训练数据集。查看器工具按分析结果 ID 分组。 -
记住 IDC 聚合对象： 一些 IDC 对象包含许多实例（例如，病理学玻片、CT 序列）。根据对象来自
sm_instance_index还是通过单个SeriesInstanceUID下载，对象计数可能显得很高。始终检查大小。 -
使用参考指南： 每个专用用例都有一个参考指南（工作流程、临床数据、DICOMweb、BigQuery、Parquet、CLI）。在编写带外查询时加载这些指南。
故障排除
| 症状 | 原因 | 解决方案 |
|---|---|---|
ModuleNotFoundError: No module named 'idc_index' | idc-index 未安装 | 运行 scripts/check_version.py 获取确切的安装命令 |
client.sql_query() 返回空 DataFrame | 查询未匹配任何结果，或列名不正确 | 检查 client.indices_overview 中的列名；使用 LIKE 进行模糊匹配 |
client.download_from_selection() 失败 | 文件路径已过时，或网络错误 | 使用 dry_run=True 验证第一个 UID；检查 GCS/S3 连通性 |
client.get_viewer_URL() 返回 OHIF 但病理学不显示 | 模态是 SM（玻片显微镜） | 使用 SLIM 查看器 URL 代替：/slim/study?studyInstanceUID={uid} |
许可证检查返回 None | 数据集可能使用非标准许可证 | 使用 client.get_license_restful(collection_id) 作为备用 |
client.get_idc_version() 返回低于预期的版本 | 未更新的缓存或包版本 | 更新 idc-index：scripts/check_version.py 标记新版本 |
curl 到 REST API 返回 404 | 端点不正确，或 API 版本问题 | 验证基础 URL 为 https://api.imaging.datacommons.cancer.gov/v3；检查 $B/version |
MCP 服务器 get_idc_version 返回不同版本 | MCP 服务器可能运行不同版本 | 信任服务器版本；idc-index 应匹配，但必要时使用 scripts/check_version.py 对齐 |
download_from_selection() 计数与预期不匹配 | download_from_selection 返回文件计数，而不是序列计数 | 将结果与 sql_query 的计数交叉验证 |
连接 prior_versions_index 产生零行 | prior_versions_index 包含已移除的序列，与实际数据无重叠 | 仅用于重现早期版本；对于版本历史，使用 index 中的 series_init_idc_version / series_revised_idc_version |
client.fetch_index() 失败或返回空 | 表可能已重命名或移动 | 检查 indices_overview 中当前的表名；更新代码 |