imaging-data-commons

イメージングデータコモンズ

概要

idc-index Python パッケージを使用して、米国国立がん研究所のイメージングデータコモンズ（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 階層（Patient → Study → Series → Instance）の上位に、2 つのグループ化レベルが追加されています。

• collection_id：疾患、モダリティ、研究テーマなどに基づいて患者をグループ化します（例：tcga_luad、nlst）。患者は必ず1つのコレクションに属します。
• analysis_result_id：1つ以上の元コレクションにまたがる派生オブジェクト（セグメンテーション、アノテーション、ラジオミクス特徴量）を識別します。

元の画像データを探すには collection_id を使用します。画像とともに登録されたアノテーションが含まれる場合があります。AI が生成したアノテーションや専門家によるアノテーションを探すには analysis_result_id を使用します。

検索に使用する主な識別子：

識別子	範囲	用途
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 セグメンテーションシリーズ	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 経由でのツール連携
クラウドストレージ（S3/GCS）	いいえ	ファイルへの直接アクセス、一括ダウンロード、カスタムパイプライン

クラウドストレージの構成

IDC は、AWS S3 と Google Cloud Storage の間でミラーリングされたパブリッククラウドストレージバケットに、すべての DICOM ファイルを保持しています。ファイルはバージョン管理に対応するため、DICOM UID ではなく CRDC UUID で整理されています。

バケット（AWS / GCS）	ライセンス	内容
idc-open-data / idc-open-data	商用利用の制限なし	IDC データの >90%
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 データは、PACS システムおよび DICOMweb 対応ツールとの連携に利用できる DICOMweb インターフェース（Google Cloud Healthcare API 実装）経由で利用できます。

エンドポイント	認証	使用例
パブリックプロキシ	いいえ	テスト、中程度のクエリ、日次クォータ
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 が 1 行に 1 つ含まれており、次の方法で用意できます。

• コホートの選択後に IDC ポータルからエクスポートする
• 再現可能なデータアクセスのために共同研究者と共有する
• クエリ結果からプログラムで生成する

形式（1 行に S3 URL を 1 つ）：

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 Study に複数の Series（例：1 回の MRI セッションで撮影した T1、T2、DWI シーケンス）が含まれる場合は、Study 単位での表示が便利です。

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 Terms and Conditions）。

重要： 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：Study UID で絞り込みます。
• seriesInstanceUID：Series 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 句を使い、長時間のダウンロードを避けてデータ構造を把握してください
• 単純なクエリにはミニインデックスを使用する - 包括的なメタデータまたは複雑な JOIN が必要な場合に限り、BigQuery を使用してください
• dirTemplate でダウンロードを整理する - %collection_id/%PatientID/%Modality のような、意味のあるディレクトリ構成を使用してください
• クエリ結果をキャッシュする - 再クエリを避け、再現性を確保するために、DataFrame を CSV ファイルに保存してください
• 先にサイズを見積もる - ダウンロード前にコレクションのサイズを確認してください。テラバイト単位のコレクションもあります！
• マニフェストを保存する - 再現性とデータの来歴を確保するため、クエリ結果と 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 を参照してください

問題：シリーズ UID が見つからない、またはデータが返されない

• 原因： UID の入力ミス、現在の IDC バージョンにデータがない、またはフィールド名が間違っています
• 解決策：
  • データが現在の IDC バージョンに含まれているか確認します（古いデータの一部は非推奨になっている場合があります）
  • まず LIMIT 5 を使ってクエリをテストします
  • メタデータスキーマのドキュメントでフィールド名を確認します

問題：ダウンロードした DICOM ファイルを開けない

• 原因： ダウンロードしたファイルが破損しているか、ビューアーに互換性がありません
• 解決策：
  • DICOM オブジェクトの種類（Modality 属性と SOPClassUID 属性）を確認します。オブジェクトの種類によっては専用ツールが必要です
  • ファイルの整合性を確認します（ファイルサイズをチェックします）
  • pydicom を使って検証します：pydicom.dcmread(file, force=True)
  • 別の DICOM ビューアー（3D Slicer、Horos、RadiAnt、QuPath）を試します
  • シリーズを再ダウンロードします

一般的な SQL クエリパターン

次のような、すぐに参照できる SQL クエリパターンについては references/sql_patterns.md を参照してください。

• フィルター値の確認（モダリティ、身体部位、メーカー）
• アノテーションおよびセグメンテーションのクエリ（seg_index、ann_index の結合を含む）
• スライド顕微鏡のクエリ（sm_index パターン）
• ダウンロードサイズの推定
• 臨床データのリンク

セグメンテーションとアノテーションの詳細については、references/digital_pathology_guide.md も参照してください。

関連スキル

次のスキルは、下流の分析と可視化において IDC のワークフローを補完します。

DICOM 処理

• pydicom - ダウンロードした DICOM ファイルを読み取り、書き込み、操作します。ピクセルデータの抽出、メタデータの読み取り、匿名化、形式変換に使用します。IDC の放射線医学データ（CT、MR、PET）を扱ううえで不可欠です。

病理学とスライド顕微鏡

DICOM 互換ツール（highdicom、wsidicom、TIA-Toolbox、Slim viewer）については、references/digital_pathology_guide.md を参照してください。

メタデータの可視化

• 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）