imaging-data-commons

Imaging Data Commons

概述

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

当前 IDC 数据版本：v23（请务必使用 IDCClient().get_idc_version() 验证）

主要工具： idc-index（GitHub）

重要——检查包版本，并在需要时升级（首先运行此操作）：

import idc_index

REQUIRED_VERSION = "0.11.10"  # Must match metadata.idc-index in this file
installed = idc_index.__version__

if installed < REQUIRED_VERSION:
    print(f"Upgrading idc-index from {installed} to {REQUIRED_VERSION}...")
    import subprocess
    subprocess.run(["pip3", "install", "--upgrade", "--break-system-packages", "idc-index"], check=True)
    print("Upgrade complete. Restart Python to use 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 "v23")
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=...)

何时使用此技能

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

快速导航

核心章节（内嵌）：

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

参考指南（按需加载）：

指南	加载时机
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 Segmentation 序列	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）

自动 = 实例化 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 集成工具
Cloud storage (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。

安装和设置

必需（用于基本访问）：

pip install --upgrade idc-index

重要： 每次发布新的 IDC 数据都会触发 idc-index 的新版本。除非需要使用旧版本以确保可复现性，否则安装时始终使用 --upgrade 标志。

重要： 当前 IDC 数据版本为 v23。请务必确认你的版本：

print(client.get_idc_version())  # Should return "v23"

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

已测试版本： idc-index 0.11.10（IDC 数据版本 v23）

可选（用于数据分析）：

pip install pandas numpy pydicom

核心功能

1. 数据发现与探索

了解 IDC 中有哪些成像合集和数据：

from idc_index import IDCClient

client = IDCClient()

# Get summary statistics from primary index
query = """
SELECT
  collection_id,
  COUNT(DISTINCT PatientID) as patients,
  COUNT(DISTINCT SeriesInstanceUID) as series,
  SUM(series_size_MB) as size_mb
FROM index
GROUP BY collection_id
ORDER BY patients DESC
"""
collections_summary = client.sql_query(query)

# For richer collection metadata, use collections_index
client.fetch_index("collections_index")
collections_info = client.sql_query("""
    SELECT collection_id, CancerTypes, TumorLocations, Species, Subjects, SupportingData
    FROM collections_index
""")

# For analysis results (annotations, segmentations), use analysis_results_index
client.fetch_index("analysis_results_index")
analysis_info = client.sql_query("""
    SELECT analysis_result_id, analysis_result_title, Subjects, Collections, Modalities
    FROM analysis_results_index
""")

collections_index 提供每个合集的精选元数据：癌症类型、肿瘤位置、物种、受试者数量和支持的数据类型，无需从主索引中进行汇总。

analysis_results_index 列出衍生数据集（AI 分割、专家标注、放射组学特征）及其源合集和模态。

2. 使用 SQL 查询元数据

使用 SQL 查询 IDC 迷你索引，以查找特定数据集。

首先，查看筛选列的可用值：

from idc_index import IDCClient

client = IDCClient()

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

# Check what BodyPartExamined values exist for MR modality
body_parts = client.sql_query("""
    SELECT DISTINCT BodyPartExamined, COUNT(*) as series_count
    FROM index
    WHERE Modality = 'MR' AND BodyPartExamined IS NOT NULL
    GROUP BY BodyPartExamined
    ORDER BY series_count DESC
    LIMIT 20
""")
print(body_parts)

然后，使用已验证的筛选值进行查询：

# Find breast MRI scans (use actual values from exploration above)
results = client.sql_query("""
    SELECT
      collection_id,
      PatientID,
      SeriesInstanceUID,
      Modality,
      SeriesDescription,
      license_short_name
    FROM index
    WHERE Modality = 'MR'
      AND BodyPartExamined = 'BREAST'
    LIMIT 20
""")

# Access results as pandas DataFrame
for idx, row in results.iterrows():
    print(f"Patient: {row['PatientID']}, Series: {row['SeriesInstanceUID']}")

若要按癌症类型筛选，请与 collections_index 联接：

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.CancerTypes LIKE '%Breast%'
      AND i.Modality = 'MR'
    LIMIT 20
""")

可用元数据字段（使用 client.indices_overview 查看完整列表）：

• 标识符：collection_id、PatientID、StudyInstanceUID、SeriesInstanceUID
• 成像：Modality、BodyPartExamined、Manufacturer、ManufacturerModelName
• 临床：PatientAge、PatientSex、StudyDate
• 描述：StudyDescription、SeriesDescription
• 许可：license_short_name

注意： 癌症类型位于 collections_index.CancerTypes 中，而非主 index 表中。

3. 下载 DICOM 文件

从 IDC 的云存储高效下载影像数据：

下载整个数据集：

from idc_index import IDCClient

client = IDCClient()

# Download small collection (RIDER Pilot ~1GB)
client.download_from_selection(
    collection_id="rider_pilot",
    downloadDir="./data/rider"
)

下载指定序列：

# First, 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
""")

