TCIA_REST_API_Downloads.ipynb

{
  "cells": [
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "mScj_P-dOMr2"
      },
      "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_REST_API_Downloads.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_REST_API_Downloads.ipynb)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "KmXfYFZtja2F"
      },
      "source": [
        "# Summary\n",
        "\n",
        "Access to large, high quality data 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 a complex process. [The Cancer Imaging Archive (TCIA)](https://www.cancerimagingarchive.net/) is a public service funded by the National Cancer Institute which addresses this challenge by providing hosting and de-identification services to take major burdens of data sharing off researchers.\n",
        "\n",
        "**This notebook is focused on basic use cases for leveraging TCIA's REST APIs to query and download data.**  If you're interested in additional TCIA notebooks and coding examples check out https://github.com/kirbyju/TCIA_Notebooks."
      ]
    },
    {
      "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 [Analysis Results](https://www.cancerimagingarchive.net/tcia-analysis-results/) datasets on TCIA 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 most common questions you might have about the datasets.  "
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "SmeqJoR5k9z0"
      },
      "source": [
        "# 2 REST API Overview\n",
        "TCIA uses software called NBIA to manage DICOM data.  The NBIA REST APIs include:\n",
        "1. [NBIA Search REST APIs](https://wiki.cancerimagingarchive.net/x/fILTB) that allow you to perform basic queries and download data from **public** collections. This API does not require a TCIA account.\n",
        "2. [NBIA Search with Authentication REST APIs](https://wiki.cancerimagingarchive.net/x/X4ATBg) that allow you to perform basic queries and download data from **public and limited-access** collections. This API requires a TCIA account for creation of authentication tokens.\n",
        "3. [NBIA Advanced REST APIs](https://wiki.cancerimagingarchive.net/x/YoATBg) that allow access to **public and limited-access** collections, but provide query endpoints mostly geared towards developers seeking to integrate searching and downloading TCIA data into web and desktop applications.  This API requires a TCIA account for creation of authentication tokens.\n",
        "\n",
        "As of v2.3 **tcia_utils** you don't have to worry about this complexity.  Each function automatically calls the proper API, and if credentials aren't specified you are logged in via a guest account to view fully public data.  See section 4.5 of this notebook to learn how to download \"limited access\" datasets you have received permission to use."
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "bqulqBEDMSS6"
      },
      "source": [
        "# 3 Setup\n",
        "\n",
        "The following cells install and import the **nbia** from [**tcia_utils**](https://pypi.org/project/tcia-utils/), which contains a variety of useful functions for accessing TCIA via Python.\n",
        "\n",
        "**tcia_utils** contains a **downloadSeries()** function that has multiple options for specifying the seriesUids you'd like to download.  By default, the function expects JSON data containing \"SeriesInstanceUID\" elements, which can be generated using any of the series-related queries such as **getSeries()** or **getCart()**.  However, if you have a series UID list from some other source, you can set **input_type = \"list\"** to pass a python list of one or more series UIDs instead of JSON. You can also set **input_type = \"manifest\"** to provide a path to a **.TCIA** manifest file.\n",
        "\n",
        "Data are saved to a **tciaDownload** folder in your current working directory by default, but you can use the **path** parameter to change this to a different directory.  Data are unzipped into a folder named after the Series Instance UID, unless `as_zip` is set to True.  In this case, it skips the unzipping steps and names the zip file after the Series Instance UID.  \n",
        "\n",
        "There is an optional **format** parameter that can be used to return metadata about what was downloaded.  It can be set to **df** to return dataframe or **csv** to save a spreadsheet. There's also a **csv_filename** parameter if you want to set a specific file name.\n",
        "\n",
        "You can specify **number = n** to tell the function to only download the first **n** scans of your seriesUids.  Remove this parameter in the examples below to download the full dataset.\n",
        "\n",
        "The **api_url** parameter can be omitted in most cases.  However, it must be set to **api_url = \"nlst\"** to access the [National Lung Screening Trial (NLST)](https://doi.org/10.7937/TCIA.HMQ8-J677) collection.  \n",
        "\n",
        "Last but not least, there is some logic built in to detect whether you've already downloaded a series.  If a directory named after the seriesUid already exists the function will assume it's already been downloaded and skip that series."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "TZ7IQ3PzcECF"
      },
      "outputs": [],
      "source": [
        "import sys\n",
        "\n",
        "# install tcia utils\n",
        "!{sys.executable} -m pip install --upgrade -q tcia_utils"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "zP4VRfgg-QXU"
      },
      "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\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "iao1mstCf8Vl"
      },
      "source": [
        "# 4 Download Examples\n",
        "\n",
        "In this section we'll cover downloading data via the REST API for the following use cases:\n",
        "\n",
        "1.   Download a full TCIA collection\n",
        "2.   Download custom results of an API query\n",
        "3.   Download a \"[Shared Cart](https://wiki.cancerimagingarchive.net/display/NBIA/TCIA+Radiology+Portal+User+Guide#TCIARadiologyPortalUserGuide-SharingDatainYourCart)\" that was created via https://nbia.cancerimagingarchive.net/\n",
        "4.   Download data from a TCIA manifest file\n",
        "5.   Download data from a **restricted** collection that requires logging in with your account\n",
        "6.   Download individual images from a series"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "fwj_OZjphcWP"
      },
      "source": [
        "## 4.1 Download a full collection\n",
        "\n",
        "You can [Browse Collections](https://www.cancerimagingarchive.net/collections) on our website to figure out what you might want to download, but you can also get a list of available collections via the API as shown below."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "II1o1709zq1d"
      },
      "outputs": [],
      "source": [
        "# get list of available collections as JSON\n",
        "nbia.getCollections()\n"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "Jbmm5DIU4Exy"
      },
      "source": [
        "Let's say that we're interested in downloading the entire **Soft-tissue-Sarcoma** collection.  First we need to get a list of all Series Instance UIDs in that collection.  We can use **nbia.getSeries()** to return JSON metadata about all series (scans) in this collection."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "eVnVh_yv7Av3"
      },
      "outputs": [],
      "source": [
        "data = nbia.getSeries(collection = \"Soft-tissue-Sarcoma\")\n",
        "print(data)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "wfkCWxiK8nQz"
      },
      "source": [
        "We can then pass that to the our download functions and view/save the metadata for what was downloaded.  We'll leverage the **number** parameter here to just grab the first 2 scans as a test.  You can remove this parameter if you want to download the full collection."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "2XVUkw5vgMZX"
      },
      "outputs": [],
      "source": [
        "nbia.downloadSeries(data, number = 2)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "gHzAX8wF0Rut"
      },
      "source": [
        "Take a second to go look at your **tciaDownload** folder to view the data.  Note that each series is saved in a directory named by its Series Instance UID.\n",
        "\n",
        "You can learn more about various ways to visualize and analyze your data in the other notebooks at https://github.com/kirbyju/TCIA_Notebooks.  However, let's use **nbia.viewSeries()** to get a quick look at one of the series we've downloaded.  You can change the Series UID in the code below to view other scans you've downloaded."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "5A17abaI0RXE"
      },
      "outputs": [],
      "source": [
        "seriesUid = \"1.3.6.1.4.1.14519.5.2.1.5168.1900.104193299251798317056218297018\"\n",
        "nbia.viewSeries(seriesUid)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "i7Pw0jvy4HO8"
      },
      "source": [
        "## 4.2 Download custom API query\n",
        "The REST API allows for a variety of different query options as demonstrated in [this notebook](https://github.com/kirbyju/TCIA_Notebooks/blob/main/TCIA_REST_API_Queries.ipynb).  "
      ]
    },
    {
      "cell_type": "markdown",
      "source": [
        "### 4.2.1 Custom downloads with getSeries()\n",
        "\n",
        "For this use case, let's assume that you are only interested in the MR scans from the [TCGA-BRCA](https://doi.org/10.7937/K9/TCIA.2016.AB2NAZRP) collection that were acquired on Siemens scanners."
      ],
      "metadata": {
        "id": "IOYo83qQ0B6W"
      }
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "6Y-uSUCBE_bJ"
      },
      "outputs": [],
      "source": [
        "# getSeries with query parameters\n",
        "data = nbia.getSeries(collection = \"TCGA-BRCA\",\n",
        "                      modality = \"MR\",\n",
        "                      manufacturer = \"SIEMENS\")\n",
        "\n",
        "print(len(data), 'Series returned')"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "mzDBsCavGuHR"
      },
      "source": [
        "Once again, let's pass those Series Instance UIDs to our download function.  This time we'll also set **format = \"df\"** to return a dataframe about what we downloaded."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "d5TAEkFmVtgg"
      },
      "outputs": [],
      "source": [
        "# feed series_data to our downloadSampleSeries function\n",
        "df = nbia.downloadSeries(data, number = 2, format = \"df\")\n",
        "display(df)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "uzqibEa5ZQbq"
      },
      "source": [
        "Another common use case may be that you'd like to review the results from **getSeries()** and do some further filtering.  This time we'll add **format = \"df\"** to save the output to a dataframe.  After removing unwanted scans from the dataframe, we'll pass the remaining Series Instance UIDs to **downloadSeries()**.  For example, let's say that you only wanted to download **T2 MR** series instead of any MR."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "tKldiImHZ1Er"
      },
      "outputs": [],
      "source": [
        "# getSeries with query parameters\n",
        "df = nbia.getSeries(collection = \"TCGA-BRCA\",\n",
        "               modality = \"MR\",\n",
        "               manufacturer = \"SIEMENS\", format = \"df\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "AK47oXMKaLZ9"
      },
      "source": [
        "Let's drop scans that don't contain **t2** in either the **ProtocolName** or **SeriesDescription** fields.  Note that we're down to 21 scans now instead of 353."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "uyaHU_f2aSSJ"
      },
      "outputs": [],
      "source": [
        "# convert the columns to lowercase to catch both upper/lower case with filter for 't2'\n",
        "filtered_df = df[(df['ProtocolName'].str.lower().str.contains('t2')) |\n",
        "                 (df['SeriesDescription'].str.lower().str.contains('t2'))]\n",
        "\n",
        "display(filtered_df)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "y_Dk04k7c0kB"
      },
      "source": [
        "Now we can feed the Series Instance UIDs from this dataframe back to **downloadSeries()**.  Note that since we're not working with the API's default JSON output anymore we need to specify **input_type = \"df\"** when we call **downloadSeries()**.\n",
        "\n",
        "Let's also try out the `as_zip` parameter this time just for fun."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "xVIo_onkfMBn"
      },
      "outputs": [],
      "source": [
        "# download the selected series_uids\n",
        "nbia.downloadSeries(filtered_df, input_type = \"df\", number = 2, as_zip=True)"
      ]
    },
    {
      "cell_type": "markdown",
      "source": [
        "### 4.2.2 Custom downloads with  getSimpleSearchWithModalityAndBodyPartPaged()\n",
        "This function lets you do pretty much everything you can do in the **Simple Search** screen at https://nbia.cancerimagingarchive.net. As as a result, there are a lot of parameters.\n",
        "\n",
        "```\n",
        "collections: list[str]   -- The DICOM collections of interest to you\n",
        "    species: list[str]       -- Filter collections by species. Possible values are 'human', 'mouse', and 'dog'\n",
        "    modalities: list[str]    -- Filter collections by modality\n",
        "    modalityAnded: bool      -- If true, only return subjects with all requested modalities, as opposed to any\n",
        "    minStudies: int          -- The minimum number of studies a collection must have to be included in the results\n",
        "    manufacturers: list[str] -- Imaging device manufacturers, e.g. SIEMENS\n",
        "    bodyParts: list[str]     -- Body parts of interest, e.g. CHEST, ABDOMEN\n",
        "    fromDate: str            -- First cutoff date, in YYYY/MM/DD format. Defaults to 1900/01/01\n",
        "    toDate: str              -- Second cutoff date, in YYYY/MM/DD format. Defaults to today's date\n",
        "    patients: list[str]      -- Patients to include in the output\n",
        "    start: int               -- Starting point of returned subject results. Defaults to 0.\n",
        "    size: int                -- Number of returned subjects per page. Defaults to 10.\n",
        "    sortDirection            -- 'ascending' or 'descending'. Defaults to 'ascending'.\n",
        "    sortField                -- 'subject', 'studies', 'series', or 'collection'. Defaults to 'subject'.\n",
        "    format: str              -- Defaults to JSON. Can be set to \"uids\" to return a python list of\n",
        "                                Series Instance UIDs or \"manifest\" to save a TCIA manifest file (up to 1,000,000 series).\n",
        "```\n",
        "\n",
        "By default it returns paged results in JSON format, but you can also set it to **manifest** or **uids** to return the results in a way that makes it easy to download them with `nbia.downloadSeries()`.  You just need to set the `input_type` parameter of `downloadSeries()` and the `format` parameter of `getSimpleSearchWithModalityAndBodyPartPaged()` accordingly.  For example:"
      ],
      "metadata": {
        "id": "IKyYgzLclH9h"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "uids = nbia.getSimpleSearchWithModalityAndBodyPartPaged(bodyParts=[\"CHEST\"], modalities=[\"CT\"], format = \"uids\")"
      ],
      "metadata": {
        "id": "I015JlqsRtNu"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "code",
      "source": [
        "# just grab the first series using number = 1 for demonstration purposes\n",
        "nbia.downloadSeries(uids, input_type = \"list\", number = 1)"
      ],
      "metadata": {
        "id": "pcqwco9y16Xh"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "source": [
        "Another common use case might be that you want to download a specific set of Patient IDs.  You can combine this with other query parameters as shown below.  Let's say you only want chest xrays for these two LIDC subjects:"
      ],
      "metadata": {
        "id": "jMp0YfW13BoZ"
      }
    },
    {
      "cell_type": "code",
      "source": [
        "# set patient ID list\n",
        "ids = ['LIDC-IDRI-0001', 'LIDC-IDRI-0002']\n",
        "\n",
        "# submit query\n",
        "uids = nbia.getSimpleSearchWithModalityAndBodyPartPaged(patients=ids, modalities = [\"CR\", \"DX\"], format = \"uids\")\n",
        "\n",
        "# download images\n",
        "nbia.downloadSeries(uids, input_type = \"list\", format = \"df\")"
      ],
      "metadata": {
        "id": "xyb5RpI33Jr0"
      },
      "execution_count": null,
      "outputs": []
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "JEKzWV7a7Q4M"
      },
      "source": [
        "### 4.2.3 Download custom NLST API query\n",
        "Let's show a similar example where we look for a specific modality and manufacturer within the [National Lung Screening Trial (NLST) Collection](https://doi.org/10.7937/TCIA.HMQ8-J677).  We have to set **api_url = \"nlst\"** in our functions for this to work, but otherwise the steps are the same."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "zGlhMzna7wgS"
      },
      "outputs": [],
      "source": [
        "# getSeries with query parameters\n",
        "data = nbia.getSeries(modality = \"CT\",\n",
        "                      manufacturer = \"Philips\",\n",
        "                      api_url = \"nlst\")\n",
        "\n",
        "print(len(data), 'Series returned')"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "D58Jjiqp8UVE"
      },
      "outputs": [],
      "source": [
        "# feed series_data to our downloadSampleSeries function\n",
        "df = nbia.downloadSeries(data, number = 2, api_url = \"nlst\", format = \"df\")\n",
        "display(df)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "AJw430rwTkJ0"
      },
      "source": [
        "## 4.3 Download a \"shared cart\"\n",
        "It's possible to use https://nbia.cancerimagingarchive.net to create a \"[Shared Cart](https://wiki.cancerimagingarchive.net/display/NBIA/TCIA+Radiology+Portal+User+Guide#TCIARadiologyPortalUserGuide-SharingDatainYourCart)\" which includes a specific set of scans you'd like to share with others.\n",
        "\n",
        "After creating a Shared Cart you will receive a URL that looks like https://nbia.cancerimagingarchive.net/nbia-search/?saved-cart=nbia-49121659384603347 which can be shared with others.  Try clicking the link to see what this looks like on the TCIA website.  Then use the code below to see how you can use the cart name at the end of the URL to download the related scans via the API."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "Wdv62WPyhEg7"
      },
      "outputs": [],
      "source": [
        "# getSharedCart metadata\n",
        "data = nbia.getSharedCart(name = \"nbia-49121659384603347\")\n",
        "print(len(data), 'Series returned')"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "-ga_N66rMWvK"
      },
      "source": [
        "We'll skip the use of the **number** parameter this time since the full cart is only 4 series.  Let's also try **format = \"csv\"** to save a spreadsheet of the metadata in addition to returning a dataframe."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "LlyJYA-rTlGY"
      },
      "outputs": [],
      "source": [
        "# feed series_data to our downloadSampleSeries function\n",
        "df = nbia.downloadSeries(data, format = \"csv\")\n",
        "display(df)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "60vpsOC2S6ff"
      },
      "source": [
        "## 4.4 Download data from a TCIA manifest file\n",
        "\n",
        "When working with manifest files you can install the NBIA Data Retriever to open the manifest and download the data as shown in [this notebook](https://github.com/kirbyju/TCIA_Notebooks/blob/main/TCIA_Linux_Data_Retriever_App.ipynb).  However, there may be cases where you don't have administrative rights to install software or prefer using the REST API to download a manifest.  \n",
        "\n",
        "In order to demonstrate this use case, let's assume that after you [Browse Collections](https://www.cancerimagingarchive.net/collections) you are interested in the [RIDER Breast MRI](https://doi.org/10.7937/K9/TCIA.2015.H1SXNUXL) collection.  We can find the URL of the manifest to download the full collection by looking at the blue \"Download\" button on that page.  Then we can download the manifest with the following commands.  "
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "pAtUWEcSHiO5"
      },
      "outputs": [],
      "source": [
        "# download manifest file from RIDER Breast MRI page\n",
        "manifest = requests.get(\"https://www.cancerimagingarchive.net/wp-content/uploads/doiJNLP-Fo0H1NtD.tcia\")\n",
        "with open('RIDER_Breast_MRI.tcia', 'wb') as f:\n",
        "    f.write(manifest.content)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "LHbh-qSHDhs3"
      },
      "source": [
        "If you open this manifest file in a text editor you'll notice that it contains several lines of download parameters that precede a list of Series Instance UIDs to download.  If we set **input_type = \"manifest\"** we can provide the path/filename to **downloadSeries()** and it will extract the UIDs from the file and download them."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "tmx0Ej70WKJ4"
      },
      "outputs": [],
      "source": [
        "df = nbia.downloadSeries(\"RIDER_Breast_MRI.tcia\", input_type = \"manifest\", number = 2, format = \"df\")\n",
        "display(df)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "A3exO0oNHtMY",
        "tags": []
      },
      "source": [
        "## 4.5 Download data from a restricted collection\n",
        "In some cases, you must specifically request access to collections before you can download them.  These are listed as **limited access** on the [Browse Collections](https://www.cancerimagingarchive.net/collections/) page. The steps to request access may vary depending on the collection, but will always require that you first [create a TCIA user account](https://wiki.cancerimagingarchive.net/x/xgHDAg). Once you've created an account, you can use your login/password to create an API token with the **getToken()** function from **tcia_utils** to verify your permissions. Tokens are valid for 2 hours and must be refreshed after that point, but **tcia_utils** monitors the timeout for you and automatically refreshes tokens if needed.\n",
        "\n",
        "**Note:** Historically the **api_url** parameter needed to be specified if you wanted to access 'restricted' datasets in most functions.  As of **tcia_utils version 2.3** this is no longer needed.  Simply create a token with your credentials and you're good to go!"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "ZzwyJcNYIIsq"
      },
      "outputs": [],
      "source": [
        "nbia.getToken()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "f1NLNszIIKOS"
      },
      "source": [
        "Let's say that we're interested in the [QIN-Breast-02](https://doi.org/10.7937/TCIA.2019.4cfm06rr) collection. As you can see on the collection page, you must email help@cancerimagingarchive.net to request access to the data. Once you've recieved approval we can use **nbia.getSeries()** to get a full list of series UIDs in this restricted collection."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "IAnZc6kdTYRL"
      },
      "outputs": [],
      "source": [
        "# getSeries with query parameters\n",
        "data = nbia.getSeries(collection = \"QIN-Breast-02\")\n",
        "\n",
        "if data != None:\n",
        "    print(len(data), 'Series returned')\n",
        "else:\n",
        "    print('No data returned.')\n",
        "    print('Did you forget to log in with your TCIA account in the previous cell?')\n",
        "    print('Did you forget to obtain permission from the helpdesk to access this collection?')"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "vxYch98LmtC0"
      },
      "source": [
        "Now we can download those scans just like before."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "id": "DGaaZxx7JKK2"
      },
      "outputs": [],
      "source": [
        "# feed series_data to our downloadSampleSeries function\n",
        "df = nbia.downloadSeries(data, number = 2, format = \"df\")\n",
        "display(df)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "tags": [],
        "id": "eHroEel0Jsjc"
      },
      "source": [
        "## 4.6 Download individual images from a series\n",
        "\n",
        "It is also possible to download specific images if you don't want the entire series. Let's look at an example using the [**CMB-GEC**](https://doi.org/10.7937/E7KH-R486) collection.  First we'll get a list of the metadata about the series."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "tags": [],
        "id": "3UGoDgEmJsjd"
      },
      "outputs": [],
      "source": [
        "nbia.getSeries(collection = \"CMB-GEC\")"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "6c3WeBpUJsjd"
      },
      "source": [
        "Once we identify a series of interest we can pass its Series Instance UID to **nbia.getSopInstanceUids()** to obtain a list of SOP Instance UIDs for the individual images that are part of this series."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "tags": [],
        "id": "ug1gYS43Jsjd"
      },
      "outputs": [],
      "source": [
        "seriesUID = \"1.3.6.1.4.1.14519.5.2.1.1600.1204.919741553251398079475267746505\"\n",
        "\n",
        "nbia.getSopInstanceUids(seriesUid)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "3wAhuRkrJsjd"
      },
      "source": [
        "After we have both a series UID and SOP Instance UID, we can call the **nbia.downloadImage()** function to download a specific image from the series."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "tags": [],
        "id": "t_5ww47sJsjd"
      },
      "outputs": [],
      "source": [
        "sopUID = \"1.3.6.1.4.1.14519.5.2.1.1600.1204.211684247543622814130853101548\"\n",
        "\n",
        "nbia.downloadImage(seriesUID, sopUID)"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {
        "id": "DYXsNGcY93B8"
      },
      "source": [
        "# Acknowledgements\n",
        "TCIA is funded by the [Cancer Imaging Program (CIP)](https://imaging.cancer.gov/), a part of the United States [National Cancer Institute (NCI)](https://www.cancer.gov/).  It is managed by the [Frederick National Laboratory for Cancer Research (FNLCR)](https://frederick.cancer.gov/) and hosted by the [University of Arkansas for Medical Sciences (UAMS)](https://www.uams.edu/)\n",
        "\n",
        "This notebook was created by [Justin Kirby](https://www.linkedin.com/in/justinkirby82/). If you leverage this notebook or any TCIA datasets in your work, please be sure to comply with the [TCIA Data Usage Policy](https://wiki.cancerimagingarchive.net/x/c4hF). In particular, make sure to cite the DOI(s) for the specific TCIA datasets you used in addition to the following paper!\n",
        "\n",
        "## TCIA Citation\n",
        "\n",
        "Clark, K., Vendt, B., Smith, K., Freymann, J., Kirby, J., Koppel, P., Moore, S., Phillips, S., Maffitt, D., Pringle, M., Tarbox, L., & Prior, F. (2013). The Cancer Imaging Archive (TCIA): Maintaining and Operating a Public Information Repository. Journal of Digital Imaging, 26(6), 1045–1057. https://doi.org/10.1007/s10278-013-9622-7"
      ]
    }
  ],
  "metadata": {
    "colab": {
      "provenance": [],
      "toc_visible": true
    },
    "kernelspec": {
      "display_name": "Python 3 (ipykernel)",
      "language": "python",
      "name": "python3"
    },
    "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"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 0
}