Imaging Data Commons

¿Qué hace Imaging Data Commons?

Descripción general

Consulta y descarga datos públicos de imágenes oncológicas del National Cancer Institute Imaging Data Commons (IDC). No se requiere autenticación para el acceso a los datos.

Acceso a red esperado: Los metadatos de IDC son accesibles de tres maneras: un índice DuckDB local incluido con el paquete Python idc-index (sin red), o el servicio IDC alojado a través de MCP o REST (api.imaging.datacommons.cancer.gov, sin autenticación). Las descargas de archivos usan GCS público (storage.googleapis.com) y AWS S3 (s3.amazonaws.com) — no requieren autenticación. El acceso DICOMweb usa el proxy público de IDC (proxy.imaging.datacommons.cancer.gov, sin autenticación) o la API de Google Cloud Healthcare (healthcare.googleapis.com, requiere autenticación GCP). Las consultas opcionales a BigQuery (bigquery.googleapis.com) también requieren autenticación GCP. Esta habilidad no accede a ninguna credencial o variable de entorno.

Versión actual de datos IDC: v24 (siempre verificar — consulte Mejores prácticas)

Elija la ruta de acceso primero. No hay una única ruta predeterminada: la ruta correcta más económica depende de la sesión y la tarea.

1. ¿La sesión ya tiene el servidor MCP de IDC? Enrute el descubrimiento y los metadatos allí — consulte Servidor MCP de IDC.
2. De lo contrario, ¿está instalado idc-index? Ejecute python scripts/check_version.py. Si pasa, use idc-index para todo.
3. No está instalado, y la tarea es solo metadatos de solo lectura — ¿conteos, valores de atributos, búsquedas de colecciones, SQL con menos de 10 000 filas, licencias, citas, URL de visores? Use la API REST con curl; no instale nada. La instalación cuesta ~77 MB de datos de índice empaquetados más pandas, pyarrow y duckdb, que una pregunta de metadatos no necesita. Consulte Opciones de acceso a datos.
4. No está instalado, y la tarea necesita más que metadatos — descarga de archivos, pandas o trazado, pydicom/SimpleITK, mosaico de patología, resultados de más de 10 000 filas, o un script con versión fija que el usuario re-ejecuta. Instale idc-index: check_version.py sale con código no cero e imprime el comando de instalación exacto para el intérprete en ejecución. Prefiera un entorno virtual, luego reinicie Python.

idc-index (GitHub) sigue siendo la ruta más capaz y la única que mueve bytes de imagen; la regla es simplemente no pagar por ella antes de que la tarea lo requiera. check_version.py nunca instala nada por sí mismo — también indica una versión más reciente de idc-index o de la habilidad cuando existe.

Configuración para la ruta idc-index:

from idc_index import IDCClient
client = IDCClient()

# Verificar la versión de datos IDC (debería ser "v24")
print(f"Versión de datos IDC: {client.get_idc_version()}")

Flujo de trabajo principal: consultar metadatos con client.sql_query() → descargar con client.download_from_selection() → visualizar con client.get_viewer_URL(). Los ejemplos en Python a continuación asumen este client; Opciones de acceso a datos tiene los equivalentes REST. Para la escala actual de datos, ejecute la consulta resumen en references/sql_patterns.md o GET /v3/stats.

Servidor MCP de IDC

IDC opera un servidor MCP alojado en https://api.imaging.datacommons.cancer.gov/mcp (HTTP streamable, sin autenticación). Donde esté disponible, complementa — no reemplaza — el flujo de trabajo de idc-index a continuación.

Identifíquelo por el recurso MCP idc://guide, o por tres o más de los nombres de herramientas build_cohort, get_cohort_urls, list_analysis_results y get_idc_version. Nombres genéricos como run_sql no son evidencia por sí solos. Si la identificación es ambigua, use idc-index.

Si esta sesión tiene el servidor, trátelo como autoridad para descubrimiento y metadatos — versión IDC, conteos, valores de atributos, construcción de cohortes, SQL de metadatos — y siga las propias instrucciones del servidor en lugar de derivarlas de este archivo. Su versión de datos es la que el servidor informe: llame a get_idc_version en lugar de confiar en la versión fijada en este archivo.

Vuelva aquí para lo que el servidor no hace: descargar archivos, análisis local con pandas/notebooks, DICOMweb, BigQuery, mosaico de patología digital y scripts reproducibles. Realice la transición pasando SeriesInstanceUID desde el servidor a client.download_from_selection(...), y ejecute scripts/check_version.py en ese punto.

Si no está disponible, el servicio idéntico es accesible sin configuración como API REST en https://api.imaging.datacommons.cancer.gov/v3 — úselo para metadatos de solo lectura en lugar de instalar idc-index, según la puerta de enrutamiento en Descripción general. Sugiera conectar el servidor MCP como máximo una vez, solo para descubrimiento interactivo repetido, y nunca cambie la configuración del usuario usted mismo.

