Imaging Data Commons

O que Imaging Data Commons faz?

Visão Geral

Consulta e baixa dados públicos de imagem oncológica do Imaging Data Commons (IDC) do National Cancer Institute. Nenhuma autenticação é necessária para acesso aos dados.

Acesso esperado à rede: Os metadados do IDC podem ser acessados de três formas — um índice DuckDB local distribuído com o pacote Python idc-index (sem rede), ou o serviço IDC hospedado via MCP ou REST (api.imaging.datacommons.cancer.gov, sem autenticação). Downloads de arquivos usam GCS público (storage.googleapis.com) e AWS S3 (s3.amazonaws.com) — sem autenticação necessária. O acesso DICOMweb usa o proxy público do IDC (proxy.imaging.datacommons.cancer.gov, sem auth) ou a Google Cloud Healthcare API (healthcare.googleapis.com, requer autenticação GCP). Consultas opcionais ao BigQuery (bigquery.googleapis.com) também requerem autenticação GCP. Nenhuma credencial ou variável de ambiente é acessada por esta skill.

Versão Atual dos Dados IDC: v24 (sempre verifique — consulte Melhores Práticas)

Escolha o caminho de acesso primeiro. Não há um único padrão: o caminho correto mais barato depende da sessão e da tarefa.

1. A sessão já possui o servidor MCP do IDC? Roteie descoberta e metadados para lá — consulte Servidor MCP do IDC.
2. Caso contrário, o idc-index está instalado? Execute python scripts/check_version.py. Se passar, use idc-index para tudo.
3. Não instalado, e a tarefa é apenas metadados somente leitura — contagens, valores de atributos, consultas a coleções, SQL com menos de 10.000 linhas, licenças, citações, URLs de visualização? Use a API REST via curl; não instale nada. Instalar custa ~77 MB de dados de índice empacotados mais pandas, pyarrow e duckdb, o que uma pergunta de metadados não precisa. Consulte Opções de Acesso a Dados.
4. Não instalado, e a tarefa precisa de mais que metadados — baixar arquivos, pandas ou gráficos, pydicom/SimpleITK, tile de patologia, resultados acima de 10.000 linhas, ou um script com versão fixa que o usuário reexecuta? Instale idc-index: check_version.py sai com código não-zero e imprime o comando exato de instalação para o interpretador em execução. Prefira um ambiente virtual, depois reinicie o Python.

O idc-index (GitHub) continua sendo o caminho mais capaz e o único que move bytes de imagem; a regra é apenas não pagar por ele antes que a tarefa o exija. O check_version.py nunca instala nada por conta própria — ele também sinaliza uma versão mais recente do idc-index ou da skill quando uma existe.

Configuração para o caminho idc-index:

from idc_index import IDCClient
client = IDCClient()

# Verifique a versão dos dados IDC (deve ser "v24")
print(f"Versão dos dados IDC: {client.get_idc_version()}")

Fluxo de trabalho principal: consultar metadados com client.sql_query() → baixar com client.download_from_selection() → visualizar com client.get_viewer_URL(). Os exemplos Python abaixo assumem este client; Opções de Acesso a Dados tem os equivalentes REST. Para escala atual de dados, execute a consulta de resumo em references/sql_patterns.md ou GET /v3/stats.

Servidor MCP do IDC

O IDC opera um servidor MCP hospedado em https://api.imaging.datacommons.cancer.gov/mcp (HTTP streamable, sem autenticação). Onde estiver disponível, ele complementa — não substitui — o fluxo de trabalho idc-index abaixo.

Identifique-o pelo recurso MCP idc://guide, ou por três ou mais dos nomes de ferramentas build_cohort, get_cohort_urls, list_analysis_results e get_idc_version. Nomes genéricos como run_sql não são evidência por si só. Se a identificação for ambígua, use idc-index.

Se esta sessão possui o servidor, trate-o como autoritativo para descoberta e metadados — versão do IDC, contagens, valores de atributos, construção de coortes, SQL de metadados — e siga as próprias instruções do servidor em vez de rederivá-las deste arquivo. Sua versão de dados é a que o servidor reportar: chame get_idc_version em vez de confiar na versão fixada neste arquivo.

