Skip to content

BPIPE Processing

Jump to bottom
Katie Lavigne edited this page Jun 23, 2022 · 8 revisions

Table of Contents

  1. Preamble
  2. Organizing your files
  3. Setting up BPIPE
  4. (Optional) Modifying the standard pipeline
  5. Using a batch script
  6. Calculating total brain & intracranial volumes
  7. Quality control
  8. T2-weighted processing

Preamble

The minc-bpipe-library consists of a set of tools used to prepare and clean up MRI images for analysis. These tools include, but are not limited to: minc conversion (convert), bias field correction (n4correct), filtering (anlm_denoise, important for ultra high-field MRI datasets), cropping (cutneck), and brain extraction (beast). These instructions describe how to run bpipe on the high performance cluster Niagara.

In order to use Niagara you must:

  1. Apply for a CCDB account
  2. Opt-in to Niagara
  3. Follow the CobraLab instructions to (i) login to Niagara and (ii) set up the CobraLab software modules

Organizing your files

To simplify your code, all files of the same scan type (e.g., T1-weighted, T2-weighted) should be in a single directory. All files should also be named in the following convention: prefix_subjectID_scantype.mnc. For example, if your study is called "ABC", your subject ID is 101, and your scan type is T1-weighted, the filename would be ABC_101_T1.mnc.

In this example, we have subdirectories t1w for T1-weighted images and t2w for T2-weighted images.

-t1w
--ABC_101_T1.mnc
--ABC_102_T1.mnc
--ABC_103_T1.mnc
-t2w
--ABC_101_T2.mnc
--ABC_102_T2.mnc
--ABC_103_T2.mnc

This structure can be easily created with the mkdir command: mkdir -p ${SCRATCH}/{t1w,t2w}. Follow the CobraLab instructions for moving files to and from Niagara.

Setting up BPIPE

Clone the bpipe library:

git clone https://github.com/CobraLab/minc-bpipe-library.git $SCRATCH/minc-bpipe-library

Delete the config file:

rm $SCRATCH/minc-bpipe-library/bpipe.config

(Optional) Modifying the standard pipeline

  • Create a backup of the standard pipeline:
cp $SCRATCH/minc-bpipe-library/minc-library.bpipe $SCRATCH/minc-bpipe-library/minc-library.bpipe_orig
  • Modify the pipeline:
nano $SCRATCH/minc-bpipe-library/minc-library.bpipe
  • Scroll to the end of the file that has opened in the terminal. Modify the last section to include/exclude preprocessing steps you need. Then save (Ctrl+o then Enter) and close (Ctrl+x) the file. See all BPIPE processing steps here.

Using a batch script

First create an output directory for the files that will be created from bpipe and change your working directory to the newly created one:

mkdir -p $SCRATCH/bpipe
cd $SCRATCH/bpipe

