影像數據共享平台 是做什麼的？
概覽
查詢並下載來自美國國家癌症研究所（NCI）影像數據共享平台（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。 - 未安裝，且任務為唯讀中繼資料 —— 計數、屬性值、集合查詢、少於 10,000 行的 SQL、授權、引用、檢視器 URL？使用
curl透過 REST API，不要安裝任何東西。 安裝會耗費約 77 MB 的壓縮索引數據以及 pandas、pyarrow 和 duckdb，而一個中繼資料查詢並不需要這些。請參閱 資料存取選項。 - 未安裝，且任務需要的不只是中繼資料 —— 下載檔案、pandas 或繪圖、pydicom/SimpleITK、病理學切片、超過 10,000 行的結果，或是使用者會重複執行的版本鎖定腳本？安裝
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 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 伺服器（可串流的 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 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 行 = 該模態的一個序列 |
| 衍生物件 | seg_index、rtstruct_index、ann_index、ann_group_index | 1 行 = 一個序列（或註釋群組） |
| 顯微鏡 | sm_index、sm_instance_index | 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。始終將這些表與 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 出現在多個表中，但具有不同的含義（計數 vs 識別符、不同的更新上下文）。將 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 |
IDC 入口網站 (https://portal.imaging.datacommons.cancer.gov/) 僅為互動式使用 —— 基於瀏覽器的探索、手動選擇佇列和下載。與上述所有選項不同，它沒有程式化介面，因此請引導使用者自行瀏覽或點擊資料；切勿將其用作腳本或工作流程中的一個步驟。
REST API —— 無需安裝的中繼資料路徑
https://api.imaging.datacommons.cancer.gov/v3，無需驗證：探索、佇列計數和清單、唯讀 SQL、臨床表、檢視器 URL、授權、引用。它與 MCP 伺服器透過純 HTTP 提供的服務相同，因此無需配置。它從不移動影像位元組 —— 切換到 idc-index 以下載、獲取 DataFrame，或取得超過 10,000 行的結果。
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" # 實際的過濾值，附帶計數
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"]}]}'
curl -s $B/collections/tcga_luad/citation
curl -s $B/collections/tcga_luad/license
curl -s "$B/viewer?SeriesInstanceUID=1.2.840.113654.2.55.123456789"
核心 API 模式
本節涵蓋使用 idc-index Python 套件的常見工作流程；請參閱 rest_api_guide.md 以了解等效的 curl 命令。
1. 探索集合和中繼資料
列出所有集合，按大小排序：
collections_df = client.sql_query("""
SELECT collection_id, collection_name, count(*) as series_count, license, license_url
FROM index
GROUP BY collection_id, collection_name, license, license_url
ORDER BY series_count DESC
""")
依模態篩選：
ct_collections = client.sql_query("""
SELECT DISTINCT collection_id FROM index WHERE Modality = 'CT'
""")
2. 下載資料
下載由 SQL 查詢定義的佇列：
manifest_df = client.sql_query(
"SELECT SeriesInstanceUID, collection_id FROM index WHERE Modality = 'SM' AND collection_id = 'tcga_bc'",
return_manifest=True
)
client.download_from_selection(manifest_df, downloadDir="/data/idc")
3. 視覺化
url = client.get_viewer_URL(SeriesInstanceUID="1.2.840.113654.2.55.1234567890")
print(f"在 IDC 檢視器中開啟：{url}")
4. 檢查授權
license_info = client.sql_query("""
SELECT collection_id, license FROM index
WHERE collection_id IN ('tcga_luad', 'nlst')
""")
5. 引用資料
citations = client.sql_query("""
SELECT collection_id, collection_name, DOI, citation
FROM collections_index
WHERE collection_id IN ('tcga_luad', 'nlst')
""")
最佳實踐
- 驗證 IDC 版本： 始終先檢查
client.get_idc_version()。此技能是根據 v24 編寫的，但 IDC 會定期發展。 - 首先使用
check_version.py： 在安裝idc-index之前執行python scripts/check_version.py。如果通過，使用現有安裝；如果失敗，它會輸出確切的安裝指令。 - 偏好唯讀中繼資料的 REST 路徑： 對於不需要下載的快速中繼資料問題，使用
curl和 REST API，以避免安裝依賴項的巨大開銷。 - 對於分析使用虛擬環境： 在安裝
idc-index及其科學計算依賴項時，始終建立一個新的虛擬環境。 - 批次下載較大的佇列： 不要在長時間執行的下載中使用互動式 Python 工作階段；編寫一個腳本並在背景執行它。
- 注意資料大小：
client.sql_query("SELECT count(*) FROM index")或GET /v3/stats會告訴您當前版本的大小。相當大的佇列可能需要大量儲存和頻寬。 - 使用 SeriesInstanceUID 作為連接鍵： 所有序列級專門表都使用
SeriesInstanceUID來連接到主index表。 - 檢查授權 在用於商業或發布之前：使用
client.sql_query()過濾index表的license欄位。 - 僅對歷史重現性使用
prior_versions_index： 查詢“有什麼新東西”應使用主index表中的series_init_idc_version和series_revised_idc_version。 - 將此腳本化為可重現的工作流程： 不要依賴互動式探索以獲取最終的資料集；編寫參數化的 SQL 查詢和版本鎖定的下載腳本。
資料來源和術語
IDC 包含來自多個儲存庫的資料，包括：
- TCGA（癌症基因體圖譜）：數千名患者的基因體和影像資料
- NLST（國家肺部篩檢試驗）：低劑量 CT 肺篩檢
- QIN（定量影像網路）：包含定量成像生物標記的試驗
- CPTAC（臨床蛋白質體學腫瘤分析聯盟）：蛋白質體學和影像
- CTP（兒童腫瘤學）：兒童癌症影像
- PDC（病理學資料集）：專業的玻片顯微鏡集合
- 其他：眾多較小的集合
關鍵術語：
- 集合： 由一個研究或目的分組的相關資料（例如 TCGA-LUAD、NLST）
- SeriesInstanceUID： 唯一影像序列的通用識別符（DICOM 標準）
- 模態： 影像類型（CT、MR、PT、SM 用於玻片顯微鏡）
- 分析結果： 衍生資料物件（分割、放射組學、註釋）
疑難排解
| 問題 | 解決方案 |
|---|---|
| 資料版本警告 | client.get_idc_version() 報告一個版本（例如 v23），對應於較舊的技能文件。執行 python scripts/check_version.py，並考慮執行 pip install --upgrade idc-index。 |
pip install 花費時間長或失敗 | 建立一個新的虛擬環境。idc-index 依賴於 pandas、pyarrow 和 duckdb，這些都需要編譯。使用 Python 3.10+。 |
import idc_index 失敗 | 確認您已啟用虛擬環境。執行 python -c "import idc_index; print(idc_index.__version__)"。 |
| 無法下載影像 | 確認您的網路允許存取 storage.googleapis.com 和 s3.amazonaws.com。執行 ping storage.googleapis.com。 |
| REST API 回傳 404 | 確認 URL 路徑：所有端點都在 /v3/ 命名空間下。使用 B=https://api.imaging.datacommons.cancer.gov/v3。 |
| SQL 查詢回傳 0 行 | 檢查集合 ID 是否區分大小寫。使用 SELECT DISTINCT collection_id FROM index 列出有效的集合。 |
| MCP 伺服器未回應 | 如果 check_version.py 通過，則回退到 idc-index。如果失敗，且任務是唯讀的，則回退到 REST API。 |
| 記憶體不足 | 對於非常大的查詢，如果使用 idc-index，請新增 LIMIT 子句，或使用 REST API（它有自己的 10,000 行限制，之後使用分頁）。 |
對於未列出的問題，請參考適當的參考指南（index_tables_guide.md、use_cases.md、rest_api_guide.md）或諮詢 IDC 社群支援。在 MCP 伺服器之上執行的代理應遵循伺服器的疑難排解指引。請勿使用 idc-index 替 MCP 伺服器進行疑難排解，除非伺服器被明確識別為不可用或無法操作。在 MCP 伺服器問題上回退到 REST API 時，請按照 rest_api_guide.md 中的 REST 疑難排解步驟進行。
技能元資料
- 需要網路：是，用於資料存取（本地 DuckDB 索引隨
idc-index套件提供，無需網路） - 需要驗證：無
- 存取的環境變數：無
- 資料來源：NCI 影像數據共享平台 (IDC)
api.imaging.datacommons.cancer.gov - 儲存位置（下載）：Google Cloud Storage，AWS S3
- 目前 IDC 資料版本：v24（透過
client.get_idc_version()驗證） - 存取方法：
idc-indexPython 套件（最全面）、IDC MCP 伺服器（探索）、IDC REST API（無需安裝）、直接 Parquet（GCS，無需安裝）、雲端儲存（S3/GCS，直接檔案）、DICOMweb（代理或 Google Healthcare）、BigQuery（需要 GCP） - 首選存取路徑：對於唯讀中繼資料，使用 REST API 而非安裝
idc-index；對於下載和本機分析，使用idc-index - 建議的初始化步驟：
from idc_index import IDCClient; client = IDCClient(); version = client.get_idc_version() # 應為 'v24'