TCIA_Segmentations.ipynb

{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "cpb6dbKi6s4v"
      },
      "source": [
        "You can download and run this notebook locally, or you can run it for free in a cloud environment using Colab or Sagemaker Studio Lab:\n",
        "\n",
        "[![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/kirbyju/TCIA_Notebooks/blob/main/TCIA_Segmentations.ipynb)\n",
        "\n",
        "[![Open In SageMaker Studio Lab](https://studiolab.sagemaker.aws/studiolab.svg)](https://studiolab.sagemaker.aws/import/github.com/kirbyju/TCIA_Notebooks/blob/main/TCIA_Segmentations.ipynb)"
      ],
      "id": "cpb6dbKi6s4v"
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "KmXfYFZtja2F"
      },
      "source": [
        "# Summary\n",
        "\n",
        "Access to large, high-quality datasets is essential for researchers to understand disease and precision medicine pathways, especially in cancer. However, HIPAA constraints make sharing medical images outside an individual institution complex. [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 that take major burdens of data sharing off researchers.\n",
        "\n",
        "**This notebook is focused on steps to identify an example segmentation file, find the corresponding reference series and visualize them together.**  If you're interested in additional TCIA notebooks and coding examples, check out the tutorials at https://github.com/kirbyju/TCIA_Notebooks."
      ],
      "id": "KmXfYFZtja2F"
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "AruUGe3lmjkh"
      },
      "source": [
        "# 1 Learn about Available Collections on the TCIA Website\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 and non-DICOM segmentation data), and answer the most common questions you might have about the datasets.  "
      ],
      "id": "AruUGe3lmjkh"
    },
    {
      "cell_type": "markdown",
      "source": [
        "# 2 Setup\n",
        "\n",
        "The following installs and imports **[tcia_utils](https://pypi.org/project/tcia-utils/)**, which contains a variety of useful functions for accessing TCIA via Python and Juptyter Notebooks.  It also ensures that the necessary imports are performed and logging settings are adjusted for Google Colab."
      ],
      "metadata": {
        "id": "bqulqBEDMSS6"
      },
      "id": "bqulqBEDMSS6"
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "YPrZ5pc-yYQl"
      },
      "outputs": [],
      "source": [
        "import sys\n",
        "\n",
        "# install tcia utils\n",
        "!{sys.executable} -m pip install --upgrade -q tcia_utils"
      ],
      "id": "YPrZ5pc-yYQl"
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "tags": [],
        "id": "LaKRUf-GJ_4C"
      },
      "outputs": [],
      "source": [
        "import requests\n",
        "import pandas as pd\n",
        "from tcia_utils import nbia\n",
        "\n",
        "# set logging level to INFO in Google Colab (not necessary in Jupyter)\n",
        "if 'google.colab' in sys.modules:\n",
        "  import logging\n",
        "\n",
        "  for handler in logging.root.handlers[:]:\n",
        "      logging.root.removeHandler(handler)\n",
        "\n",
        "  # Set handler with level = info\n",
        "  logging.basicConfig(format='%(asctime)s:%(levelname)s:%(message)s',\n",
        "                      level=logging.INFO)\n",
        "\n",
        "  print(\"Google Colab Logging set to INFO\")"
      ],
      "id": "LaKRUf-GJ_4C"
    },
    {
      "cell_type": "markdown",
      "source": [
        "# 3 Download and visualize a sample DICOM SEG\n",
        "Here we'll walk through some steps to identify an example segmentation file, find the corresponding reference series and visualize them together in the notebook.\n",
        "\n",
        "First, let's pull a list of segmentation series UIDs of interest.  We'll use the [C4KC-KiTS](https://doi.org/10.7937/TCIA.2019.IX49E8NX) collection as an example, which contains CT scans and segmentations from subjects from the training set of the [2019 Kidney and Kidney Tumor Segmentation Challenge (KiTS19)](https://kits19.grand-challenge.org/) in DICOM SEG format.  \n",
        "\n",
        "We can get an inventory of all scans in the collection using **nbia.getSeries()**."
      ],
      "metadata": {
        "id": "UmZ1gP5XsvD9"
      },
      "id": "UmZ1gP5XsvD9"
    },
    {
      "cell_type": "code",
      "source": [
        "df = nbia.getSeries(collection = \"C4KC-KiTS\", format = \"df\")\n",
        "sorted = df.sort_values([\"PatientID\", \"SeriesDescription\"])\n",
        "sorted.head(4)"
      ],
      "metadata": {
        "id": "NNfqtMZUE4xE"
      },
      "id": "NNfqtMZUE4xE",
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "Here we can see that patient KiTS-00000 has 3 CT series and one SEG series.  How do we know which one of the CTs goes with the SEG?  In many cases you can figure this out by looking at the Reference Series UID tag in the segmentation series.  Let's try it by saving the SEG series UID to a variable."
      ],
      "metadata": {
        "id": "JDtkd13_Hr7i"
      },
      "id": "JDtkd13_Hr7i"
    },
    {
      "cell_type": "code",
      "source": [
        "segSeries = sorted.loc[df['Modality'] == 'SEG', 'SeriesInstanceUID'].iloc[0]\n",
        "\n",
        "print(segSeries)"
      ],
      "metadata": {
        "id": "WFEOLIYRs33G"
      },
      "execution_count": null,
      "outputs": [],
      "id": "WFEOLIYRs33G"
    },
    {
      "cell_type": "markdown",
      "source": [
        "Next, let's determine the Reference Series Instance UID of the CT scan that goes with the segmentation using **nbia.getSegRefSeries()**."
      ],
      "metadata": {
        "id": "8NVZAb3qu_X4"
      },
      "id": "8NVZAb3qu_X4"
    },
    {
      "cell_type": "code",
      "source": [
        "refSeries = nbia.getSegRefSeries(segSeries)\n",
        "\n",
        "print(refSeries)"
      ],
      "metadata": {
        "id": "jogkmh9kvMoW"
      },
      "execution_count": null,
      "outputs": [],
      "id": "jogkmh9kvMoW"
    },
    {
      "cell_type": "markdown",
      "source": [
        "Now let's download these two series."
      ],
      "metadata": {
        "id": "KkMkyHoYwC2F"
      },
      "id": "KkMkyHoYwC2F"
    },
    {
      "cell_type": "code",
      "source": [
        "nbia.downloadSeries([refSeries, segSeries], input_type= \"list\", format = \"df\")"
      ],
      "metadata": {
        "id": "1P-s8sZBwIIz"
      },
      "execution_count": null,
      "outputs": [],
      "id": "1P-s8sZBwIIz"
    },
    {
      "cell_type": "markdown",
      "source": [
        "Finally, we can look at the images and segmentation together.  You can move the slider to flip through the images and toggle the segmentation layer on/off.  \n",
        "\n",
        "**Tip:** Once the slider is selected, sometimes it's easier to move between images using the left/right arrow keys on your keyboard than to use your mouse."
      ],
      "metadata": {
        "id": "6HU0fGOwvxxO"
      },
      "id": "6HU0fGOwvxxO"
    },
    {
      "cell_type": "code",
      "source": [
        "nbia.viewSeriesAnnotation(seriesUid = refSeries, annotationUid = segSeries)"
      ],
      "metadata": {
        "id": "gZb33aCNv24K"
      },
      "execution_count": null,
      "outputs": [],
      "id": "gZb33aCNv24K"
    },
    {
      "cell_type": "markdown",
      "source": [
        "# 4 Download and visualize a sample DICOM RTSTRUCT\n",
        "RTSTRUCT is another common format used to save segmentations.  Let's take a look at the [Annotations for The Clinical Proteomic Tumor Analysis Consortium Pancreatic Ductal Adenocarcinoma Collection (CPTAC-PDA-Tumor-Annotations) dataset](https://doi.org/10.7937/BW9V-BX61) as an example.  This [Analysis Result](https://www.cancerimagingarchive.net/tcia-analysis-results/) dataset analyzed images from the [CPTAC-PDA](https://doi.org/10.7937/K9/TCIA.2018.SC20FO18) collection.\n",
        "\n",
        "This time around, let's use the **modality** parameter in getSeries() to only return the RTSTRUCT series."
      ],
      "metadata": {
        "id": "ntPetyDFNaew"
      },
      "id": "ntPetyDFNaew"
    },
    {
      "cell_type": "code",
      "source": [
        "df = nbia.getSeries(collection = \"CPTAC-PDA\", modality = \"RTSTRUCT\", format = \"df\")\n",
        "display(df)"
      ],
      "metadata": {
        "id": "7TUxwnmYNYsK"
      },
      "execution_count": null,
      "outputs": [],
      "id": "7TUxwnmYNYsK"
    },
    {
      "cell_type": "markdown",
      "source": [
        "If you look at the Series Description column you'll note that in some cases these RTSTRUCT series are listed as \"seed point\" or \"no finding\".  These ones would not be particularly useful to visualize so let's make sure to avoid those. You can update the code below to use any of the other series UIDs you prefer, but let's start with **1.2.826.0.1.534147.667.2747872357.2023429821032.4** which has a description of **\"Pre-dose, PANCREAS - 1\"**."
      ],
      "metadata": {
        "id": "HnLV3G7mNYsK"
      },
      "id": "HnLV3G7mNYsK"
    },
    {
      "cell_type": "code",
      "source": [
        "segSeries = \"1.2.826.0.1.534147.667.2747872357.2023429821032.4\""
      ],
      "metadata": {
        "id": "vettaObhNYsL"
      },
      "execution_count": null,
      "outputs": [],
      "id": "vettaObhNYsL"
    },
    {
      "cell_type": "markdown",
      "source": [
        "Next, let's determine the Reference Series Instance UID of the CT scan that goes with the segmentation."
      ],
      "metadata": {
        "id": "1v-GBguFNYsL"
      },
      "id": "1v-GBguFNYsL"
    },
    {
      "cell_type": "code",
      "source": [
        "refSeries = nbia.getSegRefSeries(segSeries)\n",
        "\n",
        "print(refSeries)"
      ],
      "metadata": {
        "id": "sbDQNm4bNYsL"
      },
      "execution_count": null,
      "outputs": [],
      "id": "sbDQNm4bNYsL"
    },
    {
      "cell_type": "markdown",
      "source": [
        "Now let's download these two series.  "
      ],
      "metadata": {
        "id": "QeftUEEFNYsL"
      },
      "id": "QeftUEEFNYsL"
    },
    {
      "cell_type": "code",
      "source": [
        "nbia.downloadSeries([refSeries, segSeries], input_type= \"list\", format = \"df\")"
      ],
      "metadata": {
        "id": "iT7n0ahDNYsL"
      },
      "execution_count": null,
      "outputs": [],
      "id": "iT7n0ahDNYsL"
    },
    {
      "cell_type": "markdown",
      "source": [
        "Finally, we can look at the images and segmentation together.  You can move the slider to flip through the images and toggle the segmentation layer on/off."
      ],
      "metadata": {
        "id": "SqRhk5xCNYsL"
      },
      "id": "SqRhk5xCNYsL"
    },
    {
      "cell_type": "code",
      "source": [
        "nbia.viewSeriesAnnotation(seriesUid = refSeries, annotationUid = segSeries)"
      ],
      "metadata": {
        "id": "qZmqZmcgNYsL"
      },
      "execution_count": null,
      "outputs": [],
      "id": "qZmqZmcgNYsL"
    }
  ],
  "metadata": {
    "kernelspec": {
      "display_name": "tcia-env-test",
      "language": "python",
      "name": "tcia-env-test"
    },
    "language_info": {
      "codemirror_mode": {
        "name": "ipython",
        "version": 3
      },
      "file_extension": ".py",
      "mimetype": "text/x-python",
      "name": "python",
      "nbconvert_exporter": "python",
      "pygments_lexer": "ipython3",
      "version": "3.9.16"
    },
    "colab": {
      "provenance": [],
      "toc_visible": true
    }
  },
  "nbformat": 4,
  "nbformat_minor": 5
}