TCIA_REST_API_Complete_Documentation.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "9df463b2-d1b3-4877-bd9a-701139f0eb90",
   "metadata": {
    "jp-MarkdownHeadingCollapsed": true,
    "tags": []
   },
   "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_Complete_Documentation.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_Complete_Documentation.ipynb)\n",
    "\n",
    "### Set logging level to INFO in Google Colab (optional)\n",
    "This step should be skipped unless you're running on **Google Colab** as its logging root handler only shows warnings and errors by default.  If you'd like to see INFO statements you can run the following code.  This is particularly helpful when running some of the download examples so you can see the progress as downloads complete."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a09a1f00-af10-4d95-ab87-74b8019782a2",
   "metadata": {
    "id": "y4bh_j40-fia"
   },
   "outputs": [],
   "source": [
    "import logging\n",
    "\n",
    "# Check current handlers\n",
    "#print(logging.root.handlers)\n",
    "\n",
    "# Remove all handlers associated with the root logger object.\n",
    "for handler in logging.root.handlers[:]:\n",
    "    logging.root.removeHandler(handler)\n",
    "#print(logging.root.handlers)\n",
    "\n",
    "# Set handler with level = info\n",
    "logging.basicConfig(format='%(asctime)s:%(levelname)s:%(message)s', \n",
    "                    level=logging.INFO)\n",
    "\n",
    "print(\"Logging set to INFO\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7818862e-a548-438f-9127-d0bf808138ee",
   "metadata": {
    "id": "KmXfYFZtja2F",
    "jp-MarkdownHeadingCollapsed": true,
    "tags": []
   },
   "source": [
    "<a id = \"summary\"></a>\n",
    "# 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 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.<br>\n",
    "\n",
    "The tcia_utils package contains functions to simplify common tasks one might perform when interacting with The Cancer Imaging Archive (TCIA) via Jupyter/Python. Learn more about TCIA and its open-access datasets at https://www.cancerimagingarchive.net/. Please be sure to comply with the TCIA Data Usage Policy. Learn more about the tcia_utils package information on the PyPI page at https://pypi.org/project/tcia-utils/."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7e4cdb8f-a71d-48a3-b62a-6a74b9a8123e",
   "metadata": {
    "jp-MarkdownHeadingCollapsed": true,
    "tags": []
   },
   "source": [
    "## Installation"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ef026a3d-a167-42a8-981c-9a488bf26889",
   "metadata": {},
   "outputs": [],
   "source": [
    "!pip install --upgrade -q tcia-utils\n",
    "!pip install --upgrade -q pandas\n",
    "!pip install --upgrade -q requests"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "98f47ad5-4510-4325-b7d9-bd10f1fd7f9a",
   "metadata": {
    "tags": []
   },
   "source": [
    "## Usage\n",
    "To import functions related to the NBIA software, which holds TCIA's DICOM radiology data:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e42acf35-3c26-4870-a420-075ea22beb40",
   "metadata": {},
   "outputs": [],
   "source": [
    "import requests\n",
    "import pandas as pd\n",
    "from tcia_utils import nbia"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "318eed9c-76ec-4ef4-80b0-fc29a0da2e83",
   "metadata": {},
   "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.\n",
    "\n",
    "# 2. REST API Overview \n",
    "TCIA uses software called NBIA to manage DICOM data. The NBIA REST APIs are provided for the search and download functions used in the TCIA radiology portal and allow access to both public and limited access collections.\n",
    "1. The [NBIA Search REST APIs](https://wiki.cancerimagingarchive.net/x/fILTB) allow you to perform basic queries and download data from **public** collections. These APIs do not require a TCIA account.\n",
    "2. The [NBIA Search with Authentication REST APIs](https://wiki.cancerimagingarchive.net/x/X4ATBg) allow you to perform basic queries and download data from **public and limited-access** collections. These APIs require a TCIA account to create authentication tokens.\n",
    "3. The [NBIA Advanced REST APIs](https://wiki.cancerimagingarchive.net/x/YoATBg) also 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 to create authentication tokens."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6ec425a4-dc53-4206-a851-f2def73adeaf",
   "metadata": {
    "jp-MarkdownHeadingCollapsed": true,
    "tags": []
   },
   "source": [
    "# 3. Query Functions\n",
    "\n",
    "Detailed usage of some of these functions can be found at https://github.com/kirbyju/TCIA_Notebooks/blob/main/TCIA_REST_API_Queries.ipynb."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4d5e78cb-ef24-46f6-b99c-99b3d642c7f6",
   "metadata": {
    "tags": []
   },
   "source": [
    "## queryData\n",
    "\n",
    "**Params: (endpoint, api_url)**\n",
    "\n",
    "* Provides error handling for requests.get()\n",
    "* Formats output as JSON by default with options for \"df\" (dataframe) and \"csv\"\n",
    "* Because it is called by query functions that use requests.get(), ***<font color='red'>please do NOT use this function</font>***."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8dc04406-aa02-4f8e-b53e-febbf8ac369f",
   "metadata": {
    "tags": []
   },
   "source": [
    "## getCollections\n",
    "\n",
    "**Params: (api_url = \"\", format = \"\")**\n",
    "\n",
    "* *Optional: api_url, format*\n",
    "* Gets a list of collections from a specified api_url"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3184013d-9861-4eac-a2a8-a258122d6136",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is not specified, it returns a JSON object.\n",
    "nbia.getCollections(format = \"\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a8ffb4dc-cd18-4d19-8372-05463c04cd03",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is set to \"df\", it returns a pandas dataframe object.\n",
    "nbia.getCollections(format = \"df\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "50af422a-8ab9-49a8-aecb-4a3af3b420f9",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is set to \"csv\", it saves a csv file to the workspace.\n",
    "nbia.getCollections(format = \"csv\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8f107040-2f95-470a-90cf-2c2240a4b202",
   "metadata": {
    "tags": []
   },
   "source": [
    "## getBodyPart\n",
    "\n",
    "**Params: (collection = \"\", modality = \"\", api_url = \"\", format = \"\")**\n",
    "\n",
    "* *Optional: api_url, format*\n",
    "* Gets Body Part Examined metadata from a specified api_url\n",
    "* Allows filtering by collection and modality"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3e9e485d-69ca-4d11-a025-ef662b1d7019",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is not specified, it returns a JSON object.\n",
    "nbia.getBodyPart(collection = \"CPTAC-SAR\", modality = \"CT\", format = \"\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "56de6089-6061-4719-b5c8-2d67293a7f37",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is set to \"df\", it returns a pandas dataframe object.\n",
    "nbia.getBodyPart(collection = \"CPTAC-SAR\", modality = \"CT\", format = \"df\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a80bcc8b-5272-432c-8955-82ad4f31793b",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is set to \"csv\", it saves a csv file to the workspace.\n",
    "nbia.getBodyPart(collection = \"CPTAC-SAR\", modality = \"CT\", format = \"csv\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c3051475-7f22-48c0-bb39-cb4e84f35b6f",
   "metadata": {
    "tags": []
   },
   "source": [
    "## getModality\n",
    "\n",
    "**Params: (collection = \"\", bodyPart = \"\", api_url = \"\", format = \"\")**\n",
    "\n",
    "* *Optional: api_url, format*\n",
    "* Gets Modalities metadata from a specified api_url\n",
    "* Allows filtering by collection and bodyPart"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c4de1044-294b-4917-b0a7-85c6bad2494e",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is not specified, it returns a JSON object.\n",
    "nbia.getModality(collection = \"CPTAC-SAR\", bodyPart = \"EXTREMITY\", format = \"\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a24d641c-5ef1-4a50-b8ae-8737dcd95df6",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is set to \"df\", it returns a pandas dataframe object.\n",
    "nbia.getModality(collection = \"CPTAC-SAR\", bodyPart = \"EXTREMITY\", format = \"df\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "29ec7f4e-126a-423e-8181-c89ed636a906",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is set to \"csv\", it saves a csv file to the workspace.\n",
    "nbia.getModality(collection = \"CPTAC-SAR\", bodyPart = \"EXTREMITY\", format = \"csv\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e38c618d-ed84-4e4b-a03d-b42bb1b17094",
   "metadata": {
    "tags": []
   },
   "source": [
    "## getPatient\n",
    "\n",
    "**Params: (collection = \"\", api_url = \"\", format = \"\")**\n",
    "\n",
    "* *Optional: api_url, format*\n",
    "* Gets Patient metadata from a specified api_url\n",
    "* Allows filtering by collection"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "15d08619-5342-4e2e-bf37-e6266a2fea02",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is not specified, it returns a JSON object.\n",
    "nbia.getPatient(collection = \"CPTAC-SAR\", format = \"\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "29e4c447-b5a3-4bfa-b3bc-27fefbea1855",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is set to \"df\", it returns a pandas dataframe object.\n",
    "nbia.getPatient(collection = \"CPTAC-SAR\", format = \"df\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d28a302c-5681-4990-bbd8-1a089e59750b",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is set to \"csv\", it saves a csv file to the workspace.\n",
    "nbia.getPatient(collection = \"CPTAC-SAR\", format = \"csv\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "baeeed3a-50f2-4c5f-ae24-fb4ed8aa55b7",
   "metadata": {
    "tags": []
   },
   "source": [
    "## getPatientByCollectionAndModality\n",
    "\n",
    "**Params: (collection, modality, api_url = \"\", format = \"\")**\n",
    "\n",
    "* *Optional: api_url, format*\n",
    "* Gets Patient IDs from a specified api_url\n",
    "* Returns a list of patient IDs"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ac22e43a-8fe3-4060-bce9-c13f489ce232",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is not specified, it returns a JSON object.\n",
    "nbia.getPatientByCollectionAndModality(collection = \"CPTAC-SAR\", modality = \"CT\", format = \"\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "cc3fd616-256c-43b4-968f-ecae767990ff",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is set to \"df\", it returns a pandas dataframe object.\n",
    "nbia.getPatientByCollectionAndModality(collection = \"CPTAC-SAR\", modality = \"CT\", format = \"df\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "48b45d0e-5405-45d8-bece-a4a1c2fd3ee7",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is set to \"csv\", it saves a csv file to the workspace.\n",
    "nbia.getPatientByCollectionAndModality(collection = \"CPTAC-SAR\", modality = \"CT\", format = \"csv\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "79f5f2b6-29d3-48ea-ad1c-b18a2abea5f5",
   "metadata": {
    "tags": []
   },
   "source": [
    "## getNewPatientsInCollection\n",
    "\n",
    "**Params: (collection, date, api_url = \"\", format = \"\")**\n",
    "\n",
    "* *Optional: api_url, format*\n",
    "* Gets \"new\" patient metadata from a specified api_url\n",
    "* The date format is YYYY/MM/DD"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0f9e7a7d-2bd7-4dd3-9f95-f5f82a45288d",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is not specified, it returns a JSON object.\n",
    "nbia.getNewPatientsInCollection(collection = \"CPTAC-SAR\", date = \"2000/08/20\", format = \"\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e80e0d43-6bc5-44f2-8045-784177361125",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is set to \"df\", it returns a pandas dataframe object.\n",
    "nbia.getNewPatientsInCollection(collection = \"CPTAC-SAR\", date = \"2000/08/20\", format = \"df\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "abddb7bd-87de-4179-a5d6-0a0dfa731a41",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is set to \"csv\", it saves a csv file to the workspace.\n",
    "nbia.getNewPatientsInCollection(collection = \"CPTAC-SAR\", date = \"2000/08/20\", format = \"csv\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b932b58a-daef-4595-943e-41065b15eb67",
   "metadata": {},
   "source": [
    "## getStudy\n",
    "\n",
    "**Params: (collection, patientId = \"\", studyUid = \"\", api_url = \"\", format = \"\")**\n",
    "* *Optional: patientId, studyUid, api_url, format*\n",
    "* Gets Study (visit/timepoint) metadata from a specified api_url"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "219fdf73-5492-445b-9bf4-61e84fee7d4f",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is not specified, it returns a JSON object.\n",
    "nbia.getStudy(collection = \"CPTAC-SAR\", patientId = \"\", studyUid = \"\", format = \"\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ddf7a7ea-6b69-47cf-80cb-7d22be9ca03d",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is set to \"df\", it returns a pandas dataframe object.\n",
    "nbia.getStudy(collection = \"CPTAC-SAR\", patientId = \"\", studyUid = \"\", format = \"df\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7fbbc2e2-4ac8-49d5-9efd-9161fb9b650e",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is set to \"csv\", it saves a csv file to the workspace.\n",
    "nbia.getStudy(collection = \"CPTAC-SAR\", patientId = \"\", studyUid = \"\", format = \"csv\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c434c83b-5cfc-44c7-9b94-fa55dcb2b9fc",
   "metadata": {
    "tags": []
   },
   "source": [
    "## getNewStudiesInPatient\n",
    "**Params: (collection, patientId, date, api_url = \"\", format = \"\")**\n",
    "\n",
    "* *Optional: api_url, format*\n",
    "* Gets \"new\" patient metadata from a specified api_url\n",
    "* The date format is YYYY/MM/DD"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "90659cf9-5732-4c2a-a4fa-04a4c68205c8",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is not specified, it returns a JSON object.\n",
    "nbia.getNewStudiesInPatient(collection = \"CPTAC-SAR\", patientId = \"C3N-00843\", date = \"2010/09/06\", format = \"\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e4db5578-7d4a-4504-aff1-3df499fa178b",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is set to \"df\", it returns a pandas dataframe object.\n",
    "nbia.getNewStudiesInPatient(collection = \"CPTAC-SAR\", patientId = \"C3N-00843\", date = \"2010/09/06\", format = \"df\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "07f73bef-7505-451d-a699-9c8b8f1778fb",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is set to \"csv\", it saves a csv file to the workspace.\n",
    "nbia.getNewStudiesInPatient(collection = \"CPTAC-SAR\", patientId = \"C3N-00843\", date = \"2010/09/06\", format = \"csv\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4d8e52c3-dbe2-4e5a-a20b-471a07ef7e83",
   "metadata": {},
   "source": [
    "## getSeries\n",
    "\n",
    "**Params: (collection = \"\", patientId = \"\", studyUid = \"\", seriesUid = \"\", modality = \"\", bodyPart = \"\",<br>\n",
    "manufacturer = \"\", manufacturerModel = \"\", api_url = \"\", format = \"\")**\n",
    "\n",
    "* *All parameters are optional.*\n",
    "* Gets Series (scan) metadata from a specified api_url\n",
    "* Allows filtering by collection, patient ID, study UID, series UID, modality, body part, manufacturer & model\n",
    "* ***Note: Since the output of this function can be very long, it is advisable to save the output to a variable and only display a portion of it at a time when the output format is JSON.***"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "746ec846-b5a3-4fe4-86ce-c4135979f405",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is not specified, it returns a JSON object.\n",
    "data = nbia.getSeries(collection = \"CPTAC-SAR\", patientId = \"\", studyUid = \"\", seriesUid = \"\", \n",
    "                    modality = \"\", bodyPart = \"\", manufacturer = \"\", manufacturerModel = \"\", format = \"\")\n",
    "\n",
    "sample = data[:3]\n",
    "print(sample)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b745b4d3-728d-4082-99ee-981dc03d9fa9",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is set to \"df\", it returns a pandas dataframe object.\n",
    "nbia.getSeries(collection = \"CPTAC-SAR\", patientId = \"\", studyUid = \"\", seriesUid = \"\", \n",
    "                    modality = \"\", bodyPart = \"\", manufacturer = \"\", manufacturerModel = \"\", format = \"df\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2ed28e08-f63e-4fc1-97a8-1bb0f67c7178",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is set to \"csv\", it saves a csv file to the workspace.\n",
    "nbia.getSeries(collection = \"CPTAC-SAR\", patientId = \"\", studyUid = \"\", seriesUid = \"\", \n",
    "                    modality = \"\", bodyPart = \"\", manufacturer = \"\", manufacturerModel = \"\", format = \"csv\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0d920fb5-2bd2-47a4-9a61-48cca2f0c1f0",
   "metadata": {
    "tags": []
   },
   "source": [
    "## getUpdatedSeries\n",
    "**Params: (date, api_url = \"\", format = \"\")**\n",
    "\n",
    "* *Optional: api_url, format*\n",
    "* Gets \"new\" series metadata from a specified api_url\n",
    "* The date format is YYYY/MM/DD\n",
    "* ***NOTE: Unlike other API endpoints, this function expects MM/DD/YYYY, we'll convert from YYYY/MM/DD so tcia-utils is consistent***"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e7413f57-0ff3-4f3e-aacd-1c0371d47505",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is not specified, it returns a JSON object.\n",
    "nbia.getUpdatedSeries(date = \"2010/09/06\", format = \"\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "818d92fc-0f39-4c7e-a238-2c6c666b1a80",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is set to \"df\", it returns a pandas dataframe object.\n",
    "nbia.getUpdatedSeries(date = \"2010/09/06\", format = \"df\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "102bd2bc-ddaf-4465-9e80-12d3bafae9e2",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is set to \"csv\", it saves a csv file to the workspace.\n",
    "nbia.getUpdatedSeries(date = \"2010/09/06\", format = \"csv\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "713ebf27-bb5b-405e-bbf9-475f106c43c8",
   "metadata": {
    "tags": []
   },
   "source": [
    "## getSeriesMetadata\n",
    "**Params: (seriesUid, api_url = \"\", format = \"\")**\n",
    "\n",
    "* *Optional: api_url, format*\n",
    "* Gets Series (scan) metadata from a specified api_url\n",
    "* Output includes DOI and license details that are not in the getSeries() function"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "801d530d-b4de-48b7-9c41-3a9f7b1a1354",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is not specified, it returns a JSON object.\n",
    "nbia.getSeriesMetadata(seriesUid = \"1.3.6.1.4.1.14519.5.2.1.3320.3273.106936860187940539374736870621\", format = \"\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d757c0c9-b7b9-4619-9037-0f3cb84db27d",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is set to \"df\", it returns a pandas dataframe object.\n",
    "nbia.getSeriesMetadata(seriesUid = \"1.3.6.1.4.1.14519.5.2.1.3320.3273.106936860187940539374736870621\", format = \"df\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f1a18055-db4f-43ab-87fb-95771070cc39",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is set to \"csv\", it saves a csv file to the workspace.\n",
    "nbia.getSeriesMetadata(seriesUid = \"1.3.6.1.4.1.14519.5.2.1.3320.3273.106936860187940539374736870621\", format = \"csv\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5b29a139-a87e-4b4d-864a-639253a49b35",
   "metadata": {
    "tags": []
   },
   "source": [
    "## getSeriesSize\n",
    "**Params: (seriesUid, api_url = \"\", format = \"\")**\n",
    "\n",
    "* *Optional: api_url, format*\n",
    "* Gets the file count and disk size of a series/scan"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "75434e87-1b55-45d0-bb59-aaefe4500c9f",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is not specified, it returns a JSON object.\n",
    "nbia.getSeriesSize(seriesUid = \"1.3.6.1.4.1.14519.5.2.1.3320.3273.106936860187940539374736870621\", format = \"\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "7929b894-8e06-49d1-8fa1-7134784a1cec",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is set to \"df\", it returns a pandas dataframe object.\n",
    "nbia.getSeriesSize(seriesUid = \"1.3.6.1.4.1.14519.5.2.1.3320.3273.106936860187940539374736870621\", format = \"df\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e00a96b1-9692-41d2-9e1c-2521f0d24ea8",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is set to \"csv\", it saves a csv file to the workspace.\n",
    "nbia.getSeriesSize(seriesUid = \"1.3.6.1.4.1.14519.5.2.1.3320.3273.106936860187940539374736870621\", format = \"csv\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b783a759-bd1a-455f-ae49-28a1b93dd5d2",
   "metadata": {
    "tags": []
   },
   "source": [
    "## getSopInstanceUids\n",
    "**Params: (seriesUid, api_url = \"\", format = \"\")**\n",
    "\n",
    "* *Optional: api_url, format*\n",
    "* Gets SOP Instance UIDs from a specific series/scan"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6df0fb1c-6169-4eee-bb09-93b89b94deac",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is not specified, it returns a JSON object.\n",
    "nbia.getSopInstanceUids(seriesUid = \"1.3.6.1.4.1.14519.5.2.1.3320.3273.106936860187940539374736870621\", format = \"\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "012a4c40-cbfa-4a4a-90dc-1703c6a7356e",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is set to \"df\", it returns a pandas dataframe object.\n",
    "nbia.getSopInstanceUids(seriesUid = \"1.3.6.1.4.1.14519.5.2.1.3320.3273.106936860187940539374736870621\", format = \"df\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "47fc2763-6560-420d-be8c-05beb5c4755f",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is set to \"csv\", it saves a csv file to the workspace.\n",
    "nbia.getSopInstanceUids(seriesUid = \"1.3.6.1.4.1.14519.5.2.1.3320.3273.106936860187940539374736870621\", format = \"csv\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "3cc6a4db-a83e-41cf-8738-f6b3b3f91456",
   "metadata": {
    "tags": []
   },
   "source": [
    "## getManufacturer\n",
    "**Params: (collection = \"\", modality = \"\", bodyPart = \"\", api_url = \"\", format = \"\")**\n",
    "\n",
    "* *All parameters are optional.*\n",
    "* Gets manufacturer metadata from a specified api_url\n",
    "* Allows filtering by collection, body part & modality"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "285e1801-242f-460f-889f-80cab223e1d7",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is not specified, it returns a JSON object.\n",
    "nbia.getManufacturer(collection = \"\", modality = \"\", bodyPart = \"\", format = \"\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "32f8fb02-2b67-418e-a155-c024c22d2d54",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is set to \"df\", it returns a pandas dataframe object.\n",
    "nbia.getManufacturer(collection = \"\", modality = \"\", bodyPart = \"\", format = \"df\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a0f821da-ee69-4474-ade0-a633e63a5b4b",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is set to \"csv\", it saves a csv file to the workspace.\n",
    "nbia.getManufacturer(collection = \"\", modality = \"\", bodyPart = \"\", format = \"csv\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "568c25ed-2e0c-45e1-9f21-5a9a48ec3bb2",
   "metadata": {
    "tags": []
   },
   "source": [
    "## getSharedCart\n",
    "\n",
    "**Params: (name, api_url = \"\", format = \"\")**\n",
    "\n",
    "* *Optional: api_url, format*\n",
    "* Gets \"Shared Cart\" (scan) metadata from a specified api_url<br>\n",
    "* First use https://nbia.cancerimagingarchive.net/nbia-search/ to create a cart, then add data to your basket, then click \"Share\" > \"Share my cart\".\n",
    "* The \"name\" parameter is part of the URL that generates. E.g https://nbia.cancerimagingarchive.net/nbia-search/?saved-cart=nbia-49121659384603347 has a cart \"name\" of \"nbia-49121659384603347\"."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "69b59ce4-d7a1-4798-bde6-36eb95042b82",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is not specified, it returns a JSON object.\n",
    "nbia.getSharedCart(name = \"nbia-49121659384603347\", format = \"\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "adb8c154-2569-4ce5-ad09-bb554a9e6bf1",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is set to \"df\", it returns a pandas dataframe object.\n",
    "nbia.getSharedCart(name = \"nbia-49121659384603347\", format = \"df\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "aec905fd-4886-4190-9a8a-63e015ce4488",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is set to \"csv\", it saves a csv file to the workspace.\n",
    "nbia.getSharedCart(name = \"nbia-49121659384603347\", format = \"csv\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "4ea99b40-e2b1-4a30-899f-171f47b19962",
   "metadata": {},
   "source": [
    "## getCollectionDescriptions\n",
    "\n",
    "**Params: (api_url = \"\", format = \"\")**\n",
    "\n",
    "* *All parameters are optional.*\n",
    "* Gets HTML-formatted descriptions of collections and their DOIs"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3a5570cf-e1a5-437b-b320-72c774564d6d",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is not specified, it returns a JSON object.\n",
    "nbia.getCollectionDescriptions(format = \"\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "cc92c18a-417f-4346-906b-d606feea6601",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is set to \"df\", it returns a pandas dataframe object.\n",
    "nbia.getCollectionDescriptions(format = \"df\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "92fba7c5-5697-4193-819b-ef29006029fd",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is set to \"csv\", it saves a csv file to the workspace.\n",
    "nbia.getCollectionDescriptions(format = \"csv\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e0f99013-9d6a-404b-8174-bae6cec9233d",
   "metadata": {
    "tags": []
   },
   "source": [
    "## getCollectionPatientCounts\n",
    "**Params: (api_url = \"\", format = \"\")**\n",
    "\n",
    "* *All parameters are optional.*\n",
    "* Gets counts of Patient by collection from Advanced API"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "5706f5ac-a787-4333-a9c0-4b113fa5ae15",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is not specified, it returns a JSON object.\n",
    "nbia.getCollectionPatientCounts(format = \"\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "20d7d610-a704-4f9c-8b37-7c6d80039f53",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is set to \"df\", it returns a pandas dataframe object.\n",
    "nbia.getCollectionPatientCounts(format = \"df\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6eac0440-5385-4a8f-9bc0-6fd139bb9798",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is set to \"csv\", it saves a csv file to the workspace.\n",
    "nbia.getCollectionPatientCounts(format = \"csv\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0e0f20c3-17d5-4eba-b6ae-e14c3627c0ee",
   "metadata": {},
   "source": [
    "## getModalityCounts\n",
    "\n",
    "**Params: (collection = \"\", bodyPart = \"\", api_url = \"\", format = \"\")**\n",
    "\n",
    "* *All parameters are optional.*\n",
    "* Gets counts of Modality metadata from Advanced API\n",
    "* Allows filtering by collection and bodyPart"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3c88e2d7-b9a5-48ab-a8fd-695eac5db054",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is not specified, it returns a JSON object.\n",
    "nbia.getModalityCounts(collection = \"CPTAC-SAR\", bodyPart = \"\", format = \"\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "41163375-98ca-463a-985e-eafde5529823",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is set to \"df\", it returns a pandas dataframe object.\n",
    "nbia.getModalityCounts(collection = \"CPTAC-SAR\", bodyPart = \"EXTREMITY\", format = \"df\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6d14d56f-de15-4832-840d-ad4f3699b530",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is set to \"csv\", it saves a csv file to the workspace.\n",
    "nbia.getModalityCounts(collection = \"CPTAC-SAR\", bodyPart = \"EXTREMITY\", format = \"csv\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6e44dfe7-3521-4df3-ab1b-41fc8131a1d2",
   "metadata": {},
   "source": [
    "## getBodyPartCounts\n",
    "\n",
    "**Params: (collection = \"\", modality = \"\", api_url = \"\", format = \"\")**\n",
    "\n",
    "* *All parameters are optional.*\n",
    "* Gets counts of Body Part metadata from Advanced API\n",
    "* Allows filtering by collection and modality"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6145796b-6588-440b-a58c-c041fd772e0f",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is not specified, it returns a JSON object.\n",
    "nbia.getBodyPartCounts(collection = \"CPTAC-SAR\", modality = \"CT\", format = \"\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "bb568ccb-decc-477f-8aa9-eff61064a000",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is set to \"df\", it returns a pandas dataframe object.\n",
    "nbia.getBodyPartCounts(collection = \"CPTAC-SAR\", modality = \"CT\", format = \"df\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9dd277af-fe0c-4251-b6f9-afc78eefba56",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is set to \"csv\", it saves a csv file to the workspace.\n",
    "nbia.getBodyPartCounts(collection = \"CPTAC-SAR\", modality = \"CT\", format = \"csv\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7e8d9e5b-ef2d-4cda-9703-2515ffe693bb",
   "metadata": {
    "tags": []
   },
   "source": [
    "## getManufacturerCounts\n",
    "\n",
    "**Params: (collection = \"\", modality = \"\", bodyPart = \"\", api_url = \"\", format = \"\")**\n",
    "\n",
    "* *All parameters are optional.*\n",
    "* Gets counts of Manufacturer metadata from Advanced API\n",
    "* Allows filtering by collection, body part and modality"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "fb6617c0-a30e-4c90-a252-f19b388a7197",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is not specified, it returns a JSON object.\n",
    "nbia.getManufacturerCounts(collection = \"CPTAC-SAR\",  modality = \"CT\", bodyPart = \"\", format = \"\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c32ad726-5e75-419d-9979-b94f18672835",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is set to \"df\", it returns a pandas dataframe object.\n",
    "nbia.getManufacturerCounts(collection = \"CPTAC-SAR\",  modality = \"CT\", bodyPart = \"\", format = \"df\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4e988073-1284-431a-b3e9-57a7db75bfb5",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is set to \"csv\", it saves a csv file to the workspace.\n",
    "nbia.getManufacturerCounts(collection = \"CPTAC-SAR\",  modality = \"CT\", bodyPart = \"\", format = \"csv\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "158aed72-b8cd-4a09-92e1-be2591f9482c",
   "metadata": {},
   "source": [
    "## getSeriesList\n",
    "\n",
    "**Params: (list, api_url = \"\", csv_filename = \"\")**\n",
    "\n",
    "* *Optional: api_url, csv_filename*\n",
    "* Get series metadata from Advanced API\n",
    "* Allows submission of a list of UIDs\n",
    "* Returns result as dataframe and CSV"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "65e5c2eb-d1d0-40f5-89b5-633857c7ce2b",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "series_list = [\"1.3.6.1.4.1.14519.5.2.1.3320.3273.106936860187940539374736870621\", \"1.3.6.1.4.1.14519.5.2.1.6834.5010.215193814203822462481389051414\"]\n",
    "nbia.getSeriesList(list = series_list)"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "053bc164-7493-445a-af3e-965a56024345",
   "metadata": {},
   "source": [
    "## getDicomTags\n",
    "\n",
    "**Params: (seriesUid, api_url = \"\", format = \"\")**\n",
    "\n",
    "* *Optional: api_url, format*\n",
    "* Gets DICOM tag metadata for a given series UID (scan)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9d11a376-b1be-4056-bec3-3c1c155a3281",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is not specified, it returns a JSON object.\n",
    "nbia.getDicomTags(seriesUid = \"1.3.6.1.4.1.14519.5.2.1.3320.3273.106936860187940539374736870621\", format = \"\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9d859c82-4ab4-4303-ba95-53670eb8cfe6",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is set to \"df\", it returns a pandas dataframe object.\n",
    "nbia.getDicomTags(seriesUid = \"1.3.6.1.4.1.14519.5.2.1.3320.3273.106936860187940539374736870621\", format = \"df\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0221fd8e-e10f-4fc7-8431-a76cd2390a1c",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is set to \"csv\", it saves a csv file to the workspace.\n",
    "nbia.getDicomTags(seriesUid = \"1.3.6.1.4.1.14519.5.2.1.3320.3273.106936860187940539374736870621\", format = \"csv\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "79d8bb7f-9920-4d3f-bef2-661f4f232265",
   "metadata": {},
   "source": [
    "## getSegRefSeries\n",
    "**Params: (uid)**\n",
    "\n",
    "* Looks up the series UID where a given SEG/RTSTRUCT series UID (scan) is derived from\n",
    "* Returns a dataframe"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1fbd88d0-04ba-4923-b622-49ea60f03c57",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "nbia.getSegRefSeries(\"1.3.6.1.4.1.14519.5.2.1.267656005479923851264209489600557009114\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bd25528c-145e-4d32-abe6-eb888ffe3613",
   "metadata": {},
   "source": [
    "## getDoiMetadata\n",
    "\n",
    "**Params: (doi, output, api_url = \"\", format = \"\")**\n",
    "\n",
    "* *Optional: output, api_url, format*\n",
    "* Gets a list of Collections if output = \"\", or Series if output = \"series\", associated with a DOI.\n",
    "* The result includes whether the data are 3rd party analyses or not."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "187a7006-cbaf-4bbd-80a8-68930d2af722",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is not specified, it returns a JSON object.\n",
    "nbia.getDoiMetadata(doi = \"https://doi.org/10.7937/K9/TCIA.2018.PAT12TBS\", output = \"\", format = \"\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "29591de3-3e5b-43d2-a7e4-fd9e122eb965",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is not specified, it returns a JSON object.\n",
    "nbia.getDoiMetadata(doi = \"https://doi.org/10.7937/K9/TCIA.2018.PAT12TBS\", output = \"series\", format = \"\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "37df6fd6-b780-4584-9cb5-bb88089d3983",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is set to \"df\", it returns a pandas dataframe object.\n",
    "nbia.getDoiMetadata(doi = \"https://doi.org/10.7937/K9/TCIA.2018.PAT12TBS\", output = \"\", format = \"df\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6f781d60-48d8-4d2b-8a0e-3d3ad7021c3d",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is set to \"df\", it returns a pandas dataframe object.\n",
    "nbia.getDoiMetadata(doi = \"https://doi.org/10.7937/K9/TCIA.2018.PAT12TBS\", output = \"series\", format = \"df\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "069c5db3-61f6-4ffc-bbe7-baeab462874e",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is set to \"csv\", it saves a csv file to the workspace.\n",
    "nbia.getDoiMetadata(doi = \"https://doi.org/10.7937/K9/TCIA.2018.PAT12TBS\", output = \"\", format = \"csv\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1974bb71-5898-4ed4-a778-0795e9b83ebd",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "# If the format is set to \"csv\", it saves a csv file to the workspace.\n",
    "nbia.getDoiMetadata(doi = \"https://doi.org/10.7937/K9/TCIA.2018.PAT12TBS\", output = \"series\", format = \"csv\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0d5c86f9-91e2-44a4-8cd3-d7d1c7c957e0",
   "metadata": {},
   "source": [
    "## getSimpleSearchWithModalityAndBodyPartPaged\n",
    "\n",
    "**Params: (collections = [], species = [], modalities = [], bodyParts = [], manufacturers  = [], <br>\n",
    "fromDate = \"\", toDate = \"\", patients = [], minStudies: int = 0, modalityAnded = False, <br>\n",
    "start = 0, size = 10, sortDirection = 'ascending', sortField = 'subject', api_url = \"\", format = \"\")**\n",
    "\n",
    "* *All parameters are optional.*\n",
    "* Takes the same parameters as the SimpleSearch GUI\n",
    "* Use more parameters to narrow the number of subjects received.\n",
    "* **Note: This function only supports output of JSON format, please leavel the format parameter as it.**"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2eb77ad2-e470-4abd-b3ec-03c299727dab",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "nbia.getSimpleSearchWithModalityAndBodyPartPaged(collections = [\"CPTAC-LUAD\"], modalities = [\"CT\"], format = \"\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d741e9df-db33-4cd0-ba20-9a47107b7b8b",
   "metadata": {
    "jp-MarkdownHeadingCollapsed": true,
    "tags": []
   },
   "source": [
    "# 4. Download Functions\n",
    "\n",
    "Detailed usage of some of these functions can be found at https://github.com/kirbyju/TCIA_Notebooks/blob/main/TCIA_REST_API_Downloads.ipynb."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a5049e1e-bdf8-46c0-9992-d67a2e6ba736",
   "metadata": {
    "jp-MarkdownHeadingCollapsed": true,
    "tags": []
   },
   "source": [
    "## downloadSeries\n",
    "\n",
    "**Params: (series_data, number = 0, path = \"\", hash = \"\", api_url = \"\",<br>\n",
    "input_type = \"\", format = \"\", csv_filename = \"\")**\n",
    "\n",
    "* Ingests a set of seriesUids and downloads them\n",
    "* By default, series_data expects JSON containing \"SeriesInstanceUID\" elements.\n",
    "* Set number = n to download the first n series if you don't want the full dataset.\n",
    "* Set hash = \"y\" if you'd like to retrieve MD5 hash values for each image.\n",
    "* Saves to tciaDownload folder in current directory if no path is specified\n",
    "* Set input_type = \"list\" to pass a list of Series UIDs instead of JSON.\n",
    "* Set input_type = \"manifest\" to pass the path of a *.TCIA manifest file as series_data.\n",
    "* Format can be set to \"df\" or \"csv\" to return series metadata.\n",
    "* Setting a csv_filename will create the csv even if format isn't specified.\n",
    "* The metadata includes info about series that have previously been downloaded."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e2aba213-47de-4cd0-aaa9-9a1f8bcb28d6",
   "metadata": {
    "jp-MarkdownHeadingCollapsed": true,
    "tags": []
   },
   "source": [
    "## downloadImage\n",
    "**Params: (downloadImage(seriesUID, sopUID, path = \"\", api_url = \"\"))**\n",
    "\n",
    "* Ingests a seriesUids and SopInstanceUid and downloads the image"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "821eafea-5785-4c10-9e61-33823687d42b",
   "metadata": {
    "jp-MarkdownHeadingCollapsed": true,
    "tags": []
   },
   "source": [
    "# 5. Image Visualization Functions\n",
    "\n",
    "Detailed usage of these functions can be found at https://github.com/kirbyju/TCIA_Notebooks/blob/main/TCIA_REST_API_Queries.ipynb."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0d09dd17-d16a-4757-803a-9d64efbf409e",
   "metadata": {
    "jp-MarkdownHeadingCollapsed": true,
    "tags": []
   },
   "source": [
    "## viewSeries\n",
    "\n",
    "**Params: (seriesUid = \"\", path = \"\")**\n",
    "\n",
    "* Visualizes a Series (scan) you've downloaded in the notebook\n",
    "* Requires EITHER a seriesUid or path parameter\n",
    "* Leave seriesUid empty if you want to provide a custom path.\n",
    "* The function assumes \"tciaDownload/\\<seriesUid\\>/\" as path if seriesUid is provided since this is where downloadSeries() saves data."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c3ebe85e-8388-4cac-be12-b5649db85e92",
   "metadata": {
    "jp-MarkdownHeadingCollapsed": true,
    "tags": []
   },
   "source": [
    "## viewSeriesAnnotation\n",
    "\n",
    "**Params: (seriesUid = \"\", seriesPath = \"\", annotationUid = \"\", annotationPath = \"\")**\n",
    "\n",
    "* Visualizes a Series (scan) you've downloaded in the notebook\n",
    "* Adds an overlay from the annotative series (SEG or RTSTRUCT)\n",
    "* Directs to the correct visualization function depending on the modality of the annotative series\n",
    "* Requires EITHER a seriesUid or path parameter for the reference series\n",
    "* Requires EITHER a annotationUid or path parameter for the segmentation series\n",
    "* Opens a file browser for users to choose folder/file if the required parameters are not specified\n",
    "* Leave seriesUid and/or annotationUid empty if you want to provide a custom path\n",
    "* The function assumes \"tciaDownload/\\<UID\\>/\" as path if seriesUid and/or annotationUid is provided since this is where downloadSeries() saves data\n",
    "* ***<font color='red'>Note that non-axial images might not be correctly displayed.***"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "437cf74b-38b5-4636-9892-22aeab1aea76",
   "metadata": {},
   "source": [
    "### Using NSCLC-Radiomic dataset to demostrate the visualization of segmentation data\n",
    "In the following demostrations, I will show how to visualize SEG and RTSTRUCT data as an overlay on top of the reference series.\n",
    "* Ref Series UID: 1.3.6.1.4.1.32722.99.99.298991776521342375010861296712563382046\n",
    "* SEG Series UID: 1.2.276.0.7230010.3.1.3.2323910823.20524.1597260509.554\n",
    "* RT  Series UID: 1.3.6.1.4.1.32722.99.99.298991776521342375010861296712563382046\n",
    "\n",
    "The workflow is the same as the base viewSeries() function, in which the user inputs either the series UID or the path to the DICOM folder/file.\n",
    "\n",
    "In the visualization, users are able to toggle on and off the overlay as they desire, or individual segments if there are more than one presented in the data."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "546c4737-7e5a-4284-9b50-7d5e8cc05b3e",
   "metadata": {},
   "outputs": [],
   "source": [
    "# This visualizes the SEG DICOM file\n",
    "nbia.viewSeriesAnnotation(\"\", \"/Users/adam/Documents/SlicerDICOMDatabase/TCIALocal/1.3.6.1.4.1.32722.99.99.298991776521342375010861296712563382046/images\", \"\", \"/Users/adam/Documents/SlicerDICOMDatabase/TCIALocal/1.2.276.0.7230010.3.1.3.2323910823.20524.1597260509.554/images/1-1.dcm\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "27b1fb4d-aafd-43e2-bcca-8f2414386c2d",
   "metadata": {},
   "outputs": [],
   "source": [
    "# This visualizes the RTSTRUCT DICOM file\n",
    "nbia.viewSeriesAnnotation(\"\", \"/Users/adam/Documents/SlicerDICOMDatabase/TCIALocal/1.3.6.1.4.1.32722.99.99.298991776521342375010861296712563382046/images\", \"\", \"/Users/adam/Documents/SlicerDICOMDatabase/TCIALocal/1.3.6.1.4.1.32722.99.99.227938121586608072508444156170535578236/images/1-1.dcm\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f4140994-2c59-4142-a1c1-334b73b3f188",
   "metadata": {},
   "outputs": [],
   "source": [
    "# The function will prompt the user to choose the folder and/or file\n",
    "nbia.viewSeriesAnnotation()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6cb82891-72bc-4345-9cc7-dbd77e4c677f",
   "metadata": {
    "jp-MarkdownHeadingCollapsed": true,
    "tags": []
   },
   "source": [
    "## viewSeriesSEG\n",
    "\n",
    "**Params: (seriesPath = \"\", SEGPath = \"\")**\n",
    "\n",
    "* Visualizes a Series (scan) you've downloaded in the notebook\n",
    "* Adds an overlay from the SEG series\n",
    "* Requires a path parameter for the reference series\n",
    "* Requires the file path for the annotative series\n",
    "* ***<font color='red'>Not recommended to be used as a standalone function***"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "161a5eef-4071-4acb-b8de-3fe9c148b888",
   "metadata": {},
   "outputs": [],
   "source": [
    "nbia.viewSeriesSEG(\"/Users/adam/Documents/SlicerDICOMDatabase/TCIALocal/1.3.6.1.4.1.32722.99.99.298991776521342375010861296712563382046/images\", \"/Users/adam/Documents/SlicerDICOMDatabase/TCIALocal/1.2.276.0.7230010.3.1.3.2323910823.20524.1597260509.554/images/1-1.dcm\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "59a5d66d-00e7-4e47-8bb1-a51ff16f9518",
   "metadata": {
    "jp-MarkdownHeadingCollapsed": true,
    "tags": []
   },
   "source": [
    "## viewSeriesRT\n",
    "\n",
    "**Params: (seriesPath = \"\", RTath = \"\")**\n",
    "\n",
    "* Visualizes a Series (scan) you've downloaded in the notebook\n",
    "* Adds an overlay from the RTSTRUCT series\n",
    "* Requires a path parameter for the reference series\n",
    "* Requires the file path for the annotative series\n",
    "* ***<font color='red'>Not recommended to be used as a standalone function***"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4740a159-d16b-4fb1-8247-4261c13a2fd6",
   "metadata": {},
   "outputs": [],
   "source": [
    "nbia.viewSeriesRT(\"/Users/adam/Documents/SlicerDICOMDatabase/TCIALocal/1.3.6.1.4.1.32722.99.99.298991776521342375010861296712563382046/images\", \"/Users/adam/Documents/SlicerDICOMDatabase/TCIALocal/1.3.6.1.4.1.32722.99.99.227938121586608072508444156170535578236/images/1-1.dcm\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "26a264aa-011f-4150-a5d1-7eccb652a21e",
   "metadata": {
    "jp-MarkdownHeadingCollapsed": true,
    "tags": []
   },
   "source": [
    "## makeVizLinks\n",
    "\n",
    "**Params: (series_data, csv_filename=\"\")**\n",
    "\n",
    "* Ingests JSON output of getSeries() or getSharedCart()\n",
    "* Creates URLs to visualize them in a browser\n",
    "* The links appear in the last 2 columns of the dataframe.\n",
    "* TCIA links display the individual series described in each row.\n",
    "* IDC links display the entire study (all scans from that time point).\n",
    "* IDC links may not work if they haven't mirrored the series from TCIA, yet.\n",
    "* This function only works with fully public datasets (no limited-access data).\n",
    "* Optionally accepts a csv_filename parameter if you'd like to export a CSV file."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "240c55a0-253f-45a0-ab49-7d54f9ad0718",
   "metadata": {
    "jp-MarkdownHeadingCollapsed": true,
    "tags": []
   },
   "source": [
    "# 6. Other Functions"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "41aa2a70-c9e1-4d57-a33c-9667a701d91e",
   "metadata": {
    "tags": []
   },
   "source": [
    "## setApiUrl\n",
    "\n",
    "**Params: (endpoint, api_url)**\n",
    "\n",
    "* Checks for valid security tokens where needed\n",
    "* Because it is called by other functions to select base URL, ***<font color='red'>please do NOT use this function</font>***.\n",
    "* ***Note: Nearly all functions allow you to specify **api_url** as a query parameter.  This allows you to specify if you'd like to access restricted collections or the [National Lung Screening Trial (NLST)](https://doi.org/10.7937/TCIA.HMQ8-J677) collection, which lives on a separate server due to its size (>26,000 patients!).  We'll provide examples to show how this works later in the notebook.***"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ca62a668-fac4-4f05-be73-de5279ce9938",
   "metadata": {
    "tags": []
   },
   "source": [
    "## manifestToList\n",
    "\n",
    "**Params: (manifest)**\n",
    "\n",
    "* Ingests a TCIA manifest file and removes header\n",
    "* Returns a list of series UIDs\n",
    "* Because it is primarily a helper function used by downloadSeries() and makeSeriesReport(), ***<font color='red'>please do NOT use this function</font>***."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e1204cf4-1aea-4d44-9475-65adba90eed4",
   "metadata": {
    "tags": []
   },
   "source": [
    "## getToken\n",
    "**Params: (user = \"\", pw = \"\", api_url = \"\")**\n",
    "\n",
    "* Retrieves security token to access APIs that require authorization\n",
    "* Provides interactive prompts for user/pw if they're not specified as parameters\n",
    "* Uses getToken() for querying restricted collections with \"Search API\"\n",
    "* Uses getToken(api_url = \"nlst\") for \"Advanced API\" queries of National Lung Screening Trial\n",
    "* Sets expiration time for tokens (2 hours from creation)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "868b661f-6f32-42e6-8f48-c975df1cebdd",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "nbia.getToken()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bf989e69-3697-4ca8-a320-2a3fcf32d50d",
   "metadata": {
    "tags": []
   },
   "source": [
    "## refreshToken\n",
    "\n",
    "**Params: (api_url = \"\")**\n",
    "\n",
    "* Refreshes security token to extend access time for APIs that require authorization\n",
    "* Must first use getToken() to create a token\n",
    "* Because it is primarily used by getToken() to keep the login seesion alive, ***<font color='red'>please do NOT use this function</font>***."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d343d43c-b00a-485b-ac04-c79fe9592a23",
   "metadata": {
    "tags": []
   },
   "source": [
    "## logoutToken\n",
    "\n",
    "**Params: (api_url = \"\")**\n",
    "\n",
    "* Logs out of a security token for APIs that require authorization\n",
    "* Must first use getToken() to create a token"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "029c67e4-56bb-44a9-9254-e9b8fd4d9922",
   "metadata": {},
   "outputs": [],
   "source": [
    "nbia.logoutToken()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "39f05a8f-de06-4d17-9fad-22f35aee1292",
   "metadata": {
    "tags": []
   },
   "source": [
    "## makeCredentialFile\n",
    "**Params: (user = \"\", pw = \"\")**\n",
    "\n",
    "* Creates a credential file to use with NBIA Data Retriever\n",
    "* Provides interactive prompts for user/pw if they're not specified as parameters\n",
    "* ***Note: A credential file is a text file that passes the user's credentials in the following format:***\n",
    "    * userName = YourUserName\n",
    "    * passWord = YourPassword\n",
    "    * *Both parameters are case-sensitive.*\n",
    "* Users are encouraged to take a look at the file being generated.\n",
    "* Documentation at https://wiki.cancerimagingarchive.net/x/2QKPBQ and notebook at https://github.com/kirbyju/TCIA_Notebooks/blob/main/TCIA_Linux_Data_Retriever_App.ipynb."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3d330091-f2eb-4571-968d-13ca7ad3a934",
   "metadata": {},
   "outputs": [],
   "source": [
    "nbia.makeCredentialFile()"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1ffca439-488b-4a30-9dfe-a3a6db3c53c9",
   "metadata": {
    "tags": []
   },
   "source": [
    "## makeSeriesReport\n",
    "\n",
    "**Params: (series_data, input_type = \"\", format = \"\", filename = None, api_url = \"\")**\n",
    "\n",
    "* Ingests JSON output from any function that returns series-level data and creates summary report\n",
    "* Specify input_type = \"manifest\" to ingest a *.TCIA manifest file or \"list\" for a python list of UIDs.\n",
    "* If input_type = \"manifest\" or \"list\" and there are series UIDs that are restricted, you must call getToken() with a user ID that has access to all UIDs before calling this function.\n",
    "* Specifying api_url is only necessary if you are using input_type = \"manifest\" or \"list\" with NLST data (e.g. api_url = \"nlst\").\n",
    "* Specify format = \"var\" to return the report values as a dictionary.\n",
    "* Access variables example after saving function output to report_data: subjects = report_data[\"subjects\"].\n",
    "* Specify format = \"file\" to save the report to a file.\n",
    "* Specify a filename parameter to set a filename if you don't want the default filename."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "456d291f-43a2-4d74-b9c9-ee8e2390171f",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "data = nbia.getSeries(collection = \"CPTAC-SAR\", patientId = \"\", studyUid = \"\", seriesUid = \"\", \n",
    "                    modality = \"\", bodyPart = \"\", manufacturer = \"\", manufacturerModel = \"\", format = \"df\")\n",
    "nbia.makeSeriesReport(data)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ba55aff9-3031-48d8-b40c-1a2f8c79e569",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "data = nbia.getSharedCart(name = \"nbia-49121659384603347\")\n",
    "nbia.makeSeriesReport(data)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9894d651-2adf-4629-9036-e2bfa4b8dc55",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "manifest = requests.get(\"https://wiki.cancerimagingarchive.net/download/attachments/22512757/doiJNLP-Fo0H1NtD.tcia?version=1&modificationDate=1534787017928&api=v2\")\n",
    "with open('RIDER_Breast_MRI.tcia', 'wb') as f:\n",
    "    f.write(manifest.content)\n",
    "nbia.makeSeriesReport(\"RIDER_Breast_MRI.tcia\", input_type = \"manifest\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "031c2107-dc65-4702-8c58-53a7fb5d11eb",
   "metadata": {},
   "source": [
    "We can also use other parameters to make the report in the format we want."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c9d0f1e1-58b6-4282-a2ed-c7102c58d421",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "data = nbia.getSharedCart(name = \"nbia-49121659384603347\")\n",
    "nbia.makeSeriesReport(data, format = \"file\", filename = \"MyCart.txt\")"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1ecae8ae-f598-4a09-bfdc-20ea3adaae25",
   "metadata": {
    "tags": []
   },
   "outputs": [],
   "source": [
    "data = nbia.getSharedCart(name = \"nbia-49121659384603347\")\n",
    "nbia.makeSeriesReport(data, format = \"var\")"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "40400dc7-ef7e-458d-9a6b-f68661f5c23a",
   "metadata": {
    "id": "DYXsNGcY93B8",
    "jp-MarkdownHeadingCollapsed": true,
    "tags": []
   },
   "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/) and [Adam Li](https://www.linkedin.com/in/adam-l-713885121). 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": {
  "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": 5
}