imaging-data-commons

Imaging Data Commons

概要

国立がん研究所 Imaging Data Commons（IDC）から公開がん画像データのクエリとダウンロードを行います。データアクセスに認証は必要ありません。

想定されるネットワークアクセス： IDCメタデータには3つの方法でアクセスできます。idc-index Pythonパッケージに同梱のローカルDuckDBインデックス（ネットワーク不要）、またはホスト型IDCサービスをMCPまたはREST経由（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（常に確認してください。ベストプラクティスを参照）

最初にアクセス経路を選択してください。 単一のデフォルトはありません。最適な経路はセッションとタスクに依存します。

1. セッションに既にIDC MCPサーバーがある場合？ ディスカバリとメタデータはそこにルーティングします。IDC MCPサーバーを参照。
2. そうでない場合、idc-indexがインストールされていますか？ python scripts/check_version.pyを実行します。成功した場合は、すべての処理にidc-indexを使用します。
3. インストールされておらず、タスクが読み取り専用メタデータ（件数、属性値、コレクション検索、10,000行未満のSQL、ライセンス、引用、ビューアURL）の場合？ curlでREST APIを使用してください。何もインストールしないでください。インストールには約77MBのパッケージ化されたインデックスデータに加えてpandas、pyarrow、duckdbが必要であり、メタデータの質問には不要です。データアクセスオプションを参照。
4. インストールされておらず、タスクがメタデータ以上のもの（ファイルダウンロード、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はホスト型MCPサーバーをhttps://api.imaging.datacommons.cancer.gov/mcp（ストリーム可能HTTP、認証不要）で運用しています。利用可能な場合、これは以下のidc-indexワークフローを補完します（置き換えるものではありません）。

識別方法： MCPリソースidc://guide、またはツール名build_cohort、get_cohort_urls、list_analysis_results、get_idc_versionのうち3つ以上。run_sqlのような汎用的な名前はそれ自体では証拠になりません。識別が不明な場合はidc-indexを使用してください。

このセッションにサーバーがある場合、 ディスカバリとメタデータ（IDCバージョン、件数、属性値、コホート構築、メタデータSQL）については信頼できる情報源として扱い、このファイルから再導出するのではなく、サーバー自身の指示に従ってください。データバージョンはサーバーが報告するものです。get_idc_versionを呼び出し、このファイルに固定されたバージョンに依存しないでください。

サーバーが行わないことについてはここに戻ってください：ファイルのダウンロード、ローカルpandas/ノートブック解析、DICOMweb、BigQuery、デジタル病理タイル処理、再現可能なスクリプト。サーバーからSeriesInstanceUIDをclient.download_from_selection(...)に渡し、その時点でscripts/check_version.pyを実行して引き継ぎます。

利用できない場合、 同一のサービスは構成なしでREST APIとしてhttps://api.imaging.datacommons.cancer.gov/v3で利用可能です。概要のルーティング条件に従い、idc-indexをインストールせずに読み取り専用メタデータに使用してください。MCPサーバーの接続は、繰り返しのインタラクティブなディスカバリのためだけに最大1回提案し、ユーザーの設定を自分で変更しないでください。

ツール一覧、引き継ぎパターン、ホスト別の注意事項については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階層（患者→検査→シリーズ→インスタンス）の上に2つのグループ化レベルを追加します：

• collection_id：疾患、モダリティ、または研究目的で患者をグループ化します（例：tcga_luad、nlst）。患者は厳密に1つのコレクションに属します。
• analysis_result_id：1つ以上の元のコレクションにわたる派生オブジェクト（セグメンテーション、アノテーション、ラジオミクス特徴量）を識別します。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行 = そのモダリティの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）のユニバーサル結合キーです。これらは常に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は複数のテーブルに出現しますが、異なる意味を持ちます（件数と識別子、異なる更新コンテキスト）。prior_versions_indexをindexにSeriesInstanceUIDで結合すると常にゼロ行が返されます。上記の警告を参照してください。

詳細な結合例、スキーマ発見パターン、キー列リファレンス、DataFrameアクセスについてはreferences/index_tables_guide.mdを参照してください。

臨床データアクセス

臨床（非画像）属性（病期、人口統計、治療）はコレクションごとのテーブルにあります。client.fetch_index("clinical_index")は列をコレクションにマッピングする辞書をロードします。client.get_clinical_table(name)は1つのテーブルをDataFrameとして返します。

発見ワークフロー、コード値マッピング、臨床データと画像の結合についてはreferences/clinical_data_guide.mdを参照してください。

データアクセスオプション

メソッド	認証	最適な用途	リファレンス
idc-index	不要	ダウンロード、pandas解析、無制限クエリ — 最も高性能な経路	このドキュメント
IDC MCPサーバー	不要	セッションに既にある場合のディスカバリ、コホート構築、メタデータ	mcp_guide.md
IDC REST API	不要	インストール不要のメタデータ、任意の言語またはシェルから — 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で提供するため、構成は不要です。画像バイトは転送しません。ダウンロード、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"   # 実際のフィルタ値、件数付き
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 '{"filter":{"Modality":{"eq":"CT"}}}'
curl -s $B/cohort/manifest -H 'content-type: application/json' \
  -d '{"filter":{"collection_id":{"eq":"tcga_luad"}},"format":"tsv"}'
curl -s $B/viewer-url -H 'content-type: application/json' \
  -d '{"SeriesInstanceUID":"1.3.6.1.4.1.9328.50.4.1"}'
curl -s $B/license -H 'content-type: application/json' \
  -d '{"collection_id":"tcga_luad"}'
curl -s $B/citation -H 'content-type: application/json' \
  -d '{"collection_id":"tcga_luad"}'
curl -s $B/clinical -H 'content-type: application/json' \
  -d '{"collection_id":"tcga_luad"}'

完全なフィルタ構文、エラー処理、ページネーションについてはreferences/rest_api_guide.mdを参照してください。

コアAPIパターン

すべての例はfrom idc_index import IDCClient; client = IDCClient()が完了していることを前提としています（check_version.pyで確認）。RESTに相当するものについてはrest_api_guide.mdを参照してください。

1. メタデータのクエリ

# コレクションの列挙
collections = client.sql_query("SELECT * FROM collections_index")

# モダリティ別のシリーズ数
counts = client.sql_query("""
  SELECT collection_id, Modality, COUNT(*) n
  FROM index
  GROUP BY 1, 2
  ORDER BY n DESC
  LIMIT 10
""")

# フィルタリングと結合
sql = """
  SELECT c.collection_id, c.name, i.Modality, i.SeriesInstanceUID
  FROM index i
  JOIN collections_index c ON i.collection_id = c.collection_id
  WHERE c.collection_id = 'nlst' AND i.Modality = 'CT'
  LIMIT 5
"""
results = client.sql_query(sql)

2. データのダウンロード

# 選択したシリーズのダウンロード
client.download_from_selection(
  seriesInstanceUID=["1.3.6.1.4.1.9328.50.4.1", "1.3.6.1.4.1.9328.50.4.2"],
  downloadDir="./idc_data",
  dryRun=False
)

# SQL結果からダウンロードに。SeriesInstanceUIDの列が必要
client.download_from_selection(
  seriesInstanceUID=client.sql_query(
    "SELECT SeriesInstanceUID FROM index WHERE collection_id='tcga_luad' AND Modality='CT' LIMIT 2"
  ),
  downloadDir="./idc_data",
  dryRun=True  # 実際のダウンロードの前に確認
)

downloadDirが存在しない場合は作成されます。

3. データの可視化

# ブラウザビューアのURLを取得
url = client.get_viewer_URL(SeriesInstanceUID)
print(f"ブラウザで開く：{url}")

4. ライセンスの確認

# コレクションのライセンスを取得
license_info = client.get_licenses(collection_id="tcga_luad")
print(f"ライセンス：{license_info}")

# すべてのコレクションのライセンス一覧
all_licenses = client.sql_query("SELECT collection_id, license FROM collections_index")

商用利用の質問と混合ライセンスコホートについてはreferences/licensing_and_citation.mdを参照してください。

5. データの引用

# 特定のコレクションの引用を取得
citation = client.get_citation(collection_id="tcga_luad")
print(citation)

ベストプラクティス

1. アクセス経路を検証する： 以下の順序で試す（1）MCPサーバーがセッションにあるか？（2）idc-indexはテストに合格するか？（3）REST APIで十分か？（4）それ以外はidc-indexをインストールする
2. データバージョンを確認する： コードや分析でIDCデータに関する仮定をする前にclient.get_idc_version()を呼び出し、このファイル内のバージョン宣言と照らし合わせて矛盾をチェックする。このファイルのバージョンが古い可能性がある。 常に確認する。
3. ダウンロードにはdryRun=Trueを使用する： まず確認してから実際のダウンロードを行う
4. SLURM/並列環境： client.download_from_selection()は内部でmultiprocessingを使用するため、SLURMやSun Grid Engineなどのスケジューラ共有環境では予期しないファイルディスクリプタの枯渇が発生する可能性がある。その場合はclient.download_from_selection(..., workers=1)を使用するか、モジュールのロード前にOMP_NUM_THREADS=1を設定する。
5. 大きな結果： 100,000行を超える結果のSQLクエリにはclient.sql_query(sql, use_index_cache=False)を使用する。これにより結果はCSVとしてストリーミングされ、DataFrameに読み込まれる（メモリは節約されるが、計算は遅くなる）。
6. バージョン固定： IDCデータのバージョンは変更される可能性がある。pinned-versionブランチを使用するか、依存関係のidc_indexバージョンを固定する。
7. 効率的なクエリ： 不要なJOINやワイルドカードSELECT *を避ける。代わりに必要な列のみを選択する。REST SQLエンドポイントでは、返される行数（LIMITを使用）と列数を制限する。

トラブルシューティング

問題	解決策
ImportError: No module named idc_index	idc-indexがインストールされていない。scripts/check_version.pyを実行してインストールコマンドを取得するか、REST APIを使用する
duckdb.IOException またはメモリエラー	大きな結果にはclient.sql_query(sql, use_index_cache=False)を使用する。小さなLIMITで始め、徐々に増やす
ダウンロード速度が遅い	workersパラメータを増やす（デフォルト：5）。ネットワーク制限に注意
データバージョンの不一致	client.get_idc_version()を実行する。idc-indexをアップグレードするか、データバージョンを切り替える
REST API 400エラー	SQL構文とテーブル名を確認する。POST /sqlを使用する際はcontent-type: application/jsonを含める
REST API 413エラー	リクエストペイロードが大きすぎる。フィルタを小さくするか、直接Parquetアクセスを使用する
check_version.pyがスタックする	--forceフラグを付けて再実行する
GCS/S3 403エラー	公開データのため、認証は不要。リージョンまたはネットワークの問題を確認する

リファレンス

ドキュメント	場所
idc-index	https://github.com/imagingdatacommons/idc-index
IDCポータル	https://portal.imaging.datacommons.cancer.gov/
IDCドキュメント	https://learn.canceridc.dev/
IDCフォーラム	https://discourse.canceridc.dev/
IDC MCPサーバー	api.imaging.datacommons.cancer.gov/mcp（ストリーム可能HTTP）
IDC REST API	api.imaging.datacommons.cancer.gov/v3