Skip to content

CIVET Processing

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

Preamble

Surface-based metrics (surface-based volume, cortical thickness, and surface area) are calculated with CIVET through the CBRAIN platform. You may also run CIVET via command line on the Douglas Cerebral Imaging Centre or Compute Canada compute nodes (see instructions here from the Cobra Lab). The current CIVET version is 2.1.1. The major changes from 2.1.1 to 2.1.0 is as described here:

N3 intensity normalization: Normalize the T1w input scan prior to N3 corrections such that the N3 corrected image is invariant to scaling of the image. For example, N3(2T1w) = 2N3(T1w). This appears trivial, but this was not the case with the algorithm implemented in N3 (working in log space). Note that intensity normalization prior to N3 will change the cortical thickness results for CIVET compared to the previous version 2.1.0.

This means that data processed with older versions of CIVET should NOT be combined/compared with data processed with newer versions of CIVET

Via CBRAIN/NeuroHub

Here are the steps for calculating surface-based metrics with CIVET through CBRAIN.

Register for a CBRAIN or NeuroHub account

Copy files to CBRAIN Data Provider

In order to run CIVET on the CBRAIN platform, you will need to copy over your files. This can be done one-by-one on the CBRAIN platform or all at once through Secure File Transfer Protocol (SFTP).

To use SFTP, you can use FileZilla or run the following code in terminal:

sftp -o port=7500 {username}@{provider}.cbrain.mcgill.ca

Replace {username} with your CBRAIN username and {provider} with one of the two data providers, ace-cbrain-1 (for sftp-1) or ace-cbrain-2 (for sftp-2). You will then be prompted for your CBRAIN password (see CBRAIN Uploading). Once you have accessed the data provider, copy your files (replacing /path/to/mncs/ below with the appropriate path):

put /path/to/mncs/*

Which files to use?

You can either use the raw minc files ({prefix}_{subjectID}_T1.mnc) or BPIPE outputs. If you use BPIPE outputs, you should use the *cutneckapplyautocrop.mnc files and rename these files to the CIVET convention first. For example, if your files are named {prefix}_{subjectID}_T1.convert.n4correct.anlm_denoise.cutneckapplyautocrop.mnc, you can batch rename them with:

rename 's/.convert.n4correct.anlm_denoise.cutneckapplyautocrop.mnc/.mnc/' *.mnc

Or on Niagara:

rename .convert.n4correct.anlm_denoise.cutneckapplyautocrop.mnc .mnc *.mnc

Just be sure to indicate these are preprocessed in whatever directory they are stored so they are not mixed up with the unprocessed files.

Create Project

To begin using CIVET in CBRAIN, you should create a Project where all your files will be located. Login to CBRAIN from a web browser, select Projects in the upper row and click on Create Project. Give a name and description to your project. You should now see it under the Projects tab.

Copy/Register files

The SFTP-1 and SFTP-2 data providers are only for transferring files and not for storing data long term. You must register and transfer your files to one of the official storage data providers (e.g., MainStore). To do this, click on Resources → Data Providers in the upper row and click on Browse next to the Data Provider that you transferred your files to (SFTP-1 or SFTP-2). Select the files/folder containing the data, click on Register Files and select Move to MainStore and designate it to a project. Once this is complete, the files will be located in your project folder and removed from the SFTP data provider. If you copied over an entire folder, you should extract that folder by clicking on it and selecting Extract Files from Collection at the bottom of the page, and then delete the folder once the files have been extracted.

Select files & launch CIVET

To run CIVET, you will select the file(s) you want to preprocess (i.e., prefix_subject_T1.mnc), click Launch, and select CIVET (version 2.1.1 and whichever server is fastest, but keep the same server for a single project) and click Launch Civet. You will see a new page with many options for CIVET preprocessing. See the CIVET CBRAIN documentation for instructions on selecting options. Don't forget to save your parameters file so you can run it again if needed!

Quality control

Once processing is complete, you should perform a second quality control on the CIVET outputs to ensure that there were no errors or issues with preprocessing. See the CIVET documentation.

Backup files

Copy CIVET output files from MainStore to SFTP-1 on CBRAIN. Then login to the CIC and cd to the directory where you'd like to save the files. Use sftp -o port=7500 {username}@{provider}.cbrain.mcgill.ca as above but instead of put use get -r * to copy the outputs to the CIC.

Via Digital Research Alliance of Canada (formerly Compute Canada)

You can also run CIVET via the command line (see CobraLab documentation). Here are the basic steps:

Run BPIPE

See BPIPE Processing

Load modules

module load cobralab

Populate input and output directories

Make and/or change directory to location where you want to run CIVET:

mkdir $SCRATCH/ABC/civet
cd $SCRATCH/ABC/civet

Create input and output folders:

mkdir -p $SCRATCH/ABC/civet/{input,output}

Copy bpipe outputs {prefix}_{subject}_T1.n4correct.cutneckapplyautocrop.mnc files to the input folder and rename them to CIVET standard ({prefix}_{subject}_t1.mnc):

find $SCRATCH/ABC/bpipe/run* -name *"n4correct.cutneckapplyautocrop.mnc" > files.txt
while read line; do out=${line##*/}; out=${out/.convert.n4correct.cutneckapplyautocrop/}; cp ${line} input/${out}; done<"files.txt"