Generate a job list which will tell Niagara which commands to run (modify $SCRATCH/t1w/*.mnc if you have a different directory structure):

$SCRATCH/minc-bpipe-library/bpipe-batch.sh $SCRATCH/minc-bpipe-library/pipeline.bpipe $SCRATCH/t1w/*.mnc > $SCRATCH/bpipe/bpipe_joblist
  • Note: If you are using NIFTI images (.nii) replace *.mnc above with *.nii and make sure to use the convert option in minc-library.bpipe (it is part of the default pipeline).

Load required modules:

module load cobralab

Run pipeline with qbatch:

qbatch -N bpipe --chunksize 1 --walltime=8:00:00 ${SCRATCH}/bpipe/bpipe_joblist

You can check up on your job with squeue -u $USER or simply sq. Once preprocessing is complete (may take a few days depending on number of files and priority), your files will be in the bpipe directory under several different run-* folders.

Calculating total brain and intracranial volumes

Load required modules:

module load minc-toolkit minc-toolkit-extras

Calculate total brain volume (in mm3s, excluding ventricles):

collect_volumes.sh $SCRATCH/bpipe/run-*/*brainvolume.mnc > ${SCRATCH}/bpipe/TBV_brainvolumes.csv

Calculate total mask volume (in mm3s, including inner non-brain tissue, such as ventricles):

collect_volumes.sh $SCRATCH/bpipe/run-*/*cutneckapplyautocrop.beastmask.mnc > ${SCRATCH}/bpipe/TBV_maskvolumes.csv

For intracanial volume (ICV), we produce values relative to the MNI template (<1 = smaller than MNI, >1 = larger than MNI). Absolute values in mm3s could theoretically be calculated by multiplying these values by the MNI skull volume but this is not currently available. Calculating relative ICV uses xfm2det:

xfm2det $SCRATCH/bpipe/run-*/*ICV.xfm > ${SCRATCH}/bpipe/ICV_relative_to_MNI.txt

Quality control

Within each bpipe/run-* directory, you will have several files, a QC directory and a lsq6 directory. First, you want to make sure that all subjects completed all preprocessing steps. Here is an example script, that will compare the output files with the input files and list the missing subjects and found output files in the terminal:

#!/bin/bash
# CHECK FOR BPIPE MISSING FILES AND OUTPUT TEXT

t1dir="$SCRATCH/t1w" # modify if different directory structure
bpipedir="$SCRATCH/bpipe" # modify if different directory structure

for file in `ls ${t1dir}`
do
  if [ ! -f ${bpipedir}/run-*/$(basename ${file}).convert.n4correct.cutneckapplyautocrop.beastmask.mnc ]; then
    echo ${file} incomplete...
    nfiles=$(find ${bpipedir} -name "${file}"* | wc -l)
    if [ ${nfiles} -eq 0 ]; then
      echo ...failed at first step.
    else
      echo ...files found:
      find ${bpipe} -name "${file}"*
    fi
  fi
done

Create this file with nano $SCRATCH/checkbpipe.sh and copy/paste the above, save with Ctrl+o, Enter, and exit with Ctrl+x. Then make the file executable with chmod +x $SCRATCH/checkbpipe.sh and run it with ./checkbpipe.sh, making sure your present working directory (pwd) is the same as the one where this file is located.

If one or more subjects failed preprocessing, you should examine the raw data as well as any output files to try to figure out the source of the issue. You can check the raw scan using Display and consult any QC notes to see if the scan is poor quality. If some bpipe steps worked, you can examine those output files (also with Display) to see where the problem occurred. You can also copy the QC folder to your local machine (or view them in Niagara using xdg-open):

To create a QC folder and download the .jpg outputs:

mkdir $SCRATCH/bpipe/QC
cp $SCRATCH/bpipe/run-*/QC/*.jpg $SCRATCH/bpipe/QC

Then exit out of Niagara and download to your local machine (replace with appropriate username and paths):

scp -r username@niagara.computecanada.ca:/path/to/QC /path/on/local/machine

Look through these QC images and focus on the red/pink mask to make sure (1) that it covers the entire brain and (2) that it doesn't include a lot of skull or other non-brain areas. Rate either 0 (fail), 1 (questionable), and 2 (pass).

T2-weighted processing

First run the T1-weighted images through bpipe as above. Then copy relevant files into their directories as described below.

Create the directories:

mkdir -p ${SCRATCH}/{t1w-n4correct-cutneck,t2-corrected,beastmask,t2w}

Copy T1-weighted cutneck files:

find $SCRATCH/bpipe -name *cutneckapplyautocrop.mnc -exec cp {} ${SCRATCH}/t1w-n4correct-cutneck/ \;

Copy T1-weighted mask files:

find $SCRATCH/bpipe -name *cutneckapplyautocrop.beastmask.mnc -exec cp {} ${SCRATCH}/beastmask/ \;

Raw T2-weighted files should already be in the t2w folder as described above. T2-corrected files will be created in the next step so no need to move any files to that directory.

Create (nano t2bpipe.sh), make executable (chmod +x t2bpipe.sh) and run (./t2bpipe.sh) intrasubject-N4_extract:

#!/bin/bash
# Run intrasubject-N4_extract on T2-weighted images.

T2in="$SCRATCH/t2w"
T1n4="$SCRATCH/t1w-n4correct-cutneck"
T1beast="$SCRATCH/beastmask"
T2out="$SCRATCH/t2-corrected"

for file in ${T2in}/*.mnc; do
  fname=${file##*/}
  sub=${fname::-7}
  echo intrasubject-N4_extract.sh ${file} ${T1n4}/${sub}* ${T1beast}/${sub}* ${T2out}/${sub}_T2_corrected.mnc >> T2_joblist.txt
done

#Remove lines with missing data
sed '/*/d' T2_joblist.txt > tmp.txt

#Output missing data
diff T2_joblist.txt tmp.txt > missingfiles.txt

# Clean up
mv tmp.txt T2_joblist.txt

# Run
module load cobralab

qbatch -N t2_bpipe --chunksize 20 --walltime=0:20:00 ${SCRATCH}/bpipe/T2_joblist.txt

This script skips subjects missing T1w files and puts the relevant IDs into the "missingfiles.txt" file. Look at this file afterwards (or while the jobs are running) and try to determine why those files are missing.

Clone this wiki locally