imaging-data-commons

Imaging Data Commons

概述

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

预期网络访问： IDC 元数据可通过三种方式访问——捆绑的本地 DuckDB 索引（安装后可离线使用；其他索引从 GitHub 获取，临床表格从 S3 获取），或通过 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 身份验证。引用解析会联系 DOI 服务。公开的 IDC 路由无需凭据；可选的 Google 客户端使用 Application Default Credentials。

审查日期 2026-09-30： idc-index 0.12.5、idc-index-data 24.2.2、IDC v24；托管 API 3.0.0b3。使用时请重新核查。

先选择访问路径。 不存在单一的默认路径：最经济的正确路径取决于 会话和任务。

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。

idc-index（GitHub）仍然是最 强大的 Python 路径，在同一个客户端中提供查询和下载辅助函数。check_version.py 本身从不安装任何东西——它还会在新版 idc-index 或技能发布时给出提示。

idc-index 路径的设置： 使用预期的解释器运行 scripts/check_version.py 并在继续之前确认其 meets pinned minimum 消息。启动失败不算通过。

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 层级（Patient → Study → Series → Instance）之上增加了两个分组层级：

• collection_id：按疾病、模态或研究重点对患者分组（例如 tcga_luad、nlst）。请将 (collection_id, PatientID) 视为患者键；不要假设 PatientID 全局唯一。
• analysis_result_id：标识跨一个或多个原始 collection 的派生对象（分割、标注、影像组学特征）。用它查找 AI 生成或专家标注，而 collection_id 用于查找原始影像数据（其本身也可能包含已存入的标注）。

查询的关键标识符：

标识符	范围	用途
collection_id	数据集分组	按项目/研究筛选
PatientID	患者	按患者对影像分组
StudyInstanceUID	DICOM study	对相关 series 分组、可视化
SeriesInstanceUID	DICOM series	对相关 series 分组、可视化

索引表

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

重要： client.indices_overview 是当前表描述、可用列及其类型的权威来源 — 在编写 SQL 或探索数据结构时查询它。它还能回答“哪个表包含列 X”；关于该搜索模式及完整的 schema 发现方法，请参阅 references/index_tables_guide.md。

可用表

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

系列	表	粒度
核心	index（所有当前数据的主要元数据）、collections_index、analysis_results_index	series / collection / analysis result
模态采集参数	ct_index、mr_index、pt_index、contrast_index	1 行 = 该模态的 1 个 series
派生对象	seg_index、rtstruct_index、ann_index、ann_group_index	1 行 = 1 个 series（或标注组）
显微	sm_index、sm_instance_index	1 行 = 1 个 SM series / instance
几何、临床、历史	volume_geometry_index、clinical_index、version_metadata_index、prior_versions_index	见指南

references/index_tables_guide.md 包含完整的清单，列出每个表的列和 内容 — 当你需要了解某个专用表实际包含什么时，加载它。

prior_versions_index 包含历史 series 版本，包括修订版本， 其 DICOM SeriesInstanceUID 仍出现在 index 中。若要获取历史 内容，请固定 crdc_series_uuid。关于当前版本的“新增内容”，请使用 主 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。始终通过这些表与 index 在 SeriesInstanceUID 上连接。以下例外情况使用不同的列名。

连接列	表	使用场景
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 出现在多个表中，但含义不同（计数与标识符、不同的更新上下文）。仅通过 UID 连接到 prior_versions_index 可能匹配多个历史修订版本；请使用 CRDC UUID 来区分它们。

有关详细的连接示例、模式发现模式、键列参考和 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

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"]}}}'

filter 对象始终放在 filters 下 —— 无论是在 cohort/counts、cohort/manifest、 cohort/manifest.txt、licenses 还是 citations 上都是如此。裸 filter 或无法识别的键会返回 422 并指明修复方法；未加 filter 的系列枚举请求会返回 400，而不是整个归档。 带 filter 的 JSON 响应会回显 filters_applied 和 warnings（对于 manifest 则在 counts 内）—— 请阅读它们，因为它们会指出 服务丢弃了哪些谓词。因此计数为零且 warnings 为空表示该 filter 没有匹配到任何内容，而不是某个值大小写写错了；大小写写错会产生一条说明此事的 warning。

POST /sql 接受一条只读的 SELECT/WITH，作用于 idc-index 暴露的表加上 clinical.<table>；max_rows 默认为 5 000，上限为 10 000，truncated 标记是否被截断。 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 无法下载额外的系列 —— 混合选择可能会遗漏 无法识别的 UID，而完全无匹配的选择会报错 —— 因此要么升级它（运行 scripts/check_version.py 获取正确的命令） 要么用 s5cmd --no-sign-request 直接从 bucket 传输。

端点参考、filter 基础、限制以及 基于 manifest 的下载流程请参见 references/rest_api_guide.md。

云存储组织

