imagerie-donnees-communes

Imaging Data Commons

Aperçu

Interrogez et téléchargez les données d’imagerie du cancer publiques depuis le National Cancer Institute Imaging Data Commons (IDC). Aucune authentification n’est requise pour l’accès aux données.

Accès réseau attendu : Les métadonnées IDC sont accessibles de trois manières — un index local DuckDB fourni avec le paquet Python idc-index (sans réseau), ou le service IDC hébergé via MCP ou REST (api.imaging.datacommons.cancer.gov, sans authentification). Les téléchargements de fichiers utilisent GCS public (storage.googleapis.com) et AWS S3 (s3.amazonaws.com) — aucune authentification requise. L’accès DICOMweb utilise soit le proxy public IDC (proxy.imaging.datacommons.cancer.gov, sans authentification), soit l’API Google Cloud Healthcare (healthcare.googleapis.com, nécessite une authentification GCP). Les requêtes BigQuery optionnelles (bigquery.googleapis.com) nécessitent également une authentification GCP. Aucune information d’identification ou variable d’environnement n’est accédée par cette compétence.

Version actuelle des données IDC : v24 (toujours vérifier — voir Bonnes pratiques)

Choisissez d’abord le chemin d’accès. Il n’y a pas de chemin par défaut unique : le chemin le plus économique et correct dépend de la session et de la tâche.

1. La session a déjà le serveur MCP IDC ? Acheminez la découverte et les métadonnées là-bas — voir Serveur MCP IDC.
2. Sinon, idc-index est-il installé ? Exécutez python scripts/check_version.py. Si cela réussit, utilisez idc-index pour tout.
3. Pas installé, et la tâche est des métadonnées en lecture seule — comptages, valeurs d’attributs, recherches de collections, SQL de moins de 10 000 lignes, licences, citations, URLs de visualisation ? Utilisez l’API REST avec curl ; n’installez rien. L’installation coûte environ 77 Mo de données d’index empaquetées plus pandas, pyarrow et duckdb, ce dont une question de métadonnées n’a pas besoin. Voir Options d’accès aux données.
4. Pas installé, et la tâche nécessite plus que des métadonnées — téléchargement de fichiers, pandas ou tracés, pydicom/SimpleITK, pavage de pathologie, résultats de plus de 10 000 lignes, ou un script avec version figée que l’utilisateur réexécute ? Installez idc-index : check_version.py se termine avec un code non nul et imprime la commande d’installation exacte pour l’interpréteur en cours. Préférez un environnement virtuel, puis redémarrez Python.

idc-index (GitHub) reste le chemin le plus performant et le seul qui déplace des octets d’image ; la règle est simplement de ne pas payer pour cela avant que la tâche ne l’exige. check_version.py n’installe jamais rien lui-même — il signale également une version plus récente de idc-index ou de la compétence lorsqu’elle existe.

Configuration pour le chemin idc-index :

from idc_index import IDCClient
client = IDCClient()

# Vérifier la version des données IDC (devrait être "v24")
print(f"Version des données IDC : {client.get_idc_version()}")

Flux de travail de base : interroger les métadonnées avec client.sql_query() → télécharger avec client.download_from_selection() → visualiser avec client.get_viewer_URL(). Les exemples Python ci-dessous supposent ce client ; Options d’accès aux données contient les équivalents REST. Pour l’échelle actuelle des données, exécutez la requête récapitulative dans references/sql_patterns.md ou GET /v3/stats.

Serveur MCP IDC

IDC exploite un serveur MCP hébergé à https://api.imaging.datacommons.cancer.gov/mcp (HTTP streamable, sans authentification). Là où il est disponible, il complète — mais ne remplace pas — le flux de travail idc-index ci-dessous.

Identifiez-le par la ressource MCP idc://guide, ou par trois noms d’outils ou plus parmi build_cohort, get_cohort_urls, list_analysis_results et get_idc_version. Les noms génériques tels que run_sql ne sont pas une preuve suffisante à eux seuls. Si l’identification est ambiguë, utilisez idc-index.

Si cette session dispose du serveur, traitez-le comme faisant autorité pour la découverte et les métadonnées — version IDC, comptages, valeurs d’attributs, construction de cohortes, métadonnées SQL — et suivez ses propres instructions plutôt que de les redériver de ce fichier. Sa version de données est celle rapportée par le serveur : appelez get_idc_version au lieu de vous fier à la version figée dans ce fichier.

Revenez ici pour ce que le serveur ne fait pas : téléchargement de fichiers, analyse locale pandas/notebook, DICOMweb, BigQuery, pavage de pathologie numérique et scripts reproductibles. Effectuez la transition en passant les SeriesInstanceUID du serveur à client.download_from_selection(...), et exécutez scripts/check_version.py à ce moment-là.