Consulte references/mcp_guide.md para el inventario de herramientas, patrones de transición y notas por host.

Cuándo usar esta habilidad

• Encontrar imágenes de radiología (TC, RM, PET) o patología (microscopía de portaobjetos) disponibles públicamente
• Seleccionar subconjuntos de imágenes por tipo de cáncer, modalidad, sitio anatómico u otros metadatos
• Descargar datos DICOM de IDC
• Verificar licencias de datos antes de usarlos en investigación o aplicaciones comerciales
• Visualizar imágenes médicas en un navegador sin software visor DICOM local

Navegación rápida

A continuación: las reglas de enrutamiento MCP/REST, el modelo de datos IDC, las tablas de índice y cómo se unen, los patrones principales de la API (consulta, descarga, visualización, licencia, cita), mejores prácticas y solución de problemas.

Guías de referencia (cargar bajo demanda):

Guía	Cuándo cargar
index_tables_guide.md	JOINs complejos, descubrimiento de esquemas, acceso a DataFrames
use_cases.md	Flujos de trabajo completos: conjuntos de datos de entrenamiento, descargas por lotes, lectura DICOM con pydicom/SimpleITK, integración en pipelines
sql_patterns.md	Patrones SQL rápidos para descubrimiento de filtros, anotaciones, estimación de tamaño
clinical_data_guide.md	Datos clínicos/tabulares, uniones de imágenes+clínicos, mapeo de valores
licensing_and_citation.md	Preguntas sobre uso comercial, cohortes con licencias mixtas, formatos de citas
cloud_storage_guide.md	Acceso directo a S3/GCS, control de versiones, mapeo de UUID
dicomweb_guide.md	Puntos finales DICOMweb, integración con PACS
digital_pathology_guide.md	Microscopía de portaobjetos (SM), anotaciones (ANN), flujos de trabajo de patología
bigquery_guide.md	Metadatos DICOM completos, elementos privados (requiere GCP)
cli_guide.md	Herramientas de línea de comandos (idc download, archivos de manifiesto)
parquet_access_guide.md	Consultas directas a Parquet a través de GCS (sin necesidad de instalar idc-index)
mcp_guide.md	Servidor MCP alojado de IDC: inventario de herramientas, identificación, transición a idc-index
rest_api_guide.md	API REST alojada de IDC: puntos finales, sintaxis de filtros, SQL sobre HTTP, manifiestos

Modelo de datos IDC

IDC agrega dos niveles de agrupación por encima de la jerarquía DICOM estándar (Paciente → Estudio → Serie → Instancia):

• collection_id: Agrupa pacientes por enfermedad, modalidad o enfoque de investigación (por ejemplo, tcga_luad, nlst). Un paciente pertenece exactamente a una colección.
• analysis_result_id: Identifica objetos derivados (segmentaciones, anotaciones, características radiomics) en una o más colecciones originales. Úselo para encontrar anotaciones generadas por IA o por expertos, mientras que collection_id encuentra datos de imagen originales (que pueden incluir anotaciones depositadas).

Identificadores clave para consultas:

Identificador	Alcance	Uso para
collection_id	Agrupación de conjuntos de datos	Filtrar por proyecto/estudio
PatientID	Paciente	Agrupar imágenes por paciente
StudyInstanceUID	Estudio DICOM	Agrupar series relacionadas, visualización
SeriesInstanceUID	Serie DICOM	Agrupar series relacionadas, visualización

Tablas de índice

El paquete idc-index proporciona múltiples tablas de índice de metadatos, accesibles a través de SQL o como DataFrames de pandas. La API REST expone las mismas tablas a través de GET /tables y POST /sql.

Importante: client.indices_overview es la fuente autorizada para las descripciones actuales de las tablas, las columnas disponibles y sus tipos — consúltela al escribir SQL o explorar la estructura de datos. También responde "qué tabla contiene la columna X"; consulte references/index_tables_guide.md para ese patrón de búsqueda y el descubrimiento completo del esquema.

Tablas disponibles

Siempre llame a client.fetch_index("table_name") antes de consultar cualquier tabla de índice — es seguro e idempotente para todas las tablas, incluidas las que se cargan automáticamente al inicio.

Familia	Tablas	Granularidad
Principal	index (metadatos principales para todos los datos actuales), collections_index, analysis_results_index	serie / colección / resultado de análisis
Parámetros de adquisición por modalidad	ct_index, mr_index, pt_index, contrast_index	1 fila = 1 serie de esa modalidad
Objetos derivados	seg_index, rtstruct_index, ann_index, ann_group_index	1 fila = 1 serie (o grupo de anotaciones)
Microscopía	sm_index, sm_instance_index	1 fila = 1 serie/instancia SM
Geometría, clínica, historial	volume_geometry_index, clinical_index, version_metadata_index, prior_versions_index	consulte la guía

