from idc_index import IDCClient
client = IDCClient()

**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=...)`

from idc_index import IDCClient
client = IDCClient()

undefined

from idc_index import IDCClient
client = IDCClient()

**As pandas DataFrames (direct access):**
```python

undefined

from idc_index import IDCClient
client = IDCClient()

**Alternative: use `get_index_schema()` method:**
```python
schema = client.get_index_schema("index")

undefined

undefined

See `references/clinical_data_guide.md` for detailed workflows including value mapping patterns and joining clinical data with imaging.

pip install --upgrade idc-index

pip install pandas numpy pydicom

from idc_index import IDCClient

client = IDCClient()

**`collections_index`** provides curated metadata per collection: cancer types, tumor locations, species, subject counts, and supporting data types — without needing to aggregate from the primary index.

**`analysis_results_index`** lists derived datasets (AI segmentations, expert annotations, radiomics features) with their source collections and modalities.

from idc_index import IDCClient

client = IDCClient()

**Then query with validated filter values:**
```python

**To filter by cancer type, join with `collections_index`:**
```python
client.fetch_index("collections_index")
results = client.sql_query("""
    SELECT i.collection_id, i.PatientID, i.SeriesInstanceUID, i.Modality
    FROM index i
    JOIN collections_index c ON i.collection_id = c.collection_id
    WHERE c.CancerTypes LIKE '%Breast%'
      AND i.Modality = 'MR'
    LIMIT 20
""")

from idc_index import IDCClient

client = IDCClient()

**Download specific series:**
```python

**Custom directory structure:**

Default `dirTemplate`: `%collection_id/%PatientID/%StudyInstanceUID/%Modality_%SeriesInstanceUID`

```python

undefined

undefined

**Options:**

| Option | Description |
|--------|-------------|
| `--download-dir` | Output directory (default: current directory) |
| `--dir-template` | Directory hierarchy template (default: `%collection_id/%PatientID/%StudyInstanceUID/%Modality_%SeriesInstanceUID`) |
| `--log-level` | Verbosity: debug, info, warning, error, critical |

**Manifest files:**

Manifest files contain S3 URLs (one per line) and can be:
- Exported from the IDC Portal after cohort selection
- Shared by collaborators for reproducible data access
- Generated programmatically from query results

Format (one S3 URL per line):

**Example: Generate manifest from Python query:**

```python
from idc_index import IDCClient

client = IDCClient()

Then download:
```bash
idc download ct_manifest.txt --download-dir ./ct_data

from idc_index import IDCClient
import webbrowser

client = IDCClient()

The method automatically selects OHIF v3 for radiology or SLIM for slide microscopy. Viewing by study is useful when a DICOM Study contains multiple Series (e.g., T1, T2, DWI sequences from a single MRI session).

from idc_index import IDCClient

client = IDCClient()

**License types in IDC:**
- **CC BY 4.0** / **CC BY 3.0** (~97% of data) - Allows commercial use with attribution
- **CC BY-NC 4.0** / **CC BY-NC 3.0** (~3% of data) - Non-commercial use only
- **Custom licenses** (rare) - Some collections have specific terms (e.g., NLM Terms and Conditions)

**Important:** Always check the license before using IDC data in publications or commercial applications. Each DICOM file is tagged with its specific license in metadata.

from idc_index import IDCClient

client = IDCClient()

**Parameters:**
- `collection_id`: Filter by collection(s)
- `patientId`: Filter by patient ID(s)
- `studyInstanceUID`: Filter by study UID(s)
- `seriesInstanceUID`: Filter by series UID(s)
- `citation_format`: Use `IDCClient.CITATION_FORMAT_*` constants:
  - `CITATION_FORMAT_APA` (default) - APA style
  - `CITATION_FORMAT_BIBTEX` - BibTeX for LaTeX
  - `CITATION_FORMAT_JSON` - CSL JSON
  - `CITATION_FORMAT_TURTLE` - RDF Turtle

**Best practice:** When publishing results using IDC data, include the generated citations to properly attribute the data sources and satisfy license requirements.

from idc_index import IDCClient
import pandas as pd

client = IDCClient()

undefined

import pydicom
import os

**Build 3D volume from CT series:**
```python
import pydicom
import numpy as np
from pathlib import Path

def load_ct_series(series_path):
    """Load CT series as 3D numpy array"""
    files = sorted(Path(series_path).glob('*.dcm'))
    slices = [pydicom.dcmread(str(f)) for f in files]

    # Sort by slice location
    slices.sort(key=lambda x: float(x.ImagePositionPatient[2]))

    # Stack into 3D array
    volume = np.stack([s.pixel_array for s in slices])

    return volume, slices[0]  # Return volume and first slice for metadata

volume, metadata = load_ct_series("./data/lung_ct/series_dir")
print(f"Volume shape: {volume.shape}")  # (z, y, x)

import SimpleITK as sitk
from pathlib import Path

undefined

from idc_index import IDCClient

client = IDCClient()

undefined

from idc_index import IDCClient
import pandas as pd

client = IDCClient()

query = f"""
SELECT SeriesInstanceUID
FROM index
WHERE Manufacturer = '{mfr}'
  AND ManufacturerModelName = '{model}'
  AND Modality = 'MR'
  AND BodyPartExamined LIKE '%BRAIN%'
LIMIT 5
"""

series = client.sql_query(query)
client.download_from_selection(
    seriesInstanceUID=list(series['SeriesInstanceUID'].values),
    downloadDir=f"./quality_study/{mfr.replace(' ', '_')}"
)

undefined

from idc_index import IDCClient
import webbrowser

client = IDCClient()

series_list = client.sql_query("""
    SELECT SeriesInstanceUID, PatientID, SeriesDescription
    FROM index
    WHERE collection_id = 'acrin_nsclc_fdg_pet' AND Modality = 'PT'
    LIMIT 10
""")

For additional visualization options, see the [IDC Portal getting started guide](https://learn.canceridc.dev/portal/getting-started) or [SlicerIDCBrowser](https://github.com/ImagingDataCommons/SlicerIDCBrowser) for 3D Slicer integration.

from idc_index import IDCClient

client = IDCClient()

undefined

undefined

undefined

undefined

undefined

undefined

undefined

undefined

undefined

client.fetch_index("clinical_index")

See `references/clinical_data_guide.md` for complete patterns including value mapping and patient cohort selection.

undefined

undefined