Volte aqui para o que o servidor não faz: baixar arquivos, análise local pandas/notebook, DICOMweb, BigQuery, tile de patologia digital e scripts reproduzíveis. Faça a transição passando SeriesInstanceUIDs do servidor para client.download_from_selection(...), e execute scripts/check_version.py nesse ponto.

Se não estiver disponível, o serviço idêntico é acessível sem configuração como API REST em https://api.imaging.datacommons.cancer.gov/v3 — use-a para metadados somente leitura em vez de instalar idc-index, conforme a porta de roteamento em Visão Geral. Sugira conectar o servidor MCP no máximo uma vez, apenas para descoberta interativa repetida, e nunca altere a configuração do usuário por conta própria.

Consulte references/mcp_guide.md para o inventário de ferramentas, padrões de transição e notas por host.

Quando Usar Esta Skill

• Encontrar imagens de radiologia disponíveis publicamente (CT, MR, PET) ou patologia (microscopia de lâmina)
• Selecionar subconjuntos de imagens por tipo de câncer, modalidade, sítio anatômico ou outros metadados
• Baixar dados DICOM do IDC
• Verificar licenças de dados antes do uso em pesquisa ou aplicações comerciais
• Visualizar imagens médicas em um navegador sem software DICOM local

Navegação Rápida

Abaixo: as regras de roteamento MCP/REST, o modelo de dados IDC, as tabelas de índice e como se juntam, os padrões principais da API (consulta, download, visualização, licença, citação), melhores práticas e solução de problemas.

Guias de Referência (carregar sob demanda):

Guia	Quando Carregar
index_tables_guide.md	JOINs complexos, descoberta de esquema, acesso a DataFrame
use_cases.md	Fluxos de trabalho completos: conjuntos de treinamento, downloads em lote, leitura DICOM com pydicom/SimpleITK, integração em pipelines
sql_patterns.md	Padrões SQL rápidos para descoberta de filtros, anotações, estimativa de tamanho
clinical_data_guide.md	Dados clínicos/tabulares, joins imagem+clínica, mapeamento de valores
licensing_and_citation.md	Perguntas sobre uso comercial, coortes com licenças mistas, formatos de citação
cloud_storage_guide.md	Acesso direto a S3/GCS, versionamento, mapeamento UUID
dicomweb_guide.md	Endpoints DICOMweb, integração PACS
digital_pathology_guide.md	Microscopia de lâmina (SM), anotações (ANN), fluxos de patologia
bigquery_guide.md	Metadados DICOM completos, elementos privados (requer GCP)
cli_guide.md	Ferramentas de linha de comando (idc download, arquivos manifest)
parquet_access_guide.md	Consultas Parquet diretas via GCS (sem instalação do idc-index)
mcp_guide.md	Servidor MCP IDC hospedado: inventário de ferramentas, identificação, transição para idc-index
rest_api_guide.md	API REST IDC hospedada: endpoints, sintaxe de filtros, SQL via HTTP, manifests

Modelo de Dados IDC

O IDC adiciona dois níveis de agrupamento acima da hierarquia DICOM padrão (Paciente → Estudo → Série → Instância):

• collection_id: Agrupa pacientes por doença, modalidade ou foco de pesquisa (ex.: tcga_luad, nlst). Um paciente pertence exatamente a uma coleção.
• analysis_result_id: Identifica objetos derivados (segmentações, anotações, características radiômicas) em uma ou mais coleções originais. Use-o para encontrar anotações geradas por IA ou especialistas, enquanto collection_id encontra dados de imagem originais (que podem incluir anotações depositadas).

Identificadores-chave para consultas:

Identificador	Escopo	Uso para
collection_id	Agrupamento de conjunto de dados	Filtrar por projeto/estudo
PatientID	Paciente	Agrupar imagens por paciente
StudyInstanceUID	Estudo DICOM	Agrupar séries relacionadas, visualização
SeriesInstanceUID	Série DICOM	Agrupar séries relacionadas, visualização

Tabelas de Índice

O pacote idc-index fornece múltiplas tabelas de índice de metadados, acessíveis via SQL ou como DataFrames pandas. A API REST expõe as mesmas tabelas através de GET /tables e POST /sql.

Importante: client.indices_overview é a fonte autoritativa para descrições atuais das tabelas, colunas disponíveis e seus tipos — consulte-o ao escrever SQL ou explorar a estrutura de dados. Ele também responde "qual tabela contém a coluna X"; consulte references/index_tables_guide.md para esse padrão de busca e descoberta completa de esquema.