所有 DICOM 文件都存放在 AWS S3 与 GCS 之间镜像的公共 bucket 中，按 CRDC UUID （而非 DICOM UID）组织以支持版本控制，路径为 <crdc_series_uuid>/<crdc_instance_uuid>.dcm。通过 AWS CLI、gsutil 或 s5cmd 以匿名访问方式可免费访问 （无出口费用）；S3 URL 请使用 series_aws_url 列。Bucket 名称并不确立许可证；请为每个选定的系列查询 license_short_name。完整的 bucket 列表和 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 bucket （idc-index-data-artifacts）上，可用 DuckDB 或 pandas 查询。这需要安装 DuckDB。 对于临时元数据查询，优先使用 REST /sql；对于固定版本或大型结果，选择 Parquet。 另有一个独立的公共 S3 导出，还包含临床表和完整的 BigQuery 元数据。参见 references/parquet_access_guide.md。

核心能力

以下模式是从记忆中回忆而非经过核对时容易出错的地方。 每个领域的完整示例位于内联提到的参考指南中。

1. 发现 — 在按值过滤之前先枚举值

按猜测的 Modality 或 BodyPartExamined 字符串进行过滤，是导致结果集为空的最常见原因。请先枚举：

modalities = client.sql_query("""
    SELECT DISTINCT Modality, COUNT(*) as series_count
    FROM index
    GROUP BY Modality
    ORDER BY series_count DESC
""")
print(modalities)

同一模式适用于任何过滤列，也可以由另一列进一步收窄 —— 例如在某个 Modality 内收窄 BodyPartExamined，或收窄 Manufacturer、collection_id。在 REST 路径上，这种锚定只需一次调用 —— GET /attributes/{attr}/values 返回带计数的值 —— 而队列端点会在 warnings 中报告大小写有误的值，而不是返回空结果。

有两个索引带有主 index 不具备的、经整理的集合级元数据，二者都需要先调用 client.fetch_index(...)：collections_index（癌症类型、肿瘤位置、物种、受试者数量）和 analysis_results_index（派生数据集 —— AI 分割、专家标注、放射组学 —— 及其来源集合和模态）。

癌症类型位于 collections_index.cancer_types，而不是 index 中 —— 按癌症类型过滤需要一次 join：

client.fetch_index("collections_index")
results = client.sql_query("""
    SELECT i.collection_id, i.PatientID, i.SeriesInstanceUID, i.Modality
    FROM index i
    JOIN collections_index c ON i.collection_id = c.collection_id
    WHERE c.cancer_types LIKE '%Breast%'
      AND i.Modality = 'MR'
    LIMIT 20
""")

client.sql_query() 返回一个 pandas DataFrame。编写查询之前，请用 client.get_index_schema('index') 或 client.indices_overview 确认列名，而不要凭假设。

关于过滤值发现、标注与分割查询、体量估算、临床关联以及版本跟踪（"vX 中有什么新内容" —— 使用 index 中的 series_init_idc_version / series_revised_idc_version；历史对象使用 prior_versions_index），请参阅 references/sql_patterns.md。

2. 下载 DICOM 文件

两个下载方法的前两个参数顺序相反。 这是 IDC 代码出错最常见的原因 —— 请核对，而不要凭记忆：

方法	第一个参数	第二个参数	适用场景
download_from_selection	downloadDir（必填）	过滤关键字参数（可选）	按集合、患者、检查或序列过滤
download_dicom_series	seriesInstanceUID（必填）	downloadDir（必填）	仅按 UID 下载特定序列

download_from_selection 接受过滤关键字参数，而不是 DataFrame。 名称中的 "from_selection" 指的是按条件过滤 IDC 索引 —— 而不是接受 pandas DataFrame。若要下载查询结果，请先把 UID 提取到一个列表中：

# Step 1: Query for series UIDs
series_df = client.sql_query("""
    SELECT SeriesInstanceUID
    FROM index
    WHERE Modality = 'CT'
      AND BodyPartExamined = 'CHEST'
      AND collection_id = 'nlst'
    LIMIT 5
""")

# Step 2: Extract UIDs as a list from the DataFrame
uids = list(series_df['SeriesInstanceUID'].values)

# Step 3: Pass the list to download_from_selection (NOT the DataFrame itself)
client.download_from_selection(
    downloadDir="./data/lung_ct",
    seriesInstanceUID=uids       # list of strings, not a DataFrame
)

# Alternative: download_dicom_series has seriesInstanceUID as FIRST arg (different order!)
client.download_dicom_series(
    seriesInstanceUID=uids,      # FIRST arg here
    downloadDir="./data/lung_ct"
)

# Whole collection: downloadDir is still the FIRST positional argument
client.download_from_selection(downloadDir="./data/rider", collection_id="rider_pilot")

两者都默认使用 AWS；使用 source_bucket_location="gcs" 可切换到 Google。在 0.12.5 中，最具体的筛选器胜出，因此请先用 SQL 处理交叉条件，并核实每个请求的 UID 都存在。

下载的文件命名为 <crdc_instance_uuid>.dcm，而不是按 SOPInstanceUID 命名。 DICOM UID 保留在文件元数据中，而不是文件名中。读取 DICOM 头以获取序列 UID；crdc_instance_uuid 不是序列级 index 中的列。

idc download <collection|series-uid|manifest> --download-dir ./data 在 shell 中完成同样的事。关于 dirTemplate 层级选项（Python 默认值：%collection_id/%PatientID/%StudyInstanceUID/%Modality_%SeriesInstanceUID；dirTemplate="" 则扁平化）、带断点续传的 manifest 下载，以及 dry-run 体量估算，请参阅 references/cli_guide.md。

3. 可视化 IDC 图像

viewer_url = client.get_viewer_URL(seriesInstanceUID=uid)        # one series
viewer_url = client.get_viewer_URL(studyInstanceUID=study_uid)   # all series in a study

返回一个浏览器 URL —— 不会下载任何内容。该方法会自动选择用于放射学的 OHIF v3，或用于玻片显微镜的 SLIM。当单个 DICOM Study 包含多个 Series（例如来自一次 MRI 检查的 T1、T2 和 DWI）时，按 study 查看会很有用。

4. 许可证与引用——是义务，不是可选的步骤

IDC 数据带有许可证条款和署名要求，这些要求会随之进入任何下游出版物或产品，而这两者都无法从像素数据中推断出来。使用前请检查许可证，并为你下载的任何内容生成引用。

# License breakdown for a selection
licenses = client.sql_query("""
    SELECT DISTINCT collection_id, license_short_name,
           COUNT(DISTINCT SeriesInstanceUID) as series_count
    FROM index GROUP BY collection_id, license_short_name
""")

# Citations for the same selection you downloaded (APA by default)
for citation in client.citations_from_selection(collection_id="rider_pilot"):
    print(citation)

在受审查的 v24 快照中，按大小计算，约 97% 的 IDC 数据为 CC BY（允许商业使用，需署名），约 3% 为 CC BY-NC（仅限非商业用途）。许可证附加于系列，而非集合——176 个集合中有 39 个带有不止一种许可证——因此请检查你实际打算使用的选择，并注意每个组成部分仍保留其许可证义务。

这两项任务在所有三条访问路径上都可用，因此请停留在会话已在使用的那一条上：如上所述的 idc-index、通过 REST 的 POST /v3/licenses 和 POST /v3/citations，或 get_licenses 和 get_citations MCP 工具。完整的许可证清单、全部三条路径、引用格式（APA、BibTeX、CSL JSON、RDF Turtle）以及发布时应包含的内容，请参见 references/licensing_and_citation.md。

5. 超越索引的范围

请使用 Overview 中的路由判断来选择访问路径；上面的 Data Access Options 是完整的路由表。

在动用 BigQuery（需要 Google Cloud 项目及访问权限）之前，请先检查专门的索引表是否已经包含你想要的列：搜索 client.indices_overview，然后 client.fetch_index(...) 并在本地免费查询。完整的实例元数据、按分段的行以及 SR 测量表需要 BigQuery 或其公开的 Parquet 导出；这些不在精简的 idc-index 表范围内。

最佳实践

• 编写查询前先检查 schema — 使用 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 个 series）；关于 --use-s5cmd-sync 的断点续传和重试指导，请参见 references/cli_guide.md

问题：BigQuery quota exceeded 或计费错误

• 原因： 项目配额、沙盒限制或计费配置导致查询无法进行
• 解决方案： 对于简单查询，使用 idc-index mini-index（无需计费），或参见 references/bigquery_guide.md 了解成本优化建议

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

• 原因： UID 拼写错误、数据不在当前 IDC 版本中，或字段名错误
• 解决方案： 先用 LIMIT 5 测试，对照 client.indices_overview 检查字段名， 并确认该 series 存在于当前版本中（一些旧数据已被弃用）

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

• 原因： index 表仅包含 series 级元数据；特定模态的采集和重建参数位于专用表中（ct_index、mr_index、pt_index）
• 解决方案： 在 client.indices_overview 中搜索该列以找到它所在的表 — 相关循环位于 references/index_tables_guide.md 的 Finding which table contains a column 一节 — 然后获取并按 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 和 slide microscopy 都需要专用工具
• 解决方案： 使用普通的 pydicom.dcmread 检查 Modality、SOPClassUID 和传输语法； 强制解析并非验证。 在重新下载之前，检查下载完整性和解码器/查看器支持情况；将 force=True 留给已诊断的非 Part-10 输入使用。

资源

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

• IDC Portal：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
• 技能更新：releases 页面；关注该仓库（Watch → Custom → Releases）