idc-index

library0.12.3pypypi✓ verified 84d ago

Python package to simplify access to the data available in the NCI Imaging Data Commons (IDC). Provides queryable Pandas/DuckDB-based indices for DICOM studies, series, and analysis results. Latest version: 0.11.14. Released approximately every 2-4 weeks.

data ai-ml database

pip install idc-index

github ↗package ↗homepage ↗changelog ↗

INSTALL

IMPORT

SIG · IDC-INDEX

idc-index

datapythonv0.12.3

Install

13.6s avg

Import

1825ms

Disk

502MB

Pass rate

6/ 10

Env Coverage6 / 10

glibc

3.9–3.13

musl

3.9–3.13

Install & Compatibility

Where this runs

tested against v0.12.3 · pip install

no network on importno background threads

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

glibc

py 3.10

✕ build_error

✓ 13.6s

py 3.11

✕ build_error

✓ 12.6s

py 3.12

✕ build_error

✓ 11.6s

py 3.13

✕ build_error

✓ 11.6s

py 3.9

✓ —

✓ 18.8s

502MB installed

● package 502MB

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

IDCClient

✓ from idc_index import IDCClient

✗ from idc_index.client import IDCClient

Client class is exposed at the top-level package since v0.10.

index

✓ from idc_index import index

For programmatic access to the index tables (e.g., index.IndexClient)

Creates a client, then queries for CT series from the TCGA-LUAD collection.

from idc_index import IDCClient client = IDCClient() # Get all DICOM series in the index series = client.get_series(collection_id="TCGA-LUAD", modality="CT") print(len(series)) # Access as Pandas DataFrame print(series.head())

Debug

Known issues

deprecatedThe method `get_collections()` was removed in v0.11. Use `client.available_collections` property instead.

fix

Replace `client.get_collections()` with `client.available_collections`

affects: >=0.11.0

gotchaIDCClient() will download the index data on first instantiation if not already cached. This can be slow (>1GB download). Use `IDCClient(lazy=True)` to defer downloading until a query is made.

fix

client = IDCClient(lazy=True)

affects: >=0.9.0

gotchaIndex data (parquet files) is versioned with the `idc-index-data` package. If you have an older version of idc-index-data, new methods may fail or return empty results. Always keep both packages up-to-date.

fix

Run `pip install --upgrade idc-index idc-index-data`

affects: all

breakingIn v0.11.0, the `get_patient_study_series()` return format changed from a dict with keys to a namedtuple. Code expecting dict keys will break.

fix

Access elements by index (e.g., result.patient_id) instead of dict['patient_id']

affects: >=0.11.0

Errors

Common errors & fixes

AttributeError: 'IDCClient' object has no attribute 'get_collections'

The method was renamed/removed in v0.11.

fix

Use `client.available_collections` instead.

ModuleNotFoundError: No module named 'idc_index_data'

The `idc-index-data` package is not installed or not up-to-date.

fix

Run `pip install idc-index-data` or `pip install idc-index --upgrade`.

ValueError: The truth value of a DataFrame is ambiguous

Calling `bool(client.get_series(...))` on an empty DataFrame.

fix

Use `not series.empty` instead of `if series:`

RuntimeError: Cannot connect to IDC index. Make sure you have internet access.

First-time download or cached index is corrupt; or network issue.

fix

Ensure stable internet, delete `~/.cache/idc-index` and retry, or set environment variable `IDC_INDEX_CACHE_DIR` to a writable path.

Upgrade

Version history

0.12.3latest on PyPI · released May 9, 2026

Audit

Dependencies

idc-index-datarequiredProvides the actual index data (parquet tables) loaded by idc-index

duckdbrequiredUsed internally for SQL-like queries on the indices

pandasrequiredUsed to represent query results as DataFrames

Agent activity

11 hits · last 30 days

node

Resources

githubhttps://github.com/ImagingDataCommons/idc-index ↗

packagehttps://pypi.org/project/idc-index/ ↗

homepagehttps://imagingdatacommons.org ↗

changeloghttps://github.com/ImagingDataCommons/idc-index/releases ↗