Do the same for *.convert.n4correct.cutneckapplyautocrop.beastmask.mnc except rename to {prefix}_{subject}_mask.mnc:

find $SCRATCH/ABC/bpipe/run* -name *".convert.n4correct.cutneckapplyautocrop.beastmask.mnc" > maskfiles.txt
while read line; do out=${line##*/}; out=${out/.convert.n4correct.cutneckapplyautocrop.beastmask/}; cp ${line} input/${out}; done<"maskfiles.txt"

You may need to further rename your files to civet convention, and use lowercase "t1" suffixes unlike on CBRAIN (modify as needed):

rename _T1 _t1 *.mnc

Set options and run

Open a new file called runcivet.sh:

nano $SCRATCH/${study}/civet/runcivet.sh

Copy and paste the below script and change #OPTIONS TO MODIFY based on CIVET options, if desired:

#!/bin/bash
#LOAD MODULES
module load cobralab

#OPTIONS TO MODIFY
atlas="DKT"
fwhm="20:10:0"

#CREATE JOBLIST
for file in input/*_t1.mnc; do
  echo CIVET_Processing_Pipeline \
    -sourcedir input \
    -targetdir output \
    -granular \
    -template 0.50 \
    -surface-atlas ${atlas} \
    -correct-pve \
    -interp sinc \
    -N3-distance 0 \
    -lsq12 \
    -mask-hippocampus \
    -thickness tlaplace ${fwhm} \
    -resample-surfaces \
    -mean-curvature \
    -area-fwhm ${fwhm} \
    -volume-fwhm ${fwhm} \
    -run $(basename $file _t1.mnc) >> joblist.txt
done

#RUN
qbatch -N CIVET -c 1 -w 12:00:00 joblist.txt

Save (Ctrl+o then Enter), close (Ctrl+x), and make the file executable (chmod +x $SCRATCH/ABC/civet/runcivet.sh). Then run it (./$SCRATCH/ABC/civet/runcivet.sh)

Quality control

It is possible that some subjects didn't run (e.g., due to node failure or other reasons unrelated to CIVET). Check with the following code:

for infile in `ls input | grep _t1.mnc`
  do
    subj=${infile/_t1.mnc/}
    if [ ! -d output/${subj} ]; then
      echo ${infile} >> missingsubjs.txt
    fi
done

If there are missing subjects in the missingsubjs.txt file, modify the runcivet.sh script slightly as follows (it may be the case that you can just rerun the original joblist and civet will not rerun already completed subjects, but I haven't tested this on Niagara):

#!/bin/bash
#LOAD MODULES
module load cobralab

#OPTIONS TO MODIFY
atlas="DKT"
fwhm="20:10:0"

#CREATE JOBLIST
while read line; do
  echo CIVET_Processing_Pipeline \
    -sourcedir input \
    -targetdir output \
    -granular \
    -template 0.50 \
    -surface-atlas ${atlas} \
    -correct-pve \
    -interp sinc \
    -N3-distance 0 \
    -lsq12 \
    -mask-hippocampus \
    -thickness tlaplace ${fwhm} \
    -resample-surfaces \
    -mean-curvature \
    -area-fwhm ${fwhm} \
    -volume-fwhm ${fwhm} \
    -run ${line} >> joblist2.txt
done < "$1"

#RUN
qbatch -N CIVET -c 1 -w 12:00:00 joblist2.txt

And run it with the missingfiles.txt list you created (I renamed the runcivet script to runcivet_failed):

./runcivet_failed.sh missingfiles.txt

Repeat until all subjects have run.

Once you have no missing subjects, check if any subjects failed. cd to your civet directory and check for failures with the following command:

grep -i fail logs/* | grep -vi "setting locale failed"

If you see any output, it means there were failures. Take note of these in your QC document. If the reason for failure is related to extracting surfaces (e.g., extract white surface left set to failed), then there is not likely much you can do. Simply re-running failed subjects without changing any parameters would not lead to much if any improvement in the results. There is a way to fix issues of nonconvergence (e.g., one hemisphere entirely black), but I am not sure how (it may have to do with fixing the mask).

Copy the CIVET QC outputs to a separate folder to perform QC:

mkdir QC
cp -vu output/*/verify/*.png QC/

Exit Niagara (exit) and from your own computer's terminal, download the QC directory:

scp -r {username}@niagara.computecanada.ca:/path/to/civet/QC /path/to/local/directory/

Backup your data to the CIC

There is no need to backup the input files, but you should backup a list of those files and create a README.txt saying where they came from (e.g., bpipe cutneckapplyautocrop.mnc and beast masks):

ls input > inputfiles.txt
echo "Input files are BPIPE processed cutneckapplyautocrop.mnc files & beast masks, which are backed up in {path}" > README.txt

Backup the output files to the CIC or local storage using rsync or scp.

Clone this wiki locally