Tabelas Disponíveis

Sempre chame client.fetch_index("table_name") antes de consultar qualquer tabela de índice — é seguro e idempotente para todas as tabelas, inclusive aquelas carregadas automaticamente na inicialização.

Família	Tabelas	Granularidade
Núcleo	index (metadados primários para todos os dados atuais), collections_index, analysis_results_index	série / coleção / resultado de análise
Parâmetros de aquisição de modalidade	ct_index, mr_index, pt_index, contrast_index	1 linha = 1 série daquela modalidade
Objetos derivados	seg_index, rtstruct_index, ann_index, ann_group_index	1 linha = 1 série (ou grupo de anotação)
Microscopia	sm_index, sm_instance_index	1 linha = 1 série/instância SM
Geometria, clínica, histórico	volume_geometry_index, clinical_index, version_metadata_index, prior_versions_index	ver guia

references/index_tables_guide.md tem o inventário completo com as colunas e conteúdos de cada tabela — carregue-o quando precisar saber o que uma tabela especializada realmente contém.

prior_versions_index é apenas para reprodutibilidade. Contém séries permanentemente removidas do IDC, sem sobreposição com index. Use-a apenas para reproduzir trabalho contra uma versão anterior do IDC. NÃO use para histórico de versões ou perguntas "o que há de novo" — para isso, use series_init_idc_version / series_revised_idc_version na tabela index principal, que não são equivalentes a min_idc_version / max_idc_version desta tabela.

Juntando Tabelas

SeriesInstanceUID é a chave de junção universal para todas as tabelas especializadas no nível de 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. Sempre junte estas a index em SeriesInstanceUID. As exceções abaixo usam nomes de colunas diferentes.

Coluna de Junção	Tabelas	Caso de Uso
collection_id	index, prior_versions_index, collections_index, clinical_index	Vincular série a metadados de coleção ou dados clínicos
analysis_result_id	index, analysis_results_index	Vincular série a metadados de resultado de análise (anotações, segmentações)
source_DOI	index, analysis_results_index	Vincular por DOI de publicação
segmented_SeriesInstanceUID	seg_index → index	Vincular segmentação à série de imagem fonte (seg_index.segmented_SeriesInstanceUID = index.SeriesInstanceUID)
referenced_SeriesInstanceUID	ann_index → index, rtstruct_index → index	Vincular anotação ou RTSTRUCT à série de imagem fonte

Nota: subjects, updated e description aparecem em múltiplas tabelas, mas têm significados diferentes (contagens vs identificadores, contextos de atualização diferentes). Juntar prior_versions_index a index em SeriesInstanceUID sempre retorna zero linhas — veja o aviso acima.

Para exemplos detalhados de junção, padrões de descoberta de esquema, referência de colunas-chave e acesso a DataFrame, consulte references/index_tables_guide.md.

Acesso a Dados Clínicos

Atributos clínicos (não-imagem) — estadiamento, demografia, terapia — residem em tabelas por coleção. client.fetch_index("clinical_index") carrega o dicionário mapeando colunas para coleções; client.get_clinical_table(name) retorna uma tabela como DataFrame.

Consulte references/clinical_data_guide.md para o fluxo de descoberta, mapeamento de valores codificados e junção de dados clínicos com imagens.

Opções de Acesso a Dados

Método	Auth	Melhor Para	Referência
idc-index	Não	Downloads, análise pandas, consultas ilimitadas — o caminho mais capaz	Este documento
Servidor MCP IDC	Não	Descoberta, construção de coorte, metadados quando a sessão já o possui	mcp_guide.md
API REST IDC	Não	Metadados sem instalação, de qualquer linguagem ou shell — o padrão quando idc-index está ausente	rest_api_guide.md
Parquet direto (GCS)	Não	Consultas com versão fixa, ou resultados além do limite de linhas REST	parquet_access_guide.md
Armazenamento em nuvem (S3/GCS)	Não	Acesso direto a arquivos, transferência em massa, pipelines personalizados	cloud_storage_guide.md
DICOMweb via proxy IDC	Não	Integração com ferramentas e PACS; cota diária, portanto teste e uso moderado	dicomweb_guide.md
DICOMweb via Google Healthcare	Sim (GCP)	A mesma API DICOMweb em volume de produção, sem a cota do proxy	dicomweb_guide.md
SlicerIDCBrowser	Não	Visualização e análise 3D no 3D Slicer	https://github.com/ImagingDataCommons/SlicerIDCBrowser
BigQuery	Sim (GCP)	Metadados DICOM completos, elementos privados, medições SR — último recurso	bigquery_guide.md