# Download only those series
client.download_from_selection(
    seriesInstanceUID=list(series_df['SeriesInstanceUID'].values),
    downloadDir="./data/lung_ct"
)

自定义目录结构：

默认 dirTemplate：%collection_id/%PatientID/%StudyInstanceUID/%Modality_%SeriesInstanceUID

# Simplified hierarchy (omit StudyInstanceUID level)
client.download_from_selection(
    collection_id="tcga_luad",
    downloadDir="./data",
    dirTemplate="%collection_id/%PatientID/%Modality"
)
# Results in: ./data/tcga_luad/TCGA-05-4244/CT/

# Flat structure (all files in one directory)
client.download_from_selection(
    seriesInstanceUID=list(series_df['SeriesInstanceUID'].values),
    downloadDir="./data/flat",
    dirTemplate=""
)
# Results in: ./data/flat/*.dcm

下载的文件名：

单个 DICOM 文件使用其 CRDC 实例 UUID 命名：<crdc_instance_uuid>.dcm（例如，0d73f84e-70ae-4eeb-96a0-1c613b5d9229.dcm）。基于 UUID 的命名方式：

• 支持版本跟踪（文件内容变化时，UUID 会改变）
• 与云存储组织方式一致（s3://idc-open-data/<crdc_series_uuid>/<crdc_instance_uuid>.dcm）
• 不同于 DICOM UID（SOPInstanceUID），后者保留在文件元数据中

要识别文件，请在查询中使用 crdc_instance_uuid 列，或读取文件中的 DICOM 元数据（SOPInstanceUID）。

命令行下载

idc download 命令提供命令行下载功能，无需编写 Python 代码。安装 idc-index 后即可使用。

自动检测输入类型： 清单文件路径或标识符（collection_id、PatientID、StudyInstanceUID、SeriesInstanceUID、crdc_series_uuid）。

# Download entire collection
idc download rider_pilot --download-dir ./data

# Download specific series by UID
idc download "1.3.6.1.4.1.9328.50.1.69736" --download-dir ./data

# Download multiple items (comma-separated)
idc download "tcga_luad,tcga_lusc" --download-dir ./data

# Download from manifest file (auto-detected)
idc download manifest.txt --download-dir ./data

选项：

选项	描述
--download-dir	输出目录（默认：当前目录）
--dir-template	目录层级模板（默认：%collection_id/%PatientID/%StudyInstanceUID/%Modality_%SeriesInstanceUID）
--log-level	详细级别：debug、info、warning、error、critical

清单文件：

清单文件包含 S3 URL（每行一个），可通过以下方式获取：

• 在选择队列后从 IDC 门户导出
• 由协作者共享，以便可复现地访问数据
• 根据查询结果以编程方式生成

格式（每行一个 S3 URL）：

s3://idc-open-data/cb09464a-c5cc-4428-9339-d7fa87cfe837/*
s3://idc-open-data/88f3990d-bdef-49cd-9b2b-4787767240f2/*

示例：根据 Python 查询生成清单：

from idc_index import IDCClient

client = IDCClient()

# Query for series URLs
results = client.sql_query("""
    SELECT series_aws_url
    FROM index
    WHERE collection_id = 'rider_pilot' AND Modality = 'CT'
""")

# Save as manifest file
with open('ct_manifest.txt', 'w') as f:
    for url in results['series_aws_url']:
        f.write(url + '\n')

然后下载：

idc download ct_manifest.txt --download-dir ./ct_data

4. 可视化 IDC 影像

