Using Jupyter
Accessing Jupyter
To access a running Jupyter notebook server, navigate to it from the top navigation menu. Click on the notebook icon and a new tab will open in your browser with JupyterLab. If no Jupyter servers are currently running, please refer to the Starting and Stopping Jupyter section for instructions on how to start a Jupyter server.
Explore XNAT Data with JupyterLab
JupyterLab is a powerful tool for exploring and analyzing XNAT data in an interactive and flexible environment. This documentation provides a comprehensive guide on leveraging JupyterLab's capabilities to efficiently navigate, manipulate, and analyze XNAT data.
Navigating the file system
When launching a Jupyter server from XNAT, a set of mounts is collected for the container running the Jupyter server, tailored to the specific XNAT context. These mounts provide access to relevant data and resources within the Jupyter container.
After you've accessed JupyterLab, start a terminal and explore these mounts:
Project Mounts
Mounts | Access |
|---|---|
All experiment directories are available. Experiments shared into the project are not available. The experiment directories are organized as follows:
| Read only |
Only if there are project resources. | Read only |
All subject resource directories are available. Only subjects with resources will have directories. | Read only |
Persistent directory for storing your Jupyter notebooks and any other intermediate work/files. | Read / write |
Subject Mounts
As of XNAT 1.8.10 and JupyterHub Integration 1.1.0, resource files from shared subjects and experiments can now be mounted into your Jupyter environment. See: Understanding Data Sharing in XNAT's Security Structure
Mounts | Access |
|---|---|
Only experiments belonging to the specified subject are mounted. Does not support subjects and experiments shared across projects. Can only start Jupyter on a subject from the subjects primary project. The experiment directories are organized as follows:
| Read only |
Only the specified subject will be mounted and only if the subject has resource files. | Read only |
Persistent directory for storing your Jupyter notebooks and any other intermediate work/files. | Read / write |
Experiment Mounts
Mounts | |
|---|---|
Only the specified experiment will be mounted. Can only start a Jupyter server on an experiment from the experiments primary project. The experiment directories are organized as follows:
| Read only |
Persistent directory for storing your Jupyter notebooks and any other intermediate work/files. | Read / write |
User Workspace Directory
Regardless of the context in which you started Jupyter, the directory /workspace/{username} serves as the root location in JupyterLab. This directory not only stores your Jupyter notebooks, which persist between sessions, but also acts as an ideal location for managing git repositories and other data related to your projects. It is recommended to use version control systems like Git to track and manage changes to your notebooks and code. This allows you to easily collaborate, revert changes, and maintain a history of your work. To facilitate the use of Git, a git-config file is created by default at /workspace/{username}/git/config.
Please exercise caution when working within this directory, as data deleted from here is not automatically backed up by XNAT. It is recommended to regularly commit and push your changes to a remote Git repository
Environmental Variables
Environmental variables are utilized by XNAT to enhance the functionality of Jupyter servers. These variables mainly serve the following purposes:
Identify the XNAT context in which Jupyter was started
Establishing connection with XNAT's REST API from Jupyter
To learn more about the configuration and usage of environmental variables, including details about the XNAT_HOST, XNAT_USER, and XNAT_PASS variables, please refer to the Processing URL section in the documentation. Note that while the Container Service plugin is not utilized, the same feature is implemented within the JupyterHub plugin. In case you are using the xnat-docker-compose project, it may be necessary to coordinate with your administrator to update the processing URL setting, which is a core XNAT preference.
Environmental Variable | Comments |
|---|---|
XNAT_HOST | The URL of your XNAT |
XNAT_USER | A temporary token which can be used as a username |
XNAT_PASS | A temporary token which can be used as a password |
XNAT_XSI_TYPE | The XSI type of the XNAT item from where we started Jupyter |
XNAT_ITEM_ID | The ID of the XNAT item |
XNAT_DATA | The location of the mounted XNAT data. Used by XNATpy to locate mounted XNAT data |
Exporting Notebook Results into XNAT
To save or export data generated from your notebook back into XNAT, you must currently utilize the XNAT REST API.
Sample Notebooks
Explore a collection of sample notebooks available on GitHub to kickstart your data analysis. These sample notebooks cover a wide range of use cases and techniques specifically tailored to working with XNAT data. Explore topics such as interacting with the XNAT REST API, utilizing XNATpy, converting XNAT stored searches into pandas dataframes, and leveraging pydicom with XNAT data.