Yaxil Demo

This page puts the rest of the guide together on a real task: pulling an imaging session off XNAT and turning it into something you can analyze.

What XNAT Is

XNAT is the imaging data platform that stores BU's CNC neuroimaging data. Scans are uploaded to it directly from the scanner, so it — not a hard drive — is where your raw data actually lives. You can browse a session in a web interface to check for artifacts before committing to a pipeline.

BU's instance lives at xnat2.bu.edu. Sign in with your BU credentials — the same username and Kerberos password you use for SCC OnDemand.

What Yaxil Is

Yaxil is a command-line client for XNAT. Its main command, ArcGet.py, downloads a session — and, given a configuration file, converts it straight to BIDS on the way down.

Loading Yaxil

[scc4]$ module avail yaxil

--------------------------- /share/module.8/imaging ----------------------------
   yaxil/0.4.2             yaxil/0.8.0    yaxil/0.9.12    yaxil/0.16.0 (D)
   yaxil/0.6.5_dwi_beta    yaxil/0.9.0    yaxil/0.14.2

  Where:
   D:  Default Module

Yaxil is a Python program, so load a python3 module alongside it:

[scc4]$ module load python3/3.13.8
[scc4]$ module load yaxil/0.16.0

Check that it worked:

[scc4]$ ArcGet.py --version
0.16.0

Signing In Once with `xnat_auth`

Yaxil needs your XNAT credentials every time it talks to the server. Rather than typing them on each download, xnat_auth saves them once under a short alias that you pick:

[scc4]$ xnat_auth --alias xnat2 --url https://xnat2.bu.edu --username your_username
XNAT password:
INFO:__main__:credentials are valid
INFO:__main__:saved /usr4/tutorial/your_username/.xnat_auth

Option	What to put
`--alias`	A short name for this server. This page uses `xnat2`.
`--url`	`https://xnat2.bu.edu` for BU's instance
`--username`	Your BU username

There is also a --password option. Leave it off. Omitting it makes the tool prompt you instead, so your password never ends up in your shell history.

You only have to do this once. From here on, every yaxil command takes -a xnat2 and signs itself in.

~/.xnat_auth holds your credentials. It lives in your home directory, which only you can read. Treat it the way you would any other stored password.

Downloading a Session

Move to your project space. Imaging data does not belong in your home directory — see The Linux File System.

[scc4]$ cd /projectnb/your_project/your_username

Make a directory for the download to land in.

[scc4]$ mkdir my_data

Ask for the session by its label. This is the command that does the work; the rest was housekeeping.

[scc4]$ ArcGet.py -a xnat2 -l 260203_xnat_demo_data -o my_data/
INFO:/share/pkg.8/yaxil/0.16.0/install/bin/ArcGet.py:downloading scans 1,2,3,4,5,6,7,8,9,10,11,12,14,15,17,18,99
reading response data: done.

Option	Means
`-a`	the alias you set up with `xnat_auth`
`-l`	the session label to download
`-o`	where to write the output

What you get is the raw DICOMs, exactly as they came off the scanner:

[scc4]$ tree my_data/ --filelimit 10
my_data/
└── 260203_xnat_demo_data
    └── RAW [984 entries exceeds filelimit, not opening dir]

2 directories, 0 files

That is fine for archiving, but no pipeline wants it in this shape.

Describing Your Scans

Yaxil can convert to BIDS on the way down, which saves a separate dcm2niix step. To do that it has to be told which scan number is which — that scan 8 is the T1w, that scan 12 is the STILL task, and so on. That mapping lives in a YAML configuration file.

Yaxil ships examples, and the module points an environment variable at them:

[scc4]$ echo $SCC_YAXIL_EXAMPLES
/share/pkg.8/yaxil/0.16.0/install/share/examples

[scc4]$ ls $SCC_YAXIL_EXAMPLES
README.md  example_config.yaml  workshop_config.yaml

workshop_config.yaml describes the demo session used on this page. Copy it into your own directory:

[scc4]$ cp $SCC_YAXIL_EXAMPLES/workshop_config.yaml bids-config.yaml

Open it in an editor and you will see this:

sub: xnatdemo # by default, the XNAT Subject label will be used
ses: "01" # by default, the XNAT MR Session label will be used
anat:
    T1w:
        - scan: 8
          run: 1
func:
    bold:
        - scan: 12
          task: STILL
          run: 1
          id: still1
        - scan: 15
          run: 1
          task: MOVING
          id: moving1
        - scan: 18
          task: TOPHALFOFF
          run: 1
          id: tophalfoff1
    sbref:
        - scan: 11
          run: 1
          task: STILL
        - scan: 14
          run: 1
          task: MOVING
        - scan: 17
          run: 1
          task: TOPHALFOFF

Each entry names a scan number from the session on XNAT and the BIDS labels to give it. sub and ses set the subject and session names; leave them out and the XNAT labels are used instead.

For your own study you will write your own version of this file. Browse the session in xnat2.bu.edu to see which scan numbers correspond to which acquisitions. example_config.yaml in the same directory is the generic version from the Yaxil documentation.

Downloading Straight to BIDS

Same command as before, plus -f bids to ask for BIDS output and -c to point at your configuration file:

[scc4]$ mkdir mydata_bids
[scc4]$ ArcGet.py -a xnat2 -l 260203_xnat_demo_data -o mydata_bids/ -f bids -c bids-config.yaml

Checking the Result

[scc4]$ tree -L 5 mydata_bids/
mydata_bids/
├── dataset_description.json
├── sourcedata
│   └── sub-xnatdemo
│       └── ses-01
│           ├── anat
│           │   └── sub-xnatdemo_ses-01_run-1_T1w.dicom
│           └── func
│               ├── sub-xnatdemo_ses-01_task-MOVING_run-1_bold.dicom
│               ├── sub-xnatdemo_ses-01_task-MOVING_run-1_sbref.dicom
│               ├── sub-xnatdemo_ses-01_task-STILL_run-1_bold.dicom
│               ├── sub-xnatdemo_ses-01_task-STILL_run-1_sbref.dicom
│               ├── sub-xnatdemo_ses-01_task-TOPHALFOFF_run-1_bold.dicom
│               └── sub-xnatdemo_ses-01_task-TOPHALFOFF_run-1_sbref.dicom
└── sub-xnatdemo
    └── ses-01
        ├── anat
        │   ├── sub-xnatdemo_ses-01_run-1_T1w.json
        │   └── sub-xnatdemo_ses-01_run-1_T1w.nii.gz
        └── func
            ├── sub-xnatdemo_ses-01_task-MOVING_run-1_bold.json
            ├── sub-xnatdemo_ses-01_task-MOVING_run-1_bold.nii.gz
            ├── sub-xnatdemo_ses-01_task-MOVING_run-1_sbref.json
            ├── sub-xnatdemo_ses-01_task-MOVING_run-1_sbref.nii.gz
            ├── sub-xnatdemo_ses-01_task-STILL_run-1_bold.json
            ├── sub-xnatdemo_ses-01_task-STILL_run-1_bold.nii.gz
            ├── sub-xnatdemo_ses-01_task-STILL_run-1_sbref.json
            ├── sub-xnatdemo_ses-01_task-STILL_run-1_sbref.nii.gz
            ├── sub-xnatdemo_ses-01_task-TOPHALFOFF_run-1_bold.json
            ├── sub-xnatdemo_ses-01_task-TOPHALFOFF_run-1_bold.nii.gz
            ├── sub-xnatdemo_ses-01_task-TOPHALFOFF_run-1_sbref.json
            └── sub-xnatdemo_ses-01_task-TOPHALFOFF_run-1_sbref.nii.gz

16 directories, 15 files

That is a BIDS dataset. The .nii.gz files are the converted images, each with a .json sidecar of scan parameters, and sourcedata/ keeps the original DICOMs alongside them.

What Comes Next

A BIDS dataset is the starting point for every pipeline RCS documents:

MRIQC — screen the data for quality problems.
fMRIPrep — preprocess it.
FreeSurfer — cortical surface reconstruction and anatomical segmentation.
CONN — functional connectivity analysis.