Skip to content

Migrate public DICOM notebooks from NBIA to IDC #37

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
kirbyju wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Migrate public DICOM notebooks from NBIA to IDC #37

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
4a7762a
Migrate public DICOM notebooks from NBIA to IDC
google-labs-jules[bot] Feb 26, 2026
6568fcb
Refine restricted access note and migrate notebooks to IDC
google-labs-jules[bot] Feb 26, 2026
44e33f5
Correct segmentation pairing and replace simpleDicomViewer with IDC v…
google-labs-jules[bot] Feb 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
532 changes: 137 additions & 395 deletions CPTAC/CPTAC.ipynb
View file
Open in desktop

Large diffs are not rendered by default.

234 changes: 63 additions & 171 deletions TCGA/TCGA_Clinical.ipynb
View file
Open in desktop

Large diffs are not rendered by default.

370 changes: 62 additions & 308 deletions TCIA_Image_Visualization_with_itkWidgets.ipynb
View file
Open in desktop

Large diffs are not rendered by default.

122 changes: 52 additions & 70 deletions TCIA_RTStruct_SEG_Visualization_with_itkWidgets.ipynb
View file
Open in desktop

Large diffs are not rendered by default.

78 changes: 33 additions & 45 deletions TCIA_STL_Visualization_with_itkWidgets.ipynb
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,9 +22,9 @@
"# Summary\n",
"Interactive visualization of data is essential to gaining new insights into problem domains, verifying image processing pipelines, and evaluating experimental results. TCIA provides a vast quantity of high-quality clinical data for such work. itkWidgets provides methods for visualizing TCIA's data within Python notebooks, whether they are running locally or in the cloud.\n",
"\n",
"This notebook explores the visualization of \"non-traditional\" data stored in TCIA. Other notebooks in this repository demonstrate the visualization of DICOM, SEG, and RTStruct objects. Herein, we demonstrate the visualization of STL files that are commonly used in 3D printing.\n",
"TCIA has partnered with the [NCI Imaging Data Commons (IDC)](https://portal.imaging.datacommons.cancer.gov/) to host and distribute our public DICOM data. **This notebook is focused on accessing TCIA's public DICOM data from IDC and visualizing it with itkWidgets.**\n",
"\n",
"[The Cancer Imaging Archive (TCIA)](https://www.cancerimagingarchive.net/) is a public service funded by the National Cancer Institute that addresses this challenge by providing hosting and de-identification services to take major burdens of data sharing off researchers. Its rich collection of clinical data and annotations is particularly powerful as a community resource when it is paired with interactive code systems, such as Jupyter systems.\n",
"This notebook explores the visualization of \"non-traditional\" data. Other notebooks in this repository demonstrate the visualization of DICOM, SEG, and RTStruct objects. Herein, we demonstrate the visualization of STL files that are commonly used in 3D printing.\n",
"\n",
"While Jupyter systems (JupyterLab, Jupyter Notebook, Google CoLab, Amazon SageMaker, etc.) are outstanding tools for interactive programming and algorithm sharing, the ability to visualize data within them has traditionally be limited to plots and sparse 2D slices, which are insufficient when dealing with 3D clinical data. This limitation is particularly challenging when using cloud-based Jupyter systems such as Google Colab and Amazon SageMaker. 3D interactive visualization of data when using those cloud systems traditionally requires downloading that data to your local machine and then running a separate visualization application. itkWidgets addresses these visualization challenges by providing interacitve 3D (and 2D) visualizations within the cells of your Jupyter scripts.\n",
"\n",
Expand All @@ -36,14 +36,13 @@
{
"cell_type": "markdown",
"metadata": {
"id": "nj6P7YCmll4S",
"tags": []
"id": "nj6P7YCmll4S"
},
"source": [
"# Outline\n",
"\n",
"1. Setup\n",
"2. TCIA Basics\n",
"2. IDC Basics\n",
"3. STL (VTK) Basics\n",
"4. itkWidgets Basics\n",
"5. Use Cases\n",
Expand Down Expand Up @@ -119,11 +118,9 @@
"outputId": "408c7a4d-492f-43cf-cb38-afa92d1f53d3"
},
"source": [
"# 2. TCIA Basics\n",
"\n",
"[Browsing Collections](https://www.cancerimagingarchive.net/collections) and viewing [Analysis Results](https://www.cancerimagingarchive.net/tcia-analysis-results/) of TCIA datasets are the easiest ways to become familiar with what is available. These pages will help you quickly identify datasets of interest, find valuable supporting data that are not available via our APIs (e.g. clinical spreadsheets, non-DICOM segmentation data), and answer the most common questions you might have about the datasets. \n",
"# 2. IDC Basics\n",
"\n",
"If you are new to accessing TCIA via notebooks, you can find additional tutorials on querying and downloading data at https://github.com/kirbyju/TCIA_Notebooks. We will also leverage [tcia_utils](https://github.com/kirbyju/tcia_utils) in this notebook to make it easier to grab our data to visualize."
"We will use the [**idc-index**](https://github.com/ImagingDataCommons/idc-index) python package to query and download datasets from the NCI Imaging Data Commons."
]
},
{
Expand All @@ -134,8 +131,8 @@
},
"outputs": [],
"source": [
"# Install tcia_utils\n",
"!{sys.executable} -m pip install --upgrade -q tcia_utils"
"# Install idc-index\n",
"!{sys.executable} -m pip install --upgrade -q idc-index"
]
},
{
Expand All @@ -146,9 +143,11 @@
},
"outputs": [],
"source": [
"from tcia_utils import nbia\n",
"from idc_index import IDCClient\n",
"import pandas as pd\n",
"import requests"
"import requests\n",
"\n",
"idc_client = IDCClient()"
]
},
{
Expand All @@ -159,16 +158,14 @@
},
"outputs": [],
"source": [
"# Download a \"Shared Cart\" that has been previously\n",
"# created via NBIA. It contains the DICOM image objects.\n",
"# This is case Prostate-MRI-US-Biopsy-0001. It has MR and US acquisitions.\n",
"cartName = \"nbia-63501667763872140\"\n",
"\n",
"# retrieve cart metadata\n",
"cart_data = nbia.getSharedCart(cartName)\n",
"# Define SeriesInstanceUIDs to download\n",
"# This is case Prostate-MRI-US-Biopsy-0001. It has MR and US acquisitions.\n",
"uids = [\"1.3.6.1.4.1.14519.5.2.1.140367896789002601449386011052978380612\",\n",
" \"1.3.6.1.4.1.14519.5.2.1.266717969984343981963002258381778490221\"]\n",
"\n",
"# download the series_uids list and return dataframe of metadata\n",
"df = nbia.downloadSeries(cart_data, format = \"df\")\n",
"# download the series and return dataframe of metadata\n",
"idc_client.download_from_selection(seriesInstanceUID=uids, downloadDir=\"idc_download\")\n",
"df = idc_client.index[idc_client.index['SeriesInstanceUID'].isin(uids)]\n",
"\n",
"# display dataframe\n",
"display(df)"
Expand All @@ -185,9 +182,6 @@
"# For this demo...\n",
"\n",
"# Install itk for DICOM I/O and for reading DICOM into an itkImage\n",
"# that manages all DICOM field values, include acquistion details\n",
"# such as voxel image, image orientation, and image directions,\n",
"# which are critical to image processing and display.\n",
"!{sys.executable} -m pip install --upgrade -q \"itk==5.4.0\""
]
},
Expand All @@ -200,23 +194,20 @@
"outputs": [],
"source": [
"import glob\n",
"\n",
"import itk\n",
"\n",
"dicom_data_dir = \"tciaDownload\"\n",
"dicom_data_dir = \"idc_download\"\n",
"\n",
"# The series_uid defines their directory where the MR data was stored on disk.\n",
"mr_series_uid = df.at[df.Modality.eq('MR').idxmax(), 'Series UID']\n",
"dicom_mr_dir = os.path.join(dicom_data_dir, mr_series_uid)\n",
"mr_series_uid = df.loc[df['Modality'] == 'MR', 'SeriesInstanceUID'].iloc[0]\n",
"dicom_mr_dir = glob.glob(os.path.join(dicom_data_dir, f\"**/{mr_series_uid}\"), recursive=True)[0]\n",
"\n",
"# The series_uid defines their directory where the US data was stored on disk.\n",
"# The ultrasound data is stored as a single 3D DICOM object, so we resolve its filename using glob\n",
"us_series_uid = df.at[df.Modality.eq('US').idxmax(), 'Series UID']\n",
"dicom_us_dir = os.path.join(dicom_data_dir, us_series_uid)\n",
"us_series_uid = df.loc[df['Modality'] == 'US', 'SeriesInstanceUID'].iloc[0]\n",
"dicom_us_dir = glob.glob(os.path.join(dicom_data_dir, f\"**/{us_series_uid}\"), recursive=True)[0]\n",
"dicom_us_file = glob.glob(os.path.join(dicom_us_dir, \"*.dcm\"))[0]\n",
"\n",
"# Load and sort the DICOM data into a volume - since no series_uid is\n",
"# specified with this read command, it will load the first series in the directory.\n",
"# Load the DICOM data into volumes\n",
"dicom_mr_image = itk.imread(dicom_mr_dir, itk.F)\n",
"dicom_us_image = itk.imread(dicom_us_file, itk.F)"
]
Expand All @@ -229,10 +220,8 @@
},
"outputs": [],
"source": [
"# Download the STL data from TCIA. STL files are typically stored as a collection\n",
"# in a zipped file. For example, for the Prostate-MRI-US-Biopsy, the STL data\n",
"# for every patient is stored in a single 247 MB zip file. Rather than spend time\n",
"# downloading and then uncompressing that data for this demo, we will use a single STL\n",
"# Download the STL data. STL files are typically stored as a collection\n",
"# in a zipped file. For this demo, we will use a single STL\n",
"# file stored on GitHub.\n",
"\n",
"stl_filename = \"Prostate-MRI-US-Biopsy-0001-ProstateSurface-seriesUID-1.3.6.1.4.1.14519.5.2.1.266717969984343981963002258381778490221.STL\"\n",
Expand All @@ -255,7 +244,7 @@
"\n",
"[STL](https://en.wikipedia.org/wiki/STL_(file_format)) files describe the surfaces of objects, typically for computer-aided design, 3D printing, and computer-aided manufacturing. In the medical field, they have seen applications ranging from 3D printing representations of organs and complex anatomical structures for surgical planning, to 3D printing of research into cellular scaffords and artificial organs for transplantation.\n",
"\n",
"We will use VTK for loading STL files that have been downloaded from TCIA."
"We will use VTK for loading STL files."
]
},
{
Expand Down Expand Up @@ -296,7 +285,7 @@
"source": [
"# 4. itkWidget Basics\n",
"\n",
"[itkWidgets documentation](https://itkwidgets.readthedocs.io/en/latest/?badge=latest) provides a summary and illustrations of itkWidgets for a wide variety of scientific data visualization use cases. Here we focus on its application to data on TCIA."
"[itkWidgets documentation](https://itkwidgets.readthedocs.io/en/latest/?badge=latest) provides a summary and illustrations of itkWidgets for a wide variety of scientific data visualization use cases. Here we focus on its application to data from IDC."
]
},
{
Expand Down Expand Up @@ -432,7 +421,6 @@
},
{
"cell_type": "code",
"execution_count": null,
"metadata": {
"id": "C6qFIu3ChFCT"
},
Expand All @@ -442,7 +430,8 @@
"viewerB.set_image_color_range([0,300])\n",
"viewerB.set_view_mode(\"ZPlane\")\n",
"viewerB.set_ui_collapsed(False)"
]
],
"execution_count": null
},
{
"cell_type": "markdown",
Expand Down Expand Up @@ -479,8 +468,7 @@
],
"metadata": {
"colab": {
"provenance": [],
"toc_visible": true
"provenance": []
},
"kernelspec": {
"display_name": "medical-image-ai:Python",
Expand All @@ -502,4 +490,4 @@
},
"nbformat": 4,
"nbformat_minor": 0
}
}
Loading