S’il n’est pas disponible, le service identique est accessible sans configuration sous forme d’API REST à https://api.imaging.datacommons.cancer.gov/v3 — utilisez-le pour les métadonnées en lecture seule plutôt que d’installer idc-index, conformément à la règle de routage dans Aperçu. Suggérez de connecter le serveur MCP au plus une fois, uniquement pour la découverte interactive répétée, et ne modifiez jamais la configuration de l’utilisateur vous-même.

Voir references/mcp_guide.md pour l’inventaire des outils, les modèles de transition et les notes par hôte.

Quand utiliser cette compétence

• Trouver des images de radiologie (CT, IRM, TEP) ou de pathologie (microscopie de lames) publiquement disponibles
• Sélectionner des sous-ensembles d’images par type de cancer, modalité, site anatomique ou autres métadonnées
• Télécharger des données DICOM depuis IDC
• Vérifier les licences des données avant utilisation dans la recherche ou les applications commerciales
• Visualiser des images médicales dans un navigateur sans logiciel de visualisation DICOM local

Navigation rapide

Ci-dessous : les règles de routage MCP/REST, le modèle de données IDC, les tables d’index et comment les joindre, les modèles d’API de base (interroger, télécharger, visualiser, licence, citation), les bonnes pratiques et le dépannage.

Guides de référence (charger à la demande) :

Guide	Quand charger
index_tables_guide.md	JOINs complexes, découverte de schéma, accès DataFrame
use_cases.md	Flux de travail de bout en bout : jeux de données d’entraînement, téléchargements par lots, lecture DICOM avec pydicom/SimpleITK, intégration de pipeline
sql_patterns.md	Modèles SQL rapides pour la découverte de filtres, annotations, estimation de taille
clinical_data_guide.md	Données cliniques/tableaux, jointures imagerie+clinique, mappage de valeurs
licensing_and_citation.md	Questions d’utilisation commerciale, cohortes avec licences mixtes, formats de citation
cloud_storage_guide.md	Accès direct S3/GCS, versionnage, mappage UUID
dicomweb_guide.md	Points de terminaison DICOMweb, intégration PACS
digital_pathology_guide.md	Microscopie de lames (SM), annotations (ANN), flux de travail de pathologie
bigquery_guide.md	Métadonnées DICOM complètes, éléments privés (nécessite GCP)
cli_guide.md	Outils en ligne de commande (idc download, fichiers manifeste)
parquet_access_guide.md	Requêtes Parquet directes via GCS (pas d’installation idc-index nécessaire)
mcp_guide.md	Serveur MCP IDC hébergé : inventaire des outils, identification, transition vers idc-index
rest_api_guide.md	API REST IDC hébergée : points de terminaison, syntaxe de filtre, SQL sur HTTP, manifestes

Modèle de données IDC

IDC ajoute deux niveaux de regroupement au-dessus de la hiérarchie DICOM standard (Patient → Étude → Série → Instance) :

• collection_id : Regroupe les patients par maladie, modalité ou axe de recherche (ex. tcga_luad, nlst). Un patient appartient à exactement une collection.
• analysis_result_id : Identifie les objets dérivés (segmentation, annotations, caractéristiques radiomiques) à travers une ou plusieurs collections originales. Utilisez-le pour trouver des annotations générées par IA ou par des experts, tandis que collection_id trouve les données d’imagerie originales (qui peuvent elles-mêmes inclure des annotations déposées).

Identifiants clés pour les requêtes :

Identifiant	Portée	Utilisation
collection_id	Regroupement de jeux de données	Filtrage par projet/étude
PatientID	Patient	Regroupement des images par patient
StudyInstanceUID	Étude DICOM	Regroupement de séries liées, visualisation
SeriesInstanceUID	Série DICOM	Regroupement de séries liées, visualisation

Tables d’index

Le paquet idc-index fournit plusieurs tables d’index de métadonnées, accessibles via SQL ou sous forme de DataFrames pandas. L’API REST expose les mêmes tables via GET /tables et POST /sql.

Important : client.indices_overview est la source faisant autorité pour les descriptions actuelles des tables, les colonnes disponibles et leurs types — interrogez-la lors de l’écriture de SQL ou de l’exploration des structures de données. Elle répond également à « quelle table contient la colonne X » ; voir references/index_tables_guide.md pour ce modèle de recherche et la découverte complète du schéma.

Tables disponibles

Appelez toujours client.fetch_index("nom_table") avant d’interroger une table d’index — c’est sécurisé et idempotent pour toutes les tables, y compris celles chargées automatiquement au démarrage.

