Using the Rxnat Package

Adi Gherman

2019-04-25


What is XNAT?

XNAT is an open source imaging informatics platform developed by the Neuroinformatics Research Group at Washington University. XNAT was originally developed in the Buckner Lab at Washington University, now at Harvard University. It facilitates common management, productivity, and quality assurance tasks for imaging and associated data. Thanks to its extensibility, XNAT can be used to support a wide range of imaging-based projects.

Who is using XNAT?

There are several projects that currently use XNAT to manage a vast number of datasets.

For a more complete list of XNAT implementations around the world you can click here.

Installing the Rxnat package

You can install Rxnat from github with:

# install.packages("devtools")
devtools::install_github("adigherman/Rxnat")

Accessing XNAT Data

How to get a username/password for a XNAT project

XNAT projects can be public or private. In order to access a private repository a set of credentials are required. To obtain a user name and password combo you will need to visit:

Establishing a XNAT connection with the Rxnat package

The Rxnat package will accept credentials provided in the function call or read from the system environment.

Function parameters

To establish a connection using the credentials as function parameters we can call the xnat_connect function:

Setting up system environment variables

To use system environment variables we need to add them to the .Renviron file located in the user’s home folder. Use Sys.getenv("HOME") to get the path (for unix/osx users the location can be easily accessed with ~, eg. vi ~/.Renviron). The Rxnat package will be able to automatically read / use a system environment variable provided the following format is used: XXXX_Rxnat_USER and XXXX_Rxnat_PASS. XXXX is provided as an argument when an XNAT connection is initiated.

As an example NITRC is used as argument and the system environment variables names should be NITRC_Rxnat_USER, and NITRC_Rxnat_PASS.

NITRC has some public image repositories, a username and password are not required to connect/query them. To create a connection to the public NITRC resources we call the xnat_connect function.

Get list of available XNAT projects

Once a connection is established using the xnat_connect function a list of available projects can be easily retrieved by using the class internal function projects:

nitrc_projects <- nitrc$projects()
head(nitrc_projects[c('ID','name')])
#>             ID                                                  name
#> 1        ABIDE                                                 ABIDE
#> 2     ABIDE_II                                              ABIDE_II
#> 3     adhd_200                                              ADHD-200
#> 4  beijing_enh                                      Beijing Enhanced
#> 5 beijing_eoec                         Beijing Eyes Open Eyes Closed
#> 6         corr Consortium for Reliability and Reproducibility (CoRR)

Retrieve a list with all accessible subjects

A full list of subjects for each XNAT connection can be retrieved using the subjects function:

nitrc_subjects <- nitrc$subjects()
head(nitrc_subjects)
#>          project          ID        label gender handedness yob education
#> 1 cs_schizbull08 xnat_S02601 BPDwoPsy_030      F          R  NA        NA
#> 2 cs_schizbull08 xnat_S02602 BPDwoPsy_031      F          R  NA        NA
#> 3 cs_schizbull08 xnat_S02603 BPDwoPsy_032      M          R  NA        NA
#> 4 cs_schizbull08 xnat_S02604 BPDwoPsy_033      M          R  NA        NA
#> 5 cs_schizbull08 xnat_S02605 BPDwoPsy_034      M          R  NA        NA
#> 6 cs_schizbull08 xnat_S02606 BPDwoPsy_035      M          R  NA        NA
#>   ses                               group race ethnicity
#> 1  NA Bipolar Disorder: Without Psychosis   NA        NA
#> 2  NA Bipolar Disorder: Without Psychosis   NA        NA
#> 3  NA Bipolar Disorder: Without Psychosis   NA        NA
#> 4  NA Bipolar Disorder: Without Psychosis   NA        NA
#> 5  NA Bipolar Disorder: Without Psychosis   NA        NA
#> 6  NA Bipolar Disorder: Without Psychosis   NA        NA

Get full list of experiments

To obtain a full list of experiments the experiments function will be used:

nitrc_experiments <- nitrc$experiments()
head(nitrc_experiments)
#>          project      subject          ID               type
#> 1 cs_schizbull08 BPDwoPsy_030 xnat_E02615 xnat:mrSessionData
#> 2 cs_schizbull08 BPDwoPsy_031 xnat_E02617 xnat:mrSessionData
#> 3 cs_schizbull08 BPDwoPsy_032 xnat_E02619 xnat:mrSessionData
#> 4 cs_schizbull08 BPDwoPsy_033 xnat_E02621 xnat:mrSessionData
#> 5 cs_schizbull08 BPDwoPsy_034 xnat_E02623 xnat:mrSessionData
#> 6 cs_schizbull08 BPDwoPsy_035 xnat_E02625 xnat:mrSessionData
#>             label age
#> 1 BPDwoPsy_030_MR   9
#> 2 BPDwoPsy_031_MR  15
#> 3 BPDwoPsy_032_MR   7
#> 4 BPDwoPsy_033_MR   8
#> 5 BPDwoPsy_034_MR  10
#> 6 BPDwoPsy_035_MR   8