references/index_tables_guide.md tiene el inventario completo con las columnas y el contenido de cada tabla — cárguelo cuando necesite saber qué contiene realmente una tabla especializada.

prior_versions_index es solo para reproducibilidad. Contiene series eliminadas permanentemente de IDC, sin superposición con index. Úselo solo para reproducir trabajo contra una versión anterior de IDC. NO lo use para preguntas de historial de versiones o "qué hay de nuevo" — esas usan series_init_idc_version / series_revised_idc_version en la tabla principal index, que no son equivalentes a min_idc_version / max_idc_version de esta tabla.

Unir tablas

SeriesInstanceUID es la clave de unión universal para todas las tablas especializadas a nivel de serie: 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. Siempre únalas con index en SeriesInstanceUID. Las excepciones a continuación usan nombres de columna diferentes.

Columna de unión	Tablas	Caso de uso
collection_id	index, prior_versions_index, collections_index, clinical_index	Vincular serie a metadatos de colección o datos clínicos
analysis_result_id	index, analysis_results_index	Vincular serie a metadatos de resultados de análisis (anotaciones, segmentaciones)
source_DOI	index, analysis_results_index	Vincular por DOI de publicación
segmented_SeriesInstanceUID	seg_index → index	Vincular segmentación a su serie de imagen de origen (seg_index.segmented_SeriesInstanceUID = index.SeriesInstanceUID)
referenced_SeriesInstanceUID	ann_index → index, rtstruct_index → index	Vincular anotación o RTSTRUCT a su serie de imagen de origen

Nota: subjects, updated y description aparecen en múltiples tablas pero tienen significados diferentes (conteos vs identificadores, contextos de actualización diferentes). Unir prior_versions_index con index en SeriesInstanceUID siempre devuelve cero filas — consulte la advertencia anterior.

Para ejemplos detallados de uniones, patrones de descubrimiento de esquemas, referencia de columnas clave y acceso a DataFrames, consulte references/index_tables_guide.md.

Acceso a datos clínicos

Los atributos clínicos (no de imagen) — estadificación, demografía, terapia — residen en tablas por colección. client.fetch_index("clinical_index") carga el diccionario que mapea columnas a colecciones; client.get_clinical_table(name) devuelve una tabla como DataFrame.

Consulte references/clinical_data_guide.md para el flujo de trabajo de descubrimiento, mapeo de valores codificados y unión de datos clínicos con imágenes.

Opciones de acceso a datos

Método	Autenticación	Mejor para	Referencia
idc-index	No	Descargas, análisis con pandas, consultas ilimitadas — la ruta más capaz	Este documento
Servidor MCP de IDC	No	Descubrimiento, construcción de cohortes, metadatos cuando la sesión ya lo tiene	mcp_guide.md
API REST de IDC	No	Metadatos sin instalación, desde cualquier lenguaje o shell — el valor predeterminado cuando idc-index está ausente	rest_api_guide.md
Parquet directo (GCS)	No	Consultas con versión fija, o resultados más allá del límite de filas de REST	parquet_access_guide.md
Almacenamiento en la nube (S3/GCS)	No	Acceso directo a archivos, transferencia masiva, pipelines personalizados	cloud_storage_guide.md
DICOMweb a través de proxy IDC	No	Integración con herramientas y PACS; cuota diaria, por lo tanto, pruebas y uso moderado	dicomweb_guide.md
DICOMweb a través de Google Healthcare	Sí (GCP)	La misma API DICOMweb a volumen de producción, sin la cuota del proxy	dicomweb_guide.md
SlicerIDCBrowser	No	Visualización y análisis 3D en 3D Slicer	https://github.com/ImagingDataCommons/SlicerIDCBrowser
BigQuery	Sí (GCP)	Metadatos DICOM completos, elementos privados, medidas SR — último recurso	bigquery_guide.md

