imaging-data-commons

Imaging Data Commons

概要

国立がん研究所 Imaging Data Commons（IDC）から公開がん画像データをクエリしてダウンロードします。データアクセスに認証は不要です。

想定されるネットワークアクセス: IDC のメタデータには 3 つの方法で到達できます — 同梱のローカル 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 経路であり、クエリとダウンロードのヘルパーが 1 つのクライアントにまとまっています。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 サーバーを運用しています （ストリーミング可能な 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、デジタル病理のタイリング、再現可能なスクリプトです。 サーバーから client.download_from_selection(...) に SeriesInstanceUIDs を渡してハンドオフし、 その時点で scripts/check_version.py を実行してください。

利用できない場合は、同一のサービスが https://api.imaging.datacommons.cancer.gov/v3 で REST API として設定なしで利用できます。概要 のルーティングゲートに従い、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 階層（Patient → Study → Series → Instance）の上に 2 つのグループ化レベルを追加します。

• collection_id: 疾患、モダリティ、または研究テーマごとに患者をグループ化します（例: tcga_luad、nlst）。(collection_id, PatientID) を患者キーとして扱ってください。PatientID がグローバルに一意であるとは仮定しないでください。
• 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 には過去のシリーズバージョンが含まれます。これには、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。これらは常に SeriesInstanceUID で index に結合してください。以下の例外では、異なる列名を使用します。

結合列	テーブル	用途
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) は、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 との統合、1 日あたりのクォータがあるため、テストおよび中程度の利用に適しています	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"   # 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"]}}}'

フィルターオブジェクトは常に filters の下に置きます — cohort/counts、cohort/manifest、 cohort/manifest.txt、licenses、citations のいずれでも同様です。裸のフィルターや認識されないキーは 修正方法を示す 422 になります。フィルターなしでシリーズを列挙するリクエストは 400 になり、アーカイブ全体が返ることはありません。 フィルター適用済みの JSON レスポンスは filters_applied と warnings（マニフェストでは counts の内部）をエコーします — これらを読んでください。サーバーが破棄した述語がそこに示されているからです。したがって、カウントがゼロで warnings が空なら、それは値の大文字小文字が間違っていたのではなく、フィルターが何にも一致しなかったことを意味します。大文字小文字の誤りはその旨を伝える警告を生成します。

POST /sql は、idc-index が公開するテーブルおよび clinical.<table> に対して、読み取り専用の SELECT/WITH を 1 つ受け取ります。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 が省略される可能性があり、まったく一致しない選択では例外が発生します — したがって、idc-index をアップグレードするか（正しいコマンドについては scripts/check_version.py を実行してください）、s5cmd --no-sign-request でバケットから直接転送してください。

エンドポイントリファレンス、フィルターの根拠、制限、およびマニフェストベースのダウンロードフローについては、references/rest_api_guide.md を参照してください。

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

すべての DICOM ファイルは、AWS S3 と GCS の間でミラーリングされた公開バケットに存在し、バージョニングをサポートするために（DICOM UID ではなく）CRDC UUID によって整理され、<crdc_series_uuid>/<crdc_instance_uuid>.dcm という形式になっています。匿名アクセスで AWS CLI、gsutil、または s5cmd を使用すれば無料（エグレス料金なし）でアクセスできます。S3 URL には series_aws_url 列を使用してください。バケット名はライセンスを確立しません。選択した各シリーズについて license_short_name をクエリしてください。バケットの完全なリストと UUID マッピングについては references/cloud_storage_guide.md を参照してください。

DICOMweb アクセス

IDC データは、PACS 統合および DICOMweb 互換ツールのために DICOMweb（Google Cloud Healthcare API）経由で利用できます。テストと中程度のクエリには公開プロキシ（認証なし、日次クォータあり）、本番ボリュームには Google Healthcare（GCP 認証）を使用します。詳細は references/dicomweb_guide.md を参照してください。

Parquet への直接アクセス

idc-index メタデータテーブルは、公開 GCS バケット（idc-index-data-artifacts）上で Parquet としても公開されており、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 パスでは、このグラウンディングは 1 回の呼び出しで済みます — GET /attributes/{attr}/values は値と件数を返し、コホートエンドポイントは大文字小文字を誤った値を空の結果ではなく warnings として報告します。

2 つのインデックスには、プライマリの index にはないキュレーションされたコレクションレベルのメタデータが含まれており、どちらも先に client.fetch_index(...) が必要です: collections_index(がん種、腫瘍部位、生物種、被験者数)と analysis_results_index(派生データセット — AI セグメンテーション、専門家アノテーション、ラジオミクス — とそのソースコレクションおよびモダリティ)です。

がん種は index ではなく collections_index.cancer_types にあります — がん種でフィルタリングするには結合が必要です:

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 ファイルのダウンロード

2 つのダウンロードメソッドは、最初の 2 つの引数の順序が逆です。 これは壊れた IDC コードの最も一般的な原因です — 思い出すのではなく確認してください:

メソッド	第 1 引数	第 2 引数	使用する場面
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 です。Google には source_bucket_location="gcs" を使用してください。0.12.5 では最も具体的なセレクターが優先されるため、交差する基準にはまず SQL を使用し、要求されたすべての UID が存在することを確認してください。