Famille	Tables	Granularité
Cœur	index (métadonnées principales pour toutes les données actuelles), collections_index, analysis_results_index	série / collection / résultat d’analyse
Paramètres d’acquisition par modalité	ct_index, mr_index, pt_index, contrast_index	1 ligne = 1 série de cette modalité
Objets dérivés	seg_index, rtstruct_index, ann_index, ann_group_index	1 ligne = 1 série (ou groupe d’annotations)
Microscopie	sm_index, sm_instance_index	1 ligne = 1 série SM / instance
Géométrie, clinique, historique	volume_geometry_index, clinical_index, version_metadata_index, prior_versions_index	voir le guide

references/index_tables_guide.md contient l’inventaire complet avec les colonnes et le contenu de chaque table — chargez-le lorsque vous avez besoin de savoir ce que contient réellement une table spécialisée.

prior_versions_index est uniquement pour la reproductibilité. Elle contient des séries supprimées définitivement d’IDC, sans aucun chevauchement avec index. Utilisez-la uniquement pour reproduire un travail basé sur une version précédente d’IDC. Ne l’utilisez PAS pour l’historique des versions ou les questions « quoi de neuf » — celles-ci utilisent series_init_idc_version / series_revised_idc_version dans la table index principale, qui ne sont pas équivalents à min_idc_version / max_idc_version de cette table.

Joindre des tables

SeriesInstanceUID est la clé de jointure universelle pour toutes les tables spécialisées au niveau série : 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. Joignez toujours celles-ci à index sur SeriesInstanceUID. Les exceptions ci-dessous utilisent des noms de colonnes différents.

Colonne de jointure	Tables	Cas d’utilisation
collection_id	index, prior_versions_index, collections_index, clinical_index	Lier une série aux métadonnées de collection ou données cliniques
analysis_result_id	index, analysis_results_index	Lier une série aux métadonnées de résultat d’analyse (annotations, segmentations)
source_DOI	index, analysis_results_index	Lier par DOI de publication
segmented_SeriesInstanceUID	seg_index → index	Lier une segmentation à sa série d’images source (seg_index.segmented_SeriesInstanceUID = index.SeriesInstanceUID)
referenced_SeriesInstanceUID	ann_index → index, rtstruct_index → index	Lier une annotation ou RTSTRUCT à sa série d’images source

Remarque : subjects, updated et description apparaissent dans plusieurs tables mais ont des significations différentes (comptages vs identifiants, contextes de mise à jour différents). Joindre prior_versions_index à index sur SeriesInstanceUID renvoie toujours zéro ligne — voir l’avertissement ci-dessus.

Pour des exemples détaillés de jointure, des modèles de découverte de schéma, une référence des colonnes clés et un accès DataFrame, voir references/index_tables_guide.md.

Accès aux données cliniques

Les attributs cliniques (non d’imagerie) — stadification, démographie, thérapie — résident dans des tables par collection. client.fetch_index("clinical_index") charge le dictionnaire mappant les colonnes aux collections ; client.get_clinical_table(nom) renvoie une table sous forme de DataFrame.

Voir references/clinical_data_guide.md pour le flux de travail de découverte, le mappage des valeurs codées et la jointure des données cliniques avec l’imagerie.

Options d’accès aux données

Méthode	Auth	Idéal pour	Référence
idc-index	Non	Téléchargements, analyse pandas, requêtes illimitées — le chemin le plus performant	Ce document
Serveur MCP IDC	Non	Découverte, construction de cohortes, métadonnées lorsque la session en dispose déjà	mcp_guide.md
API REST IDC	Non	Métadonnées sans installation, depuis tout langage ou terminal — le défaut en l’absence de idc-index	rest_api_guide.md
Parquet direct (GCS)	Non	Requêtes avec version figée, ou résultats dépassant la limite de lignes REST	parquet_access_guide.md
Stockage cloud (S3/GCS)	Non	Accès direct aux fichiers, transfert en masse, pipelines personnalisés	cloud_storage_guide.md
DICOMweb via proxy IDC	Non	Intégration d’outils et PACS ; quota quotidien, donc test et usage modéré	dicomweb_guide.md
DICOMweb via Google Healthcare	Oui (GCP)	La même API DICOMweb à volume de production, sans le quota du proxy	dicomweb_guide.md
SlicerIDCBrowser	Non	Visualisation et analyse 3D dans 3D Slicer	https://github.com/ImagingDataCommons/SlicerIDCBrowser
BigQuery	Oui (GCP)	Métadonnées DICOM complètes, éléments privés, mesures SR — dernier recours	bigquery_guide.md

