Rxnat: Query and retrieves neuroimaging sets from XNAT projects
Adi Gherman
2021-02-18
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.
XNAT has become the data archiving tool of choice for multiple neuroimaging projects and research labs around the world. Listed below are some of the most popular image repositories that use XANT.
- NITRC - Neuroimaging Informatics Tools and Resources Clearinghouse is currently a free one-stop-shop collaboratory for science researchers that need resources such as neuroimaging analysis software, publicly available data sets, or computing power.
- ConnectomeDB - The Human Connectome Project (HCP) is a project to construct a map of the complete structural and functional neural connections in vivo within and across individuals.
- XNAT Central - XNAT Central is a database for sharing neuroimaging and related data with select collaborators or the general community.
For a more complete list of XNAT implementations around the world you can click here.
Installing the Rxnat package
You can install Rxnat from Neuroconductor (Rxnat will be incorporated with the Feb 2019 release) or from GitHub with:
source("http://neuroconductor.org/neurocLite.R")
neuro_install("Rxnat", release = "stable")
# install.packages("remotes")
remotes::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:
- HCP (Human Connectome Project) - new account request and click on the Register button
- NITRC - new account request. Some of the NITRC hosted projects will require additional access reuquests but this can be easily requested using the NITRC web interface for each project.
- XNAT Central - this is mostly public, but you can also perform a new account request if any of the projects require it.
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:
nitrc <- xnat_connect('https://nitrc.org/ir', username='XXXX', password='YYYY', xnat_name=NULL)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 <- xnat_connect('https://nitrc.org/ir', xnat_name='NITRC')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:
hcp <-xnat_connect('https://db.humanconnectome.org', xnat_name = "hcp")
hcp_projects <- hcp$projects()
head(hcp_projects[c('id','name')])
id name
1 CCF_DMCC_STG DMCC Staging Project
2 HCP_1200 WU-Minn HCP Data - 1200 Subjects
3 HCP_500 WU-Minn HCP Data – 500 Subjects + MEG2
4 HCP_500_RST HCP 500 Subject + MEG2 Restricted Data
5 HCP_900 WU-Minn HCP Data - 900 Subjects + 7T
6 HCP_Coded HCP_CodedRetrieve a list with all accessible subjects
A full list of subjects for each XNAT connection can be retrieved using the subjects function:
hcp_subjects <- hcp$subjects()
head(hcp_subjects)
project ID label gender handedness yob education ses group race ethnicity
1 HCP_Subjects ConnectomeDB_S02177 100004 M NA NA NA NA NA NA NA
2 HCP_Subjects ConnectomeDB_S01982 100206 M NA NA NA NA NA NA NA
3 HCP_Subjects ConnectomeDB_S00230 100307 F NA NA NA NA NA NA NA
4 HCP_Subjects ConnectomeDB_S00381 100408 M NA NA NA NA NA NA NA
5 HCP_Subjects ConnectomeDB_S01590 100610 M NA NA NA NA NA NA NA
6 HCP_Subjects ConnectomeDB_S00551 101006 F NA NA NA NA NA NA NAGet full list of experiments
To obtain a full list of experiments the experiments function will be used:
hcp_experiments <- hcp$experiments()
head(hcp_experiments)
project subject ID type label age
1 HCP_Subjects 100206 ConnectomeDB_E13304 xnat:mrSessionData 100206_3T 26
2 HCP_Subjects 100307 ConnectomeDB_E03657 xnat:mrSessionData 100307_3T 26
3 HCP_Subjects 100307 ConnectomeDB_E10373 xnat:megSessionData 100307_MEG NA
4 HCP_Subjects 100408 ConnectomeDB_E03658 xnat:mrSessionData 100408_3T 31
5 HCP_Subjects 100610 ConnectomeDB_E11186 xnat:mrSessionData 100610_3T 26
6 HCP_Subjects 100610 ConnectomeDB_E24170 xnat:mrSessionData 100610_7T 26Get 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:
ConnectomeDB_E13304_resources <- hcp$get_xnat_experiment_resources('ConnectomeDB_E13304')
head(ConnectomeDB_E13304_resources[c('Name','URI')])
Name URI
1 100206_3T_BIAS_BC.nii.gz /data/experiments/ConnectomeDB_E13304/scans/101/resources/274961/files/100206_3T_BIAS_BC.nii.gz
2 100206_3T_BIAS_32CH.nii.gz /data/experiments/ConnectomeDB_E13304/scans/102/resources/274962/files/100206_3T_BIAS_32CH.nii.gz
3 100206_3T_T1w_MPR1.nii.gz /data/experiments/ConnectomeDB_E13304/scans/103/resources/274963/files/100206_3T_T1w_MPR1.nii.gz
4 100206_3T_T2w_SPC1.nii.gz /data/experiments/ConnectomeDB_E13304/scans/106/resources/274964/files/100206_3T_T2w_SPC1.nii.gz
5 100206_3T_FieldMap_Magnitude.nii.gz /data/experiments/ConnectomeDB_E13304/scans/107/resources/274965/files/100206_3T_FieldMap_Magnitude.nii.gz
6 100206_3T_FieldMap_Phase.nii.gz /data/experiments/ConnectomeDB_E13304/scans/108/resources/274966/files/100206_3T_FieldMap_Phase.nii.gzQuery 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:
- subject_ID - subject ID identifier
- project - the project ID
- age - subject’s age
- experiment_ID - experiment ID identifier
- type - type of image scan
- TR - repetition time
- TE - echo time
- TI - inversion time
- flip - flip status
- voxel_res - overall image voxel resolution
- voxel_res_X - voxel X resolution
- voxel_res_Y - voxel Y resolution
- voxel_res_Z - voxel Z resolution
- orientation - image orientation
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.
hcp_500_age_26 <- query_scan_resources(hcp,age='26', project='HCP_500')
head(hcp_500_age_26[c("subject_ID","experiment_ID", "Project", "Age")])
subject_ID experiment_ID Project Age
1 ConnectomeDB_S00230 ConnectomeDB_E03657 HCP_500 26
2 ConnectomeDB_S00231 ConnectomeDB_E03664 HCP_500 26
3 ConnectomeDB_S00234 ConnectomeDB_E03684 HCP_500 26
4 ConnectomeDB_S00235 ConnectomeDB_E03690 HCP_500 26
5 ConnectomeDB_S00236 ConnectomeDB_E03694 HCP_500 26
6 ConnectomeDB_S00237 ConnectomeDB_E03988 HCP_500 26Getting 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(hcp,'ConnectomeDB_E03657')
scan_resources[1,"Name"]
[1] "100307_3T_BIAS_BC.nii.gz"
> scan_resources[1,"URI"]
[1] "/data/experiments/ConnectomeDB_E03657/scans/101/resources/69128/files/100307_3T_BIAS_BC.nii.gz"To download the resource file (100307_3T_BIAS_BC.nii.gz) we will do:
> download_xnat_file(hcp,"/data/experiments/ConnectomeDB_E03657/scans/101/resources/69128/files/100307_3T_BIAS_BC.nii.gz")
[1] "/var/folders/wb/l7jtkdy14f761vm4xr9zxjj80000gn/T//RtmpFfYbQ7/100307_3T_BIAS_BC.nii.gz"Getting Data: Download a directory of data
To download all the T2w type images from experiment ConnectomeDB_E03657 we will use the download_xnat_dir function.
download_xnat_dir(hcp, experiment_ID='ConnectomeDB_E03657',scan_type='T2w', verbose=TRUE)
Downloading: 28 MB [1] "/var/folders/wb/l7jtkdy14f761vm4xr9zxjj80000gn/T//RtmpFfYbQ7/ConnectomeDB_E03657.zip"
# Session Infodevtools::session_info()─ Session info ───────────────────────────────────────────────────────────────
setting value
version R version 4.0.2 (2020-06-22)
os macOS Catalina 10.15.7
system x86_64, darwin17.0
ui X11
language (EN)
collate en_US.UTF-8
ctype en_US.UTF-8
tz America/New_York
date 2021-02-18
─ Packages ───────────────────────────────────────────────────────────────────
package * version date lib
abind 1.4-5 2016-07-21 [2]
animation * 2.6 2018-12-11 [2]
ANTsR * 0.5.7.5 2021-02-16 [1]
ANTsRCore * 0.7.4.9 2021-02-16 [1]
assertthat 0.2.1 2019-03-21 [2]
base64enc 0.1-3 2015-07-28 [2]
bitops 1.0-6 2013-08-17 [2]
cachem 1.0.4 2021-02-13 [1]
callr 3.5.1 2020-10-13 [1]
cli 2.3.0 2021-01-31 [1]
codetools 0.2-18 2020-11-04 [1]
colorout * 1.2-2 2020-06-01 [2]
colorspace 2.0-0 2020-11-11 [1]
crayon 1.4.1 2021-02-08 [1]
DBI 1.1.1 2021-01-15 [1]
desc 1.2.0 2020-06-01 [2]
devtools * 2.3.2 2020-09-18 [1]
digest 0.6.27 2020-10-24 [1]
dplyr * 1.0.4 2021-02-02 [1]
ellipsis 0.3.1 2020-05-15 [2]
evaluate 0.14 2019-05-28 [2]
EveTemplate * 1.0.0 2020-06-01 [2]
extrantsr * 3.9.13.1 2020-09-03 [2]
farver 2.0.3 2020-01-16 [2]
fastmap 1.1.0 2021-01-25 [1]
fs 1.5.0 2020-07-31 [2]
fslr * 2.25.0 2021-02-16 [1]
generics 0.1.0 2020-10-31 [1]
ggplot2 * 3.3.3 2020-12-30 [1]
git2r 0.28.0 2021-01-11 [1]
glue 1.4.2 2020-08-27 [1]
gtable 0.3.0 2019-03-25 [2]
highr 0.8 2019-03-20 [2]
htmltools 0.5.1.1 2021-01-22 [1]
httr 1.4.2 2020-07-20 [2]
ITKR 0.5.3.3.0 2021-02-15 [1]
kirby21.base * 1.7.4 2020-10-01 [1]
kirby21.flair 1.7.0 2021-01-13 [1]
kirby21.fmri * 1.7.0 2018-08-13 [2]
kirby21.smri * 1.5 2021-02-16 [1]
kirby21.t1 * 1.7.3.2 2021-01-09 [1]
kirby21.t2 1.7.0 2021-02-16 [1]
knitr * 1.31 2021-01-27 [1]
lattice 0.20-41 2020-04-02 [2]
lifecycle 1.0.0 2021-02-15 [1]
magrittr 2.0.1 2020-11-17 [1]
matlabr * 1.6.0 2020-07-01 [2]
Matrix 1.3-2 2021-01-06 [1]
matrixStats * 0.58.0 2021-01-29 [1]
memoise 2.0.0 2021-01-26 [1]
mgcv 1.8-33 2020-08-27 [1]
munsell 0.5.0 2018-06-12 [2]
neurobase * 1.31.0 2020-10-07 [1]
neurohcp * 0.9.0 2021-02-18 [1]
nlme 3.1-152 2021-02-04 [1]
ore 1.6.3 2019-11-02 [2]
oro.nifti * 0.11.0 2020-09-04 [2]
pillar 1.4.7 2020-11-20 [1]
pkgbuild 1.2.0 2020-12-15 [1]
pkgconfig 2.0.3 2019-09-22 [2]
pkgload 1.1.0 2020-05-29 [2]
plyr * 1.8.6 2020-03-03 [2]
prettyunits 1.1.1 2020-01-24 [2]
processx 3.4.5 2020-11-30 [1]
ps 1.5.0 2020-12-05 [1]
purrr 0.3.4 2020-04-17 [2]
R.matlab 3.6.2 2018-09-27 [2]
R.methodsS3 * 1.8.1 2020-08-26 [1]
R.oo * 1.24.0 2020-08-26 [1]
R.utils * 2.10.1 2020-08-26 [1]
R6 2.5.0 2020-10-28 [1]
rcamino * 0.6.4 2020-06-01 [2]
RColorBrewer * 1.1-2 2014-12-07 [2]
Rcpp 1.0.6 2021-01-15 [1]
RcppEigen 0.3.3.9.1 2020-12-17 [1]
RCurl 1.98-1.2 2020-04-18 [2]
remotes 2.2.0 2020-07-21 [2]
reshape2 * 1.4.4 2020-04-09 [2]
rlang 0.4.10 2020-12-30 [1]
rmarkdown * 2.6 2020-12-14 [1]
RNifti * 1.3.0 2020-12-04 [1]
RNiftyReg 2.7.0 2020-10-08 [1]
rprojroot 2.0.2 2020-11-15 [1]
rstudioapi 0.13 2020-11-12 [1]
Rxnat * 1.0.14 2020-10-15 [1]
scales 1.1.1 2020-05-11 [2]
sessioninfo 1.1.1 2018-11-05 [2]
spm12r * 2.8.2 2021-01-11 [1]
stapler 0.7.2 2020-07-09 [2]
stringi 1.5.3 2020-09-09 [1]
stringr * 1.4.0 2019-02-10 [2]
testthat 3.0.2 2021-02-14 [1]
tibble 3.0.6 2021-01-29 [1]
tidyselect 1.1.0 2020-05-11 [2]
usethis * 2.0.1 2021-02-10 [1]
vctrs 0.3.6 2020-12-17 [1]
WhiteStripe 2.3.2 2019-10-01 [2]
withr 2.4.1 2021-01-26 [1]
xfun 0.21 2021-02-10 [1]
yaml * 2.2.1 2020-02-01 [2]
zoo * 1.8-8 2020-05-02 [2]
source
CRAN (R 4.0.0)
CRAN (R 4.0.0)
Github (ANTsX/ANTsR@4abee8d)
Github (ANTsX/ANTsRCore@ddf445b)
CRAN (R 4.0.0)
CRAN (R 4.0.0)
CRAN (R 4.0.0)
CRAN (R 4.0.2)
CRAN (R 4.0.2)
CRAN (R 4.0.2)
CRAN (R 4.0.2)
Github (jalvesaq/colorout@726d681)
CRAN (R 4.0.2)
CRAN (R 4.0.2)
CRAN (R 4.0.2)
Github (muschellij2/desc@b0c374f)
CRAN (R 4.0.2)
CRAN (R 4.0.2)
CRAN (R 4.0.2)
CRAN (R 4.0.0)
CRAN (R 4.0.0)
Github (muschellij2/EveTemplate@ed54115)
Github (muschellij2/extrantsr@00c75ad)
CRAN (R 4.0.0)
CRAN (R 4.0.2)
CRAN (R 4.0.2)
local
CRAN (R 4.0.2)
CRAN (R 4.0.2)
Github (ropensci/git2r@4e342ca)
CRAN (R 4.0.2)
CRAN (R 4.0.0)
CRAN (R 4.0.0)
CRAN (R 4.0.2)
CRAN (R 4.0.2)
Github (stnava/ITKR@ea0ac19)
local
Github (muschellij2/kirby21.flair@461077a)
CRAN (R 4.0.0)
Github (muschellij2/kirby21.smri@b15bcbc)
local
Github (muschellij2/kirby21.t2@8b5c8f4)
CRAN (R 4.0.2)
CRAN (R 4.0.2)
CRAN (R 4.0.2)
CRAN (R 4.0.2)
local
CRAN (R 4.0.2)
CRAN (R 4.0.2)
CRAN (R 4.0.2)
CRAN (R 4.0.2)
CRAN (R 4.0.0)
local
local
CRAN (R 4.0.2)
CRAN (R 4.0.0)
local
CRAN (R 4.0.2)
CRAN (R 4.0.2)
CRAN (R 4.0.0)
CRAN (R 4.0.0)
CRAN (R 4.0.0)
CRAN (R 4.0.0)
CRAN (R 4.0.2)
CRAN (R 4.0.2)
CRAN (R 4.0.0)
CRAN (R 4.0.0)
CRAN (R 4.0.2)
CRAN (R 4.0.2)
CRAN (R 4.0.2)
CRAN (R 4.0.2)
Github (muschellij2/rcamino@6f9ba9f)
CRAN (R 4.0.0)
CRAN (R 4.0.2)
CRAN (R 4.0.2)
CRAN (R 4.0.0)
CRAN (R 4.0.2)
CRAN (R 4.0.0)
CRAN (R 4.0.2)
CRAN (R 4.0.2)
CRAN (R 4.0.2)
Github (jonclayden/RNiftyReg@20c419f)
CRAN (R 4.0.2)
CRAN (R 4.0.2)
Github (adigherman/Rxnat@14a60c1)
CRAN (R 4.0.0)
CRAN (R 4.0.0)
local
Github (muschellij2/stapler@79e23d2)
CRAN (R 4.0.2)
CRAN (R 4.0.0)
CRAN (R 4.0.2)
CRAN (R 4.0.2)
CRAN (R 4.0.0)
CRAN (R 4.0.2)
CRAN (R 4.0.2)
CRAN (R 4.0.0)
CRAN (R 4.0.2)
CRAN (R 4.0.2)
CRAN (R 4.0.0)
CRAN (R 4.0.0)
[1] /Users/johnmuschelli/Library/R/4.0/library
[2] /Library/Frameworks/R.framework/Versions/4.0/Resources/library