XTOLM Use Case - Compute Brain Volumes from XNAT MR Session and Export Data

In this example, we will use XTOLM to compute whole brain volume using the Brain Extraction Tool for all MPRAGE scans in an MRI project in XNAT, and save the resulting statistics in a spreadsheet.

Prerequisites

FSL and dcm2nii on your path
We'll use data from surfmask_smpl project on XNAT central so you'll need an XNAT Central account.

Step by Step Instructions

1. Write a bash script that computes human brain volume from a T1-weighted MR image in DICOM format (assuming FSL v4+ is on the path).

brain_volume.sh

BASH

#!/bin/bash
in=$1 #input DICOM directory
dcm2nii $in
cp $in/[0-9]*.nii head.nii
if [ ! -f "head.nii" ]; then exit -1; fi
bet head brain -m
vol=(`fslstats brain_mask -V`); vol=${vol[1]}
#report the volume in mm3 to console.
echo $vol

2. Create a CSV spreadsheet listing all scans that you want to process.

In many cases, you'll have such spreadsheet; if not, you can start with the one created using the one generated by XNAT:

Now, modify the spreadsheet so that column names don't contain spaces, empty and irrelevant cells are removed, and set "Scans" to "SPGR", the scan type that we want to process for each session. If any fields have trailing zeroes, you'll need to modify the csv outside of Excel to add them.

3. Adapt the brain_volume.sh to process all sessions from your CSV file.

brain_volume.xt

BASH

#!/bin/bash
#this line will convert test.csv to a bash source test.params that assigns corresponding arrays.
rcsv test.csv `pwd`/test.params; source `pwd`/test.params; rm test.params
#as a result, the following arrays are assigned:
#MR_ID=("001_obscured" "002_obscured" ...
#Subject=("001" "002" "003" ...
#Scans=("SPGR" "SPGR" "SPGR" ...
#now, iterate over all MR sessions. 
set -x
for ((i=0; i<${#MR_ID[*]}; i++)); do
    #this will create directory named ${MR_ID[i]} and cd to it.
    set_context ${Subject[i]} ${MR_ID[i]}
    #load specified scan from XNAT.
    load_type "${Scans[i]}"
    #find the scan that was created by load_type.
    set -x
    in=`ls -d study*`
    #compute brain volume, similarly to brain_volume.sh
    dcm2nii $in
    #select the unmodified NIFTI volume to process.
    cp $in/[0-9]*[0-9].nii head.nii
    if [ ! -f "head.nii" ]; then exit -1; fi
    bet head brain -m
    vol=(`fslstats brain_mask -V`); vol=${vol[1]}
    #now we use special command to save a variable with this offline session.
    save_vars vol
    break
done
#return to the starting directory.
set_context null 
#this will go through all sessions and generate a spreadsheet summarizing variables saved with "save_vars" command.
summary mpr_vol

4. Test the batch processing.

We will run the developed script on a single session to see if it works. For that, uncomment break statement on line 26. Now we are ready to run the script:

running brain_volume.xt

BASH

xtolm -sr https://central.xnat.org -u your_xnat_central_user -pr surfmask_smpl -o brain_volume.xt
cat mpr_vol.csv

After making sure that mpr_vol.csv produces correct output, comment the break statement on line 26 and rerun the brain_volume.xt. Now we'll have the BET calculations saved in mpr_vol.csv file ready for analysis (note that Excel removed trailing zeroes from the subject again).