Le portail IDC (https://portal.imaging.datacommons.cancer.gov/) est interactif uniquement — exploration via navigateur, sélection manuelle de cohortes et téléchargement. Contrairement à chaque option ci-dessus, il n’a pas d’interface programmable, donc dirigez un utilisateur vers lui pour naviguer ou cliquer sur les données lui-même ; ne l’utilisez jamais comme étape dans un script ou un flux de travail.

API REST — le chemin de métadonnées sans installation

https://api.imaging.datacommons.cancer.gov/v3, sans authentification : découverte, comptages de cohortes et manifestes, SQL en lecture seule, tables cliniques, URLs de visualisation, licences, citations. C’est le même service que le serveur MCP via HTTP simple, donc aucune configuration n’est nécessaire. Elle ne déplace jamais d’octets d’image — passez à idc-index pour télécharger, obtenir un DataFrame, ou pour des résultats de plus de 10 000 lignes.

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"   # valeurs de filtre réelles, avec comptages
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":{"collection_id":["nlst"]}}'
curl -s $B/cohort/manifest -H 'content-type: application/json' \
  -d '{"filters":{"collection_id":["nlst"]}}'
curl -s $B/collection/nlst   # métadonnées de collection
curl -s $B/collection/nlst/licenses
curl -s $B/collection/nlst/citation
curl -s $B/viewer/1.2.840.113619.2.388.3.315958.306.1455907394.171

Interrogation des métadonnées

Découverte de filtre

Question : « Quelles modalités d’imagerie sont disponibles pour le cancer du poumon dans IDC ? »

client.indices_overview répertorie les colonnes et leurs types. collections_index répertorie toutes les collections — filtrez par collection_id ou cancer_type. Les tables spécialisées (ct_index, mr_index, etc.) contiennent les paramètres d’acquisition par modalité.

# Découvrir les colonnes disponibles
print(client.indices_overview)

# Trouver les collections liées au poumon
poumon_collections = client.sql_query(
    "SELECT collection_id, description FROM collections_index WHERE lower(collection_id) LIKE '%lung%'"
)

Requête SQL de base

# Sélectionner des séries CT de TCGA-LUAD
query = """
SELECT
  SeriesInstanceUID,
  collection_id,
  Modality,
  StudyInstanceUID,
  SeriesDescription,
  SeriesNumber,
  SeriesInstanceUID
FROM
  index
WHERE
  collection_id = 'tcga_luad'
  AND Modality = 'CT'
LIMIT 10
"""
résultat = client.sql_query(query)

Requête SQL avancée avec jointure

# Sélectionner les séries CT avec volume
query = """
SELECT
  i.SeriesInstanceUID,
  i.collection_id,
  i.StudyInstanceUID,
  v.CubeSizeInMM
FROM
  index i
JOIN
  volume_geometry_index v
ON
  i.SeriesInstanceUID = v.SeriesInstanceUID
WHERE
  i.Modality = 'CT'
  AND i.collection_id = 'nlst'
LIMIT 10
"""
résultat = client.sql_query(query)

Téléchargement de fichiers

Téléchargement d’une sélection

series_uids = ["1.2.840.113619.2.388.3.315958.306.1455907394.171",
               "1.2.840.113619.2.388.3.315958.306.1455907394.172"]
client.download_from_selection(series_uids, downloadDir="./idc_data")

Téléchargement avec filtrage

# Télécharger toutes les séries CT NLST avec des cubes de taille > 100 mm
query = """
SELECT i.SeriesInstanceUID
FROM index i
INNER JOIN volume_geometry_index v ON i.SeriesInstanceUID = v.SeriesInstanceUID
WHERE i.collection_id = 'nlst' AND i.Modality = 'CT' AND v.CubeSizeInMM > 100
"""
séries = client.sql_query(query)
client.download_from_selection(séries["SeriesInstanceUID"].tolist(), downloadDir="./ct_nlst_large")

Téléchargement d’un manifeste

# Générer un manifeste de cohorte via l’API REST
curl -s $B/cohort/manifest -H 'content-type: application/json' \
  -d '{"filters":{"collection_id":["nlst"],"Modality":["CT"]}}' \
  | jq -r '.series[]' > manifest_nlst_ct.csv
# Utiliser l’outil CLI idc pour télécharger depuis le manifeste
# idc download --manifest manifest_nlst_ct.csv --download-dir ./nlst_ct

Visualisation

# Obtenir une URL de visualisation pour une étude
url = client.get_viewer_URL("1.3.6.1.4.1.14519.5.2.3.327424.1704.122319700225.1820921345.733")