/imaging-data-commons

name: imaging-data-commons
description: Query and download public cancer imaging data from NCI Imaging Data Commons using idc-index. Use for accessing large-scale radiology (CT, MR, PET) and pathology datasets for AI training or research. No authentication required. Query by metadata, visualize in browser, check licenses.
license: This skill is provided under the MIT License. IDC data itself has individual licensing (mostly CC-BY, some CC-NC) that must be respected when using the data.
metadata:
    version: 1.3.1
    skill-author: Andrey Fedorov, @fedorov
    idc-index: "0.11.9"
    idc-data-version: "v23"
    repository: https://github.com/ImagingDataCommons/idc-claude-skill

Imaging Data Commons

Overview

Use the `idc-index` Python package to query and download public cancer imaging data from the National Cancer Institute Imaging Data Commons (IDC). No authentication required for data access.

Routing Boundary

Use this skill for NCI Imaging Data Commons, IDC, TCIA cancer imaging cohorts, DICOMWeb, public cancer imaging data, radiology datasets, and DICOM imaging cohort retrieval. This is not generic Data Commons, public statistical data, population indicators, statistical variables, DCIDs, PubMed, ClinicalTrials.gov, or generic public dataset search.

**Current IDC Data Version: v23** (always verify with `IDCClient().get_idc_version()`)

**Primary tool:** `idc-index` ([GitHub](https://github.com/imagingdatacommons/idc-index))

**CRITICAL - Check package version and upgrade if needed (run this FIRST):**

import idc_index

REQUIRED_VERSION = "0.11.9"  # Must match metadata.idc-index in this file
installed = idc_index.__version__

if installed < REQUIRED_VERSION:
    print(f"Upgrading idc-index from {installed} to {REQUIRED_VERSION}...")
    import subprocess
    subprocess.run(["pip3", "install", "--upgrade", "--break-system-packages", "idc-index"], check=True)
    print("Upgrade complete. Restart Python to use new version.")
else:
    print(f"idc-index {installed} meets requirement ({REQUIRED_VERSION})")

**Verify IDC data version and check current data scale:**

from idc_index import IDCClient
client = IDCClient()

# Verify IDC data version (should be "v23")
print(f"IDC data version: {client.get_idc_version()}")

# Get collection count and total series
stats = client.sql_query("""
    SELECT
        COUNT(DISTINCT collection_id) as collections,
        COUNT(DISTINCT analysis_result_id) as analysis_results,
        COUNT(DISTINCT PatientID) as patients,
        COUNT(DISTINCT StudyInstanceUID) as studies,
        COUNT(DISTINCT SeriesInstanceUID) as series,
        SUM(instanceCount) as instances,
        SUM(series_size_MB)/1000000 as size_TB
    FROM index
""")
print(stats)

**Core workflow:** 1. Query metadata → `client.sql_query()` 2. Download DICOM files → `client.download_from_selection()` 3. Visualize in browser → `client.get_viewer_URL(seriesInstanceUID=...)`

When to Use This Skill

• Finding publicly available radiology (CT, MR, PET) or pathology (slide microscopy) images
• Selecting image subsets by cancer type, modality, anatomical site, or other metadata
• Downloading DICOM data from IDC
• Checking data licenses before use in research or commercial applications
• Visualizing medical images in a browser without local DICOM viewer software

Quick Navigation

**Core Sections (inline):**

• IDC Data Model - Collection and analysis result hierarchy
• Index Tables - Available tables and joining patterns
• Installation - Package setup and version verification
• Core Capabilities - Essential API patterns (query, download, visualize, license, citations, batch)
• Best Practices - Usage guidelines
• Troubleshooting - Common issues and solutions

**Reference Guides (load on demand):**

| Guide | When to Load | |-------|--------------| | `index_tables_guide.md` | Complex JOINs, schema discovery, DataFrame access | | `use_cases.md` | End-to-end workflow examples (training datasets, batch downloads) | | `sql_patterns.md` | Quick SQL patterns for filter discovery, annotations, size estimation | | `clinical_data_guide.md` | Clinical/tabular data, imaging+clinical joins, value mapping | | `cloud_storage_guide.md` | Direct S3/GCS access, versioning, UUID mapping | | `dicomweb_guide.md` | DICOMweb endpoints, PACS integration | | `digital_pathology_guide.md` | Slide microscopy (SM), annotations (ANN), pathology workflows | | `bigquery_guide.md` | Full DICOM metadata, private elements (requires GCP) | | `cli_guide.md` | Command-line tools (`idc download`, manifest files) |

IDC Data Model

IDC adds two grouping levels above the standard DICOM hierarchy (Patient → Study → Series → Instance):

• **collection_id**: Groups patients by disease, modality, or research focus (e.g., `tcga_luad`, `nlst`). A patient belongs to exactly one collection.
• **analysis_result_id**: Identifies derived objects (segmentations, annotations, radiomics features) across one or more original collections.

Use `collection_id` to find original imaging data, may include annotations deposited along with the images; use `analysis_result_id` to find AI-generated or expert annotations.

**Key identifiers for queries:** | Identifier | Scope | Use for | |------------|-------|---------| | `collection_id` | Dataset grouping | Filtering by project/study | | `PatientID` | Patient | Grouping images by patient | | `StudyInstanceUID` | DICOM study | Grouping of related series, visualization | | `SeriesInstanceUID` | DICOM series | Grouping of related series, visualization |

Index Tables

The `idc-index` package provides multiple metadata index tables, accessible via SQL or as pandas DataFrames.

**Complete index table documentation:** Use https://idc-index.readthedocs.io/en/latest/indices_reference.html for quick check of available tables and columns without executing any code.

**Important:** Use `client.indices_overview` to get current table descriptions and column schemas.