无需下载，即可在浏览器中查看 DICOM 数据：

from idc_index import IDCClient
import webbrowser

client = IDCClient()

# First query to get valid UIDs
results = client.sql_query("""
    SELECT SeriesInstanceUID, StudyInstanceUID
    FROM index
    WHERE collection_id = 'rider_pilot' AND Modality = 'CT'
    LIMIT 1
""")

# View single series
viewer_url = client.get_viewer_URL(seriesInstanceUID=results.iloc[0]['SeriesInstanceUID'])
webbrowser.open(viewer_url)

# View all series in a study (useful for multi-series exams like MRI protocols)
viewer_url = client.get_viewer_URL(studyInstanceUID=results.iloc[0]['StudyInstanceUID'])
webbrowser.open(viewer_url)

此方法会自动为放射影像选择 OHIF v3，为切片显微镜选择 SLIM。按检查查看很有用，因为一个 DICOM 检查可能包含多个序列（例如，单次 MRI 检查中的 T1、T2、DWI 序列）。

5. 了解并检查许可证

使用前请检查数据许可（商业应用尤其重要）：

from idc_index import IDCClient

client = IDCClient()

# Check licenses for all collections
query = """
SELECT DISTINCT
  collection_id,
  license_short_name,
  COUNT(DISTINCT SeriesInstanceUID) as series_count
FROM index
GROUP BY collection_id, license_short_name
ORDER BY collection_id
"""

licenses = client.sql_query(query)
print(licenses)

IDC 中的许可证类型：

• CC BY 4.0 / CC BY 3.0（约 97% 的数据）——允许商业使用，但须注明来源
• CC BY-NC 4.0 / CC BY-NC 3.0（约 3% 的数据）——仅限非商业用途
• 自定义许可证（罕见）——部分数据集有特定条款（例如，NLM 条款与条件）

重要提示： 在出版物或商业应用中使用 IDC 数据之前，务必检查许可证。每个 DICOM 文件的元数据中都标注了其特定许可证。

生成引用以注明来源

source_DOI 列包含指向相关出版物的 DOI，这些出版物介绍了数据的生成方式。为满足注明来源的要求，请使用 citations_from_selection() 生成格式规范的引用：

from idc_index import IDCClient

client = IDCClient()

# Get citations for a collection (APA format by default)
citations = client.citations_from_selection(collection_id="rider_pilot")
for citation in citations:
    print(citation)

# Get citations for specific series
results = client.sql_query("""
    SELECT SeriesInstanceUID FROM index
    WHERE collection_id = 'tcga_luad' LIMIT 5
""")
citations = client.citations_from_selection(
    seriesInstanceUID=list(results['SeriesInstanceUID'].values)
)

# Alternative format: BibTeX (for LaTeX documents)
bibtex_citations = client.citations_from_selection(
    collection_id="tcga_luad",
    citation_format=IDCClient.CITATION_FORMAT_BIBTEX
)

参数：

• collection_id：按数据集筛选
• patientId：按患者 ID 筛选
• studyInstanceUID：按检查 UID 筛选
• seriesInstanceUID：按序列 UID 筛选
• citation_format：使用 IDCClient.CITATION_FORMAT_* 常量：
  • CITATION_FORMAT_APA（默认）——APA 格式
  • CITATION_FORMAT_BIBTEX——适用于 LaTeX 的 BibTeX 格式
  • CITATION_FORMAT_JSON——CSL JSON 格式
  • CITATION_FORMAT_TURTLE——RDF Turtle 格式

最佳实践： 使用 IDC 数据发布结果时，请附上生成的引用，以便正确注明数据来源并满足许可证要求。

6. 批量处理和筛选

通过筛选高效处理大型数据集：

from idc_index import IDCClient
import pandas as pd

client = IDCClient()

# Find chest CT scans from GE scanners
query = """
SELECT
  SeriesInstanceUID,
  PatientID,
  collection_id,
  ManufacturerModelName
FROM index
WHERE Modality = 'CT'
  AND BodyPartExamined = 'CHEST'
  AND Manufacturer = 'GE MEDICAL SYSTEMS'
  AND license_short_name = 'CC BY 4.0'
LIMIT 100
"""

results = client.sql_query(query)