Get the complete list of resources for a specific experiment

The scan resources for an experiment can be retrieved using the get_xnat_experiment_resources function:

xnat_E00026_resources <- nitrc$get_xnat_experiment_resources('xnat_E00026')
head(xnat_E00026_resources[c('Name','URI')])
#>                               Name
#> 1    scan_mprage_anonymized.nii.gz
#> 2 scan_mprage_skullstripped.nii.gz
#> 3                 scan_rest.nii.gz
#> 4    scan_mprage_anonymized.nii.gz
#> 5 scan_mprage_skullstripped.nii.gz
#> 6                 scan_rest.nii.gz
#>                                                                                                                    URI
#> 1        /data/experiments/xnat_E00026/scans/anat_mprage_anonymized/resources/3967/files/scan_mprage_anonymized.nii.gz
#> 2  /data/experiments/xnat_E00026/scans/anat_mprage_skullstripped/resources/3968/files/scan_mprage_skullstripped.nii.gz
#> 3                                  /data/experiments/xnat_E00026/scans/func_rest/resources/3969/files/scan_rest.nii.gz
#> 4       /data/experiments/xnat_E00026/scans/anat_mprage_anonymized/resources/11985/files/scan_mprage_anonymized.nii.gz
#> 5 /data/experiments/xnat_E00026/scans/anat_mprage_skullstripped/resources/11986/files/scan_mprage_skullstripped.nii.gz
#> 6                                 /data/experiments/xnat_E00026/scans/func_rest/resources/11987/files/scan_rest.nii.gz

Query the XNAT projects for matching entries

If you are interested just in a subset of subjects/experiments that match a certain criteria you can use the query_scan_resources function. Accepted query parameters are:

To retrieve a list of all subject IDs and associated experiment IDs we can use the query_scan_resources function. In the example below, we are querying the HCP XNAT database for all subjects belonging the the HCP_500 project with scans taken at age 26.

nitrc_age_26 <- query_scan_resources(nitrc,age='26')
head(nitrc_age_26[c("subject_ID","experiment_ID", "Project", "Age")])
#>        subject_ID   experiment_ID Project Age
#> 1 NITRC_IR_S05244 NITRC_IR_E10507     ixi  26
#> 2 NITRC_IR_S05267 NITRC_IR_E10530     ixi  26
#> 3 NITRC_IR_S05270 NITRC_IR_E10533     ixi  26
#> 4 NITRC_IR_S05278 NITRC_IR_E10541     ixi  26
#> 5 NITRC_IR_S05394 NITRC_IR_E10657     ixi  26
#> 6 NITRC_IR_S05427 NITRC_IR_E10690     ixi  26

Getting Data: Download a single scan image/resource file

To download a single file we will use the download_file function. Using the first experiment_ID from the above example, we will get all scan resources associated with it first.

scan_resources <- get_scan_resources(nitrc,'xnat_E00026')
scan_resources[1,c("Name","URI")]

To download the resource file (100307_3T_BIAS_BC.nii.gz) we will do:

> download_xnat_file(nitrc,"/data/experiments/xnat_E00026/scans/anat_mprage_anonymized/resources/3967/files/scan_mprage_anonymized.nii.gz", file_dir = tempdir())
[1] "/var/folders/kr/05bm5krj0r3fpwxfdmx4xthm0000gn/T//RtmpTNSN5E/scan_mprage_anonymized.nii.gz"

Getting Data: Download a directory of data

To download all the T1 type images from experiment ConnectomeDB_E03657 we will use the download_xnat_dir function.

download_xnat_dir(nitrc, experiment_ID='NITRC_IR_E10507',scan_type='T2', file_dir = tempdir(), verbose=TRUE)
/var/folders/kr/05bm5krj0r3fpwxfdmx4xthm0000gn/T//RtmpTNSN5E/NITRC_IR_E10507.zip
Downloading: 5.2 MB     [1] "/var/folders/kr/05bm5krj0r3fpwxfdmx4xthm0000gn/T//RtmpTNSN5E/NITRC_IR_E10507.zip"