El Portal IDC (https://portal.imaging.datacommons.cancer.gov/) es solo interactivo — exploración basada en navegador, selección manual de cohortes y descarga. A diferencia de todas las opciones anteriores, no tiene interfaz programática, por lo tanto, dirija a un usuario allí para navegar o hacer clic a través de los datos ellos mismos; nunca lo use como un paso en un script o flujo de trabajo.

API REST: la ruta de metadatos sin instalación

https://api.imaging.datacommons.cancer.gov/v3, sin autenticación: descubrimiento, conteos de cohortes y manifiestos, SQL de solo lectura, tablas clínicas, URL de visores, licencias, citas. Es el mismo servicio que el servidor MCP a través de HTTP simple, por lo que no necesita configuración. Nunca mueve bytes de imagen — cambie a idc-index para descargar, obtener un DataFrame o para resultados de más de 10 000 filas.

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"   # valores de filtro reales, con conteos
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"}}}'

Uso principal

1. Consulta de metadatos

SQL con idc-index (cualquier tamaño de resultado):

# Obtener todas las colecciones con su número de series
df = client.sql_query("""
  SELECT collection_id, COUNT(*) as series_count
  FROM index
  GROUP BY collection_id
  ORDER BY series_count DESC
""")

SQL a través de la API REST (hasta 10 000 filas):

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"}'

Descubrimiento de filtros (valores de atributos):

curl -s "$B/attributes/CollectionLongName/values?q=cancer"

Siempre devuelve conteos y permita al usuario elegir valores reales en lugar de adivinar.

2. Descarga de archivos

# Descargar todas las series de una colección
manifest = client.get_manifest(collection_id="nlst")
client.download_from_selection(manifest)

# Descargar una lista de SeriesInstanceUID
euids = ["1.2.840.113619.2.55.3.604688.12345", ...]
manifest = client.get_manifest(seriesInstanceUID=euids)
client.download_from_selection(manifest, downloadDir="./idc_data")

También son posibles descargas de solo manifiesto: dl_only_manifest=True genera archivos "/path/to/manifest_*.tsv".

3. Visualización

URL del visor OHIF:

# Obtener URL del visor para la primera serie
series_df = client.sql_query("SELECT SeriesInstanceUID FROM index LIMIT 1")
suid = series_df["SeriesInstanceUID"].iloc[0]
viewer_url = client.get_viewer_URL(suid)
print(f"Ver en visor IDC: {viewer_url}")

API REST (múltiples UIDs):

curl -s $B/viewer -H 'content-type: application/json' \
  -d '{"seriesInstanceUID":["1.2.840.113619.2.55.3.604688.12345"]}'

4. Verificación de licencias

# Obtener licencias para todas las colecciones
df_lic = client.sql_query("""
  SELECT DISTINCT c.collection_id, c.license, c.license_url
  FROM index i
  JOIN collections_index c ON i.collection_id = c.collection_id
""")

# Verificar si una colección permite uso comercial
df_nsclc = client.sql_query("""
  SELECT license, license_url
  FROM collections_index
  WHERE collection_id = 'nsclc_radiomics'
""")

5. Citas

citations = client.sql_query("""
  SELECT DISTINCT c.collection_id, c.doi, c.citation, c.TCIA_Links
  FROM index i
  JOIN collections_index c ON i.collection_id = c.collection_id
""")

Mejores prácticas

1. Siempre verifique get_idc_version() antes de escribir consultas; los nombres de las colecciones, los esquemas de las tablas y los rangos de fechas cambian con cada versión.
2. Use el filtrado más restrictivo primero en las consultas SQL para mantener bajos los tamaños de los resultados intermedios.
3. Vuelva a verificar las licencias antes de cualquier uso en investigación o comercial — diferentes colecciones tienen diferentes condiciones.
4. Conecte el servidor MCP como máximo una vez, solo para descubrimiento interactivo repetido; no cambie la configuración del usuario usted mismo.
5. La ruta REST sin instalación es la opción correcta para preguntas rápidas de metadatos; no instale idc-index a menos que necesite descargar imágenes o ejecutar análisis más pesados.
6. Para trabajo reproducible, fije la versión de idc-index y la versión de datos IDC (v24).
7. Prefiera Python para tareas que requieren manipulación de datos (pandas, DICOM, trazado); la API REST es mejor para descubrimiento y verificación rápidos.
8. Cuando use download_from_selection(), especifique downloadDir para organizar las descargas y verifique el espacio en disco.

Solución de problemas

Problema	Causa probable	Solución
idc-index no instalado	Paquete faltante	Ejecute python scripts/check_version.py para obtener el comando de instalación
Error de autenticación en la API REST	Token faltante	La API REST pública no requiere autenticación; verifique la URL
La consulta SQL devuelve 0 filas	Nombre de colección o valor de filtro incorrecto	Use GET /attributes/CollectionID/values para encontrar valores válidos
La descarga falla con error de permisos	Ruta de descarga no escribible	Especifique downloadDir con permisos de escritura
get_viewer_URL() devuelve None	SeriesInstanceUID no válido o no es de imagen	Verifique que el UID exista en index con una consulta SQL
El servidor MCP no responde	El servidor puede estar en mantenimiento	Vuelva a intentar más tarde o use la API REST como alternativa

Referencias

• Documentación IDC: https://learn.canceridc.dev/
• Portal IDC: https://portal.imaging.datacommons.cancer.gov/
• Repositorio GitHub de IDC-Index: https://github.com/imagingdatacommons/idc-index
• Foro de discusión: https://discourse.canceridc.dev/
• Documentación DICOMweb: https://learn.canceridc.dev/dicomweb