Welcome to xnat_downloader’s documentation!¶
xnat_downloader takes dicoms from an xnat server and saves them in BIDS format
Installation¶
local install¶
- clone the repository from github
git clone https://github.com/HBClab/xnat_downloader
- within the terminal, cd into the place where you downloaded the repository.
If you see a setup.py, in the directory (use
ls), then you are in the right place.
cd /path/to/repository/xnat_downloader
- Install the repository using python.
python setup.py install
docker install¶
docker pull jdkent/xnat_downloader
Usage¶
usage: xnat_downloader [-h] [-c CONFIG] [-i INPUT_JSON]
xnat_downloader downloads xnat dicoms and saves them in BIDs compatible
directory format
optional arguments:
-h, --help show this help message and exit
-c CONFIG, --config CONFIG login file (contains user/pass info)
Required arguments:
-i INPUT_JSON, --input_json INPUT_JSON json file defining inputs for this script.
json format¶
The json file has multiple fields specifying where and how the data are downloaded from xnat.
- destination: string
(required) The absolute path to the output base directory of the BIDS dataset
- project: string
(required) The name of the project on xnat
- server: string
(required) The base URL to the xnat server (e.g. “https://central.xnat.org”)
- subjects: list
(optional) The subjects you wish to download from xnat. Use the subject names as they are seen on xnat.
- sub_dict: dictionary
(optional) (non-BIDS) If you want to change the subject label that is not represented in the xnat subject name
- session_labels: list
(optional) (non-BIDS) If you want to replace the names of the sessions on xnat with your own list of scans.
Warning
this will not behave as expected if the subject on xnat has a missing “middle” session or an extra session.
- scan_labels: list
(optional) a list of the scans you want to download (if you don’t want to download all the scans).
- num_digits: int
(optional) an integer indicating how many digits the subject number should have. For example if the subject number on xnat is 10, then setting num_digits to 2 will not change the subject 10, but if num_digits was set to 3 then subject 10 will be written as 010.
- scan_dict: dictionary
(conditionally required) (non-BIDS) required if your dicoms are not stored in a BIDS format on xnat. The keys to the dictionary are scan names as they are seen on xnat (e.g. “SAG FSPGR BRAVO”), and the values are the associated reproin (BIDS-ish) name for the scan (e.g. “anat-T1w”).
example json¶
Once installed and the json file is configured, the final step is to call the command.
locally installed: (python2 only)
xnat_downloader -i /path/to/json/file.json
via docker:
docker run \
-v /path/to/out:/out \
-v /path/to/json/:/json \
jdkent:xnat_downloader \
-i /json/file.json
Note: when calling via docker, the destination location should be specified relative to where the path is in the docker container, not on your machine.
FAQ¶
What’s the server address to the University of Iowa’s XNAT installation?¶
How should I specify paths in my json file?¶
Always use absolute paths and do not use ~ to specify your home directory.