This textbook was written for the clinical research community at Johns Hopkins leveraging the precision medicine analytics platform (PMAP). These notebooks are available in html form on the Precision Medicine portal as well as in computational form in the CAMP-share folder on Crunchr (Crunchr.pm.jh.edu).

What is XNAT

XNAT is an open-source imaging informatics platform developed by the Neuroinformatics Research Group at Washington University with a REST-API for medical imaging data management and accessibility to various projects. Instead of organizing/handling DICOMs in the file organizer, one can access DICOMs (and associated metadata) on demand from their XNAT account. </br> </br> XNAT includes the following features:

This is the Link to an XNAT introduction Video

Can I use XNAT without obtaining IRB approval?

Absolutely! We’ve created a series of Jupyter Notebooks, starting with this one, precisely to make it easy to explore and learn about XNAT without the need to have one of those pesky IRB protocols. The Notebooks are structured around an open-source, de-identified dataset.

Prerequisites to implement this notebook without an IRB protocol:
Go the XNAT login page
Click the “Johns Hopkins Login” button to login using your JHED ID.
Once you’ve successfully logged in, under Projects, click on "Demo Project" to get to the following screen:

This is the sample dataset that this notebook uses. Notice the Project ID is Indicated as "Demo-Project".

Prerequisites to implement this notebook if you have an IRB protocol:

To use XNAT:

In order to use XNAT, you must have an XNAT account and session URL

XNAT account username should be JHED ID

</br> Can use XNAT either with IRB project or the default sample RSNA Brain Tumor Dataset. This notebook will display accessibility using the sample dataset.

How to Access DICOMs from XNAT via Jupyter Notebook Tutorial

Learning Objectives

  1. Install and Connect to XNAT Session
  2. Understand Data Organzation in XNAT
  3. Visualize the data with Pydicom

Table of contents

Prerequisites to implement this notebook:

  1. IRB approved Study
  2. XNAT project provisioned Study
  3. XNAT project permissions granted and 'honest broker' step completed by CCDA

Purpose:

Currently, accessing patient DICOMs requires managing several files and loading them.
Using an XNAT Session to programmatically access DICOMs using Jupyter notebook, the user can easily directly load a file instead of having to manage the various files in the file system and loading them one-by-one.

Install and Connect to XNAT Session

Install/Import XNAT and subsequent complementary packages for viewing and analysis:

Install XNAT using pip only if not installed already </br> XNAT to be added as default library to Crunchr Container, so should only have to import

How to Connect to using your XNAT Session URL and XNAT User ID
Specify your XNAT session URL (should be provided to you), username (JHED ID without @jh.edu), and Project ID.

Then enter your XNAT password to allow access:

View All Accessible Studies in XNAT

How to view all accessible projects in XNAT To access all the projects you are allowed access to via your XNAT account, use the projects object of your session.
Thereby, session.projects displays all accessible projects/datasets

4 Projects shown here: "Daisy", "kaggle", "DevOpsTesting5", and "DevOpsTesting6"

How to Select a specific project/dataset within your session?

Specify the Project name within session.projects

Example Dataset used: RSNA-MICCAI Brain Tumor Radiogenomic Classification
Specify the Project of interest by using the Project ID as attribute to session.project

Project ID is specified as first attribute of each project in session.project list above or in XNAT REST-API

kaggle is the project ID for the RSNA-MICCAI Brain Tumor Radiogenomic Classification sample dataset

How to get total number of Patients within a Project/Dataset:

Specify the specific Project in your session (as shown above), then implement the subjects parameter of the dataset.

session.projects["kaggle"].subjects object includes all subjects in the project.

To calculate the total Number of all Patients within Dataset, calculate the length of the session.projects["kaggle"].subjects object

Access All Patients in XNAT Study

How to Access list of all Patient Numbers/Labels in respective Project
This allows the user to explore the study with its various patients and imaging series, aid their research analysis by knowing all the patients and number of patients in the study. This list can also be used to modify inclusion criteria.

Thereby, by printing the subject.label Patient ID for all Patient Data in the XNAT Study session.projects["kaggle"].subjects.values() using the below forloop, we can access the Patient IDs for all Patients in the Study:

Understanding Data Organization in XNAT:

XNAT has specific terminology to its Data Organization and understanding aides in research analysis of the study. The Diagram below explains the organization format.

Dataset > Patient > MR Session > Patient Metadata + Scans

Scans > T2w, T1w, FLAIR, T1wCE

Study 1 can be IRB Study A, etc.

How to access Specific Patient Scan

Create File object for particular Subject Scan
File Object - Allows us to use, access and manipulate the particular file

ex: T2w Scan for Patient "00822"

Parameters Include:

Visualize T2w Scan and DICOM Metadata

It is crucial to visualize DICOM Data to understand the study and patient imaging series -- which allows researchers to better build their analysis. Instead of managing various files, XNAT allows one to easily view the Patient Imaging series directly in Jupyter Notebook.

Using Pydicom, we read the File Object (defined previously, T2w image) and display it using matplotlib.pyplot

How to Access DICOM Metadata

By Accesing the raw DICOM Header Metadata, researchers can better understand the study and modify inclusion/exclusion criteria. Via XNAT, the user does not have to manage metadata and can instead view it easily using the File Object

Using Pydicom.dcmread function to read the opened File Object (as defined in the cells above), we can define the DICOM metadata variable and display it.

How to Download Patient Scans:

Users can locally download Patient Imaging Series if they need local access to the file.

Specify the Patient Scan using the same File Object Parameters mentioned previously
Instead of creating File Object, only Specify Patient Scan
download_dir requires path to file where Patient Series should be downloaded to.