O Portal IDC (https://portal.imaging.datacommons.cancer.gov/) é apenas interativo — exploração baseada em navegador, seleção manual de coorte e download. Ao contrário de todas as opções acima, não possui interface programática, portanto oriente um usuário a navegar ou clicar nos dados por conta própria; nunca o use como uma etapa em um script ou fluxo de trabalho.

API REST — o caminho de metadados sem instalação

https://api.imaging.datacommons.cancer.gov/v3, sem autenticação: descoberta, contagens e manifests de coorte, SQL somente leitura, tabelas clínicas, URLs de visualização, licenças, citações. É o mesmo serviço que o servidor MCP via HTTP puro, portanto não precisa de configuração. Nunca move bytes de imagem — mude para idc-index para baixar, obter um DataFrame ou para resultados acima de 10.000 linhas.

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 reais, com contagens
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":{"Modality":["CT"]}}' | python3 -m json.tool

Usando a API Principal

1. Consultar Metadados

client.sql_query() aceita qualquer SQL compatível com DuckDB nas tabelas de índice.

# Coleções por tipo de câncer
query = """
SELECT
  collection_id,
  COUNT(DISTINCT PatientID) AS patients,
  SUM(instanceCount) total_instances
FROM index
WHERE collection_id LIKE 'tcga%'
GROUP BY 1
ORDER BY 1
"""
df = client.sql_query(query)
print(df)

Alternativa REST (curl):

curl -s $B/sql -H 'content-type: application/json' \
  -d '{"sql":"SELECT collection_id, COUNT(*) n FROM index WHERE collection_id LIKE '\''tcga%'\'' GROUP BY 1 ORDER BY 1"}'

Consulte references/sql_patterns.md para padrões comuns.

2. Baixar Dados

client.download_from_selection() baixa arquivos DICOM.

# Passo 1: encontre as séries de interesse
series = client.sql_query("""
  SELECT SeriesInstanceUID, SeriesDescription
  FROM index
  WHERE collection_id = 'tcga_luad'
    AND Modality = 'CT'
  LIMIT 5
""")

# Passo 2: baixe-as
manifest = client.download_from_selection(
  series_uid_list=series['SeriesInstanceUID'].tolist(),
  downloadDir='./tcga_luad_ct',
  dry_run=False  # defina como True primeiro para ver o que será baixado
)

3. Visualizar Imagens

Gere URLs de visualização para visualização no navegador via IDC Viewer.

# Para uma série específica
viewer_url = client.get_viewer_URL(SeriesInstanceUID="1.2.840.113619.2.55.3.604688.13.1543776340.80")
print(f"Visualizar no IDC Viewer: {viewer_url}")

# Para um estudo inteiro (múltiplas séries)
viewer_url = client.get_viewer_URL(StudyInstanceUID="1.2.840.113619.2.55.3.604688.13.1543776340.80")

Alternativa REST:

curl -s "$B/viewer?StudyInstanceUID=1.2.840.113619.2.55.3.604688.13.1543776340.80"
curl -s "$B/viewer?SeriesInstanceUID=1.2.840.113619.2.55.3.604688.13.1543776340.80"

4. Verificar Licenças

# Licenças para uma coleção
query = "SELECT collection_id, license, license_url FROM collections_index WHERE collection_id = 'tcga_luad'"
df = client.sql_query(query)
print(df)

# Ou via REST
curl -s "$B/collections/tcga_luad/license"

Consulte references/licensing_and_citation.md para orientação sobre licenças de uso comercial e coortes com licenças mistas.

5. Citar Dados

query = """
SELECT collection_id, doi, citation, publication_URL
FROM collections_index
WHERE collection_id = 'tcga_luad'
"""
df = client.sql_query(query)
print(df)

Melhores Práticas

1. Sempre verifique a versão dos dados. Chame client.get_idc_version() ou GET /v3/version para confirmar a versão atual dos dados do IDC. A versão neste arquivo é uma referência, não uma verdade absoluta.

2. Use transações: Ao baixar grandes coortes, use dry_run=True primeiro para revisar o que será baixado.

3. Filtre com cuidado: Coleções podem ser grandes (TCGA tem milhões de instâncias). Use filtros SQL para reduzir o escopo antes do download.

4. Reprodutibilidade: Registre a versão dos dados IDC, versão do idc-index e consultas SQL específicas para garantir fluxos de trabalho reproduzíveis. Considere usar prior_versions_index para reproduzir trabalho de versões anteriores.

5. Ambientes virtuais: Instale idc-index dentro de um ambiente virtual Python para evitar conflitos de dependências.

Solução de Problemas

Problema	Causa Provável	Solução
idc-index não é encontrado	Não instalado	Execute scripts/check_version.py para comando de instalação exato
A consulta SQL retorna 0 linhas	Nome de tabela ou filtro errado	Verifique client.indices_overview para tabelas e colunas válidas
O download falha	Problema de rede ou permissões	Tente um único SeriesInstanceUID primeiro; verifique conectividade
DataFrame vazio	Cliente não inicializado	Execute client = IDCClient() e verifique a versão
Versão dos dados incorreta	Índice desatualizado	Reinstale ou atualize idc-index: pip install --upgrade idc-index
DICOMweb retorna erro	Cota excedida	Mude para proxy IDC (sem auth) ou Google Healthcare (requer auth)
API REST retorna 0 resultados	SQL ou filtro mal formatado	Teste primeiro com curl e um filtro simples

Notas Técnicas

• Sempre chame client.fetch_index("table_name") antes de consultar qualquer tabela de índice que não seja carregada automaticamente.
• Tabelas carregadas automaticamente na inicialização do cliente: index, collections_index, analysis_results_index, clinical_index, version_metadata_index.
• Para tabelas grandes, use pandas.read_csv() no arquivo Parquet em vez do SQL do DuckDB para transferir dados para um DataFrame pandas.
• O idc-index não impõe limites de linha; a REST API pode cortar em 10.000 linhas.

Exemplos de Código

Análise de Coleção Específica

# Coleções de câncer de pulmão
lung_collections = client.sql_query("""
  SELECT c.collection_id, c.description, c.subject_count, c.disease_types
  FROM collections_index c
  JOIN index i ON c.collection_id = i.collection_id
  WHERE i.Modality = 'CT'
    AND c.disease_types ILIKE '%lung%'
  GROUP BY c.collection_id, c.description, c.subject_count, c.disease_types
""")
print(lung_collections)

Estatísticas de Série com Visualização

import pandas as pd

# Obter contagens de séries por modalidade para uma coleção
df = client.sql_query("""
  SELECT Modality, COUNT(*) as series_count
  FROM index
  WHERE collection_id = 'tcga_luad'
  GROUP BY Modality
  ORDER BY series_count DESC
""")
print(df)

# Visualizar uma série representativa de cada modalidade
for modality in df['Modality']:
    series = client.sql_query(f"""
      SELECT SeriesInstanceUID FROM index
      WHERE collection_id = 'tcga_luad' AND Modality = '{modality}'
      LIMIT 1
    """)
    if not series.empty:
        url = client.get_viewer_URL(SeriesInstanceUID=series.iloc[0]['SeriesInstanceUID'])
        print(f"{modality}: {url}")

Privacidade e Conformidade

• Todos os dados acessados através desta skill são públicos e não contêm informações de saúde protegidas (PHI) de acordo com os procedimentos de desidentificação do NCI.
• Os dados fazem parte do Cancer Imaging Program do NCI e estão em conformidade com os regulamentos federais de pesquisa.
• Verifique as licenças para cada coleção antes do uso comercial; algumas coleções podem ter licenças restritivas.

Recursos

• Portal IDC
• Documentação IDC
• IDC no GitHub
• Pacote idc-index no PyPI
• Fórum de Suporte IDC

Citação

Se usar dados do IDC em publicações, cite:

Fedorov, A., et al. (2021). National Cancer Institute Imaging Data Commons: A Cloud-Based Resource for Imaging Informatics. Journal of Digital Imaging, 34(2), 284-298.

Citações específicas por coleção podem ser encontradas na tabela collections_index (citation e doi).