# Save manifest for later
results.to_csv('lung_ct_manifest.csv', index=False)

# Download in batches to avoid timeout
batch_size = 10
for i in range(0, len(results), batch_size):
    batch = results.iloc[i:i+batch_size]
    client.download_from_selection(
        seriesInstanceUID=list(batch['SeriesInstanceUID'].values),
        downloadDir=f"./data/batch_{i//batch_size}"
    )

7. 使用 BigQuery 执行高级查询

对于需要完整 DICOM 元数据、复杂 JOIN、临床数据表或私有 DICOM 元素的查询，请使用 Google BigQuery。需要启用结算功能的 GCP 账号。

快速参考：

• 数据集：bigquery-public-data.idc_current.*
• 主表：dicom_all（合并后的元数据）
• 完整元数据：dicom_metadata（所有 DICOM 标签）
• 私有元素：OtherElements 列（厂商专属标签，例如扩散 b 值）

有关设置、表结构、查询模式、私有元素访问和成本优化，请参阅 references/bigquery_guide.md。

使用 BigQuery 前，请务必检查专用索引表是否已包含所需元数据：

1. 使用 client.indices_overview 或 idc-index 索引参考查看所有可用表及其列
2. 获取相关索引：client.fetch_index("table_name")
3. 使用 client.sql_query() 在本地查询（免费，无需 GCP 账号）

常见专用索引：seg_index（分割）、ann_index / ann_group_index（显微镜标注）、sm_index（切片显微镜）、collections_index（集合元数据）。只有在需要私有 DICOM 元素或任何索引中都没有的属性时，才使用 BigQuery。

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. 与分析工作流集成

将 IDC 数据集成到影像分析工作流中：

读取已下载的 DICOM 文件：

import pydicom
import os

# Read DICOM files from downloaded series
series_dir = "./data/rider/rider_pilot/RIDER-1007893286/CT_1.3.6.1..."

dicom_files = [os.path.join(series_dir, f) for f in os.listdir(series_dir)
               if f.endswith('.dcm')]

# Load first image
ds = pydicom.dcmread(dicom_files[0])
print(f"Patient ID: {ds.PatientID}")
print(f"Modality: {ds.Modality}")
print(f"Image shape: {ds.pixel_array.shape}")

从 CT 序列构建 3D 体积：

import pydicom
import numpy as np
from pathlib import Path

def load_ct_series(series_path):
    """Load CT series as 3D numpy array"""
    files = sorted(Path(series_path).glob('*.dcm'))
    slices = [pydicom.dcmread(str(f)) for f in files]

    # Sort by slice location
    slices.sort(key=lambda x: float(x.ImagePositionPatient[2]))

    # Stack into 3D array
    volume = np.stack([s.pixel_array for s in slices])

    return volume, slices[0]  # Return volume and first slice for metadata

volume, metadata = load_ct_series("./data/lung_ct/series_dir")
print(f"Volume shape: {volume.shape}")  # (z, y, x)

与 SimpleITK 集成：

import SimpleITK as sitk
from pathlib import Path

# Read DICOM series
series_path = "./data/ct_series"
reader = sitk.ImageSeriesReader()
dicom_names = reader.GetGDCMSeriesFileNames(series_path)
reader.SetFileNames(dicom_names)
image = reader.Execute()

# Apply processing
smoothed = sitk.CurvatureFlow(image1=image, timeStep=0.125, numberOfIterations=5)

# Save as NIfTI
sitk.WriteImage(smoothed, "processed_volume.nii.gz")

常见用例

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

• 从肺部 CT 扫描构建深度学习训练数据集
• 比较不同扫描仪厂商的图像质量
• 下载前在浏览器中预览数据
• 用于商业用途的许可证感知型批量下载

最佳实践

• 生成响应前确认 IDC 版本 - 每次会话开始时务必调用 client.get_idc_version()，确认使用的是预期数据版本（当前为 v23）。如果使用的是较旧版本，建议运行 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 包
• **解决方案：**使用 pip install --upgrade idc-index 安装

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

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

问题：BigQuery quota exceeded 或账单错误

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

问题：找不到 Series 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 处理

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

病理学和切片显微镜

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

元数据可视化

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

数据探索

• exploratory-data-analysis - 对科学数据文件进行全面的 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）