ダウンロードされたファイルは SOPInstanceUID ではなく <crdc_instance_uuid>.dcm という名前になります。 DICOM UID はファイル名ではなく、ファイルメタデータ内に保持されます。シリーズ UID については DICOM ヘッダーを読み取ってください。crdc_instance_uuid はシリーズレベルの index のカラムではありません。

idc download <collection|series-uid|manifest> --download-dir ./data はシェルから同じことを行います。dirTemplate の階層オプション(Python のデフォルト: %collection_id/%PatientID/%StudyInstanceUID/%Modality_%SeriesInstanceUID、dirTemplate="" でフラット化)、再開可能なマニフェストダウンロード、ドライランによるサイズ見積もりについては、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 スタディが複数のシリーズ(1 回の MRI セッションからの T1、T2、DWI)を保持する場合、スタディ単位で表示すると便利です。

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 スナップショットでは、サイズベースで IDC データの約 97% が CC BY（帰属表示を条件に商用利用可）、約 3% が CC BY-NC（非商用のみ）です。ライセンスはコレクションではなくシリーズに付随します — 176 の コレクションのうち 39 が複数のライセンスを持っています — そのため、実際に使用する予定の選択範囲を確認し、 各コンポーネントがそれぞれのライセンス義務を保持することに注意してください。

どちらのタスクも 3 つのアクセス経路すべてから利用できるため、セッションがすでに使用している経路を そのまま使ってください。上記のような idc-index、REST 経由の POST /v3/licenses と POST /v3/citations、 または MCP ツール get_licenses と get_citations です。完全なライセンス一覧、3 つの経路すべて、 引用フォーマット（APA、BibTeX、CSL JSON、RDF Turtle）、および公開時に含めるべき内容については references/licensing_and_citation.md を参照してください。

5. インデックスの先へ踏み込む

アクセス経路は概要にあるルーティングゲートで選択してください。上記のデータアクセスの選択肢が 完全なルーティング表です。

BigQuery に手を伸ばす前に（Google Cloud プロジェクトとアクセス権が必要です）、専用の インデックステーブルに目的の列がすでに存在しないか確認してください。client.indices_overview を検索し、 次に client.fetch_index(...) を実行してローカルで無料でクエリします。完全なインスタンスメタデータ、セグメント単位の 行、SR 測定テーブルには BigQuery またはその公開 Parquet エクスポートが必要です。これらは コンパクトな idc-index テーブルの範囲外です。

ベストプラクティス

• クエリを書く前にスキーマを確認する — client.get_index_schema('index')（キャッシュされたメタデータを読み取り、SQL は実行されません）または client.indices_overview を使用して、利用可能なすべての列とその説明を確認します。メインの index テーブルにあるバージョン追跡列 series_init_idc_version と series_revised_idc_version は、prior_versions_index に触れることなく「何が新しく、いつ追加されたか」という質問に直接答えます。
• IDC データの内容に関する質問にはインデックスを使用する - ローカルでは client.sql_query() を、HTTP 経由では POST /v3/sql を使って、IDC インデックスを直接クエリします。Web 上の情報源（リリースノート、ブログ記事、ドキュメントページ）は頻繁に古くなっており、誤った回答を生み出します。インデックスが権威ある情報源です。Web 検索が利用できる場合でも使用してください。
• セッションの開始時に 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）を使用し、ダウンロード前にコレクションのサイズを確認します — 一部のコレクションはテラバイト級です。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 シリーズ）でダウンロードしてください。--use-s5cmd-sync の再開と再試行のガイダンスについては references/cli_guide.md を参照してください

問題: BigQuery quota exceeded または請求エラー

• 原因: プロジェクトのクォータ、サンドボックスの制限、または請求設定がクエリを妨げています
• 解決策: 単純なクエリには idc-index のミニインデックスを使用してください（請求は不要です）。または、コスト最適化のヒントについては references/bigquery_guide.md を参照してください

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

• 原因: UID のタイプミス、現在の IDC バージョンにデータが存在しない、またはフィールド名が誤っている
• 解決策: まず LIMIT 5 でテストし、フィールド名を client.indices_overview と照合し、そのシリーズが現在のバージョンに含まれていることを確認してください（一部の古いデータは非推奨です）

問題: index テーブルに列が見つからない（例: SliceThickness、PixelSpacing、KVP、EchoTime、InjectedDose）

• 原因: index テーブルにはシリーズレベルのメタデータのみが含まれています。モダリティ固有の取得および再構成パラメータは専用のテーブル（ct_index、mr_index、pt_index）にあります
• 解決策: client.indices_overview でその列を検索して、どのテーブルにあるかを確認してください。このループは references/index_tables_guide.md の どのテーブルに列が含まれているかを見つける に記載されています。その後、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、スライド顕微鏡はいずれも専用のツールが必要です
• 解決策: 通常の pydicom.dcmread で Modality、SOPClassUID、転送構文を確認してください。強制パースは検証ではありません。再ダウンロードする前に、ダウンロードの完全性とデコーダー/ビューアのサポートを確認してください。force=True は、診断済みの非 Part-10 入力のために取っておいてください。

リソース

リファレンスガイドとその判断トリガーは、上記の クイックナビゲーション に記載されています。

• IDC ポータル: 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
• スキルの更新: リリースページ、リポジトリをウォッチしてください（Watch → Custom → Releases）