The NBIA Data Retriever is a software product you can download and install so that you can download radiology images from from the TCIA Radiology Portal. This guide documents the command-line interface (CLI) of the NBIA Data Retriever. If you are using Linux, you can access NBIA Data Retriever's command-line interface, which does not require the desktop environment. See the Cancer Imaging Archive User's Guide to learn how to use the Graphical User Interface (GUI) of the TCIA Radiology Portal.
Downloading the NBIA Data Retriever for Linux
The NBIA Data Retriever CLI is available on both Red Hat Package Manager (RPM) and Debian (DEB) operating systems.
Supported Operating Systems
The NBIA Data Retriever command-line interface for Linux supports the following operating systems:
- RPM (tested on Fedora 40 Workstation, OEL 9.4)
- Deb (tested on Ubuntu 2024 LTS)
Click one of the following links to download the NBIA Data Retriever for that operating system. See Downloading Study Data for information on using this application to download data.
- RPM (tested on centOS)
To run this file, type the following at the command prompt:sudo yum -v -y remove NBIADataRetriever-4.4.2.x86_64.rpm;sudo yum -y install NBIADataRetriever-4.4.3-1.x86_64.rpm - DEB (tested on Ubuntu)
To run this file, type the following at the command prompt:sudo -S dpkg -r nbia-data-retriever-4.4.2.deb;sudo -S dpkg -i nbia-data-retriever-4.4.3-1.deb
Installing the NBIA Data Retriever on Linux
After downloading, double-click to install the package through a GUI or you can run the following in a terminal:
mkdir /usr/share/desktop-directories/ wget -P ~/NBIA-Data-Retriever https://cbiit-download.nci.nih.gov/nbia/releases/ForTCIA/NBIADataRetriever_4.4/nbia-data-retriever-4.4.3-1.deb dpkg -i ~/NBIA-Data-Retriever/nbia-data-retriever-4.4.3-1.deb
Running the NBIA Data Retriever on Linux
In the two sample commands that follow, the -l <credential file> option is only required when the manifest file contains series from restricted collections. It is unnecessary when the manifest file only contains series from public collections.
To run the NBIA Data Retriever on CentOS, run the following sample command.
/opt/NBIADataRetriever/bin/NBIADataRetriever --cli <location>/<manifest file name>.tcia -d <parent location>/<download directory> -l <location>/<credential file> -v –f
To run the NBIA Data Retriever on Ubuntu, run the following sample command.
/opt/nbia-data-retriever/bin/nbia-data-retriever --cli <location>/<manifest file name>.tcia -d <parent location>/<download directory> -l <location>/<credential file> -v –f
A credential file is a text file that passes the user's credentials in the following format:
userName=YourUserName passWord=YourPassword
The parameters "userName" and "passWord" are case-sensitive.
CLI Parameters
The options available for the command line interface are described in the following table.
If you use the NBIA Data Retriever CLI with the -v, -f, or -q options, and want to access restricted collection(s), put these options after the user credential parameters.
| Option | Description |
|---|---|
| -c, -C, --cli, --CLI | Indicates running as a CLI app |
| -cd, -CD, --CD or –cd | Run with classic directory naming, which organizes files in a child folder under the destination folder as follows: Collection Name > Patient ID > Study Instance UID > Series Instance UID |
| -d, -D <download directory> | Required. The user must have write permission for the directory specified with this option. |
| -dd, -DD, --DD or –dd | Run with descriptive directory naming, which is the default. A descriptive directory name organizes the files in a child folder under the destination folder as follows: Collection Name > Patient ID > Study Date + Study ID + Study Description (54 char max) + last 5 digits of Study Instance UID > Series Number + Series Description (54 char max) + last 5 digits of Series Instance UID |
| -f, -F | Skip the series the user does not have access to. Force the user to download the series if the user has access. Default is false. |
| -l <credential file> | Required when the manifest file has series from restricted collections. Optional when the manifest file has series from public collections only. |
| -m, -M, --md5, –MD5 | Enable validation of the checksums of the downloaded files. Default is that checksums will not be validated. |
| -p, -P <password> | Optional |
| -q, -Q | Quiet. Default is false. |
| -u, -U <user name> | Optional |
| -v, -V | Verbose. Default is false. |
Resuming an Interrupted Download Using the CLI
If your download is interrupted, you can resume it using the CLI in the following way.
- At the command-line prompt and from the same directory that you initially used to invoke NBIA Data Retriever, type the same CLI command again. Alternately, you can run the CLI command from a directory other than the original directory by adding the “-d” option followed by the original directory.
The NBIA Data Retriever reviews what has already been downloaded, then asks “Do you want to download all or download only missing series?" - Enter A to download all, M to download missing series, or E to exit the program.