-
Notifications
You must be signed in to change notification settings - Fork 6
DEPRECATED ANTs Multivariate Template Construction
This set of instructions in now deprecated in favour of https://github.com/CobraLab/twolevel_ants_dbm a streamlined automated tool which does all these steps for you.
See https://github.com/CoBrALab/documentation/wiki/Running-twolevel_ants_dbm-on-Niagara
This wiki page describes how to run the ANTs multivariate template construction tool (http://www.ncbi.nlm.nih.gov/pubmed/20851191) at the CIC. Please read through the entire wiki page before attempting to run the script. Then, go back and follow the individual steps.
The ANTs multivariate template construction tool can be used to create a group average of your images, using 1 or more modalities to drive registration. If available in your dataset, using multiple modalities can improve pairwise registrations by providing complementary contrasts. The tool outputs a final group average image for each input modality. You can also request that the tool output the transformations from each input image to the resulting group average image, to allow warping of each image to a common space.
The script, titled antsMultivariateTemplateConstruction2.sh, is available as part of the ANTs module and is configured to communicate with the CIC compute cluster. It works with nifti images (.nii.gz). If using this script in your work, you should reference http://www.ncbi.nlm.nih.gov/pubmed/20851191.
First, convert your .mnc files to .nii.gz nifti files, if needed. Use the mnc2nii tool that is part of the minc-toolkit module to convert from .mnc to .nii, then gzip your nifti files. The following loops should provide a good start:
>> module load minc-toolkit
>> for file in *mnc; do mnc2nii $file $(basename $file mnc)nii; done
>> for file in *nii; do gzip $file; done
>> module unload minc-toolkit
In the above, minc-toolkit is unloaded after use as it will conflict with the ANTs module loaded later on.
Create a folder and copy your images to the folder. You may use symbolic links. Copy the script to your folder as well, you will have to make a direct edit to it. In the example below, I have also renamed the script slightly to allude to changes being made.
>> mkdir ants_template_example
>> cd ants_template_example
>> cp -s /path/to/mydata/*nii.gz .
>> cp /opt/quarantine/ANTs/git/install/bin/antsMultivariateTemplateConstruction2.sh ./my-antsMultivariateTemplateConstruction2.sh
The script requires a .csv file containing the names of all your input files. Each column of the .csv file should contain the names of the files from a unique modality, and each row should contain the names of files pertaining to the same subject. For example, if I have multimodal data for 10 subjects with 10 T1 weighted images and 10 T2 weighted images, my .csv file should contain two columns (1 column for T1w files, 1 column for T2w files), and 10 rows (1 row for each subject). Row 1 contains the names for subject 1, row 2 contains the names for subject 2. If this is not correct, the script will confuse the files of one subject with another and you will get poor registrations. A two modality example is below:
100206_t1_crop.nii.gz,100206_t2_crop.nii.gz
100307_t1_crop.nii.gz,100307_t2_crop.nii.gz
100408_t1_crop.nii.gz,100408_t2_crop.nii.gz
100610_t1_crop.nii.gz,100610_t2_crop.nii.gz
101006_t1_crop.nii.gz,101006_t2_crop.nii.gz
101107_t1_crop.nii.gz,101107_t2_crop.nii.gz
101309_t1_crop.nii.gz,101309_t2_crop.nii.gz
101410_t1_crop.nii.gz,101410_t2_crop.nii.gz
101915_t1_crop.nii.gz,101915_t2_crop.nii.gz
102008_t1_crop.nii.gz,102008_t2_crop.nii.gz
Use the -h flag to view some information about the script, as well as all the available options.
>> ./my-antsMultivariateTemplateConstruction2.sh -h
Detailed below are options which you may be expected to specify in a standard setting. However, be sure to read the help on all options to determine if your application is any different.
-d: 3, in most cases, specifying your data is 3-dimensional. If you are working with a timeseries, you likely have 4-D data instead
-o: OutputPrefix; A prefix that is prepended to all output files.
-b: Specify 1 to save all intermediate files, including transforms from each subject to the group average. If you are interested in warping native space data to a common space, be sure to specify 1 here
-c: To take advantage of the CIC compute cluster, specify 1. Specifying 0 will run jobs serially (one at a time).
-k: Number of modalities used to construct the template (default 1): For example,
if one wanted to create a multimodal template consisting of T1,T2,and FA
components ("-k 3").
-n: N4BiasFieldCorrection of moving image: 0 == off, 1 == on (default 1).
-r: As described in the help, specify 1 if you do not have an initial template.
You are required to specify the number of CPUs required per job. Using your preferred editor, open up the script and go to line 488 where you will find the following text:
QSUBOPTS="" # EDIT THIS
Within the quotations, add in -pe smp followed by the number of CPUs per job. For example, to specify 6 CPUs per job, you would edit line 488 to read as follows:
QSUBOPTS="-pe smp 6" # EDIT THIS
The number of CPUs per job will be related to the file size and resolution of your data, where higher resolution data will require more CPUs. For whole brain 1mm isotropic data, 6 CPUs is likely a suitable choice. However, it is highly recommended that you perform a test run with ~10 subjects to ensure that you are choosing a suitable value. Create a separate test folder, copy ~10 subjects data along with the script, edit the script to specify X CPUs and run the script with your desired options. If this runs to completion, you can expect X CPUs to be an appropriate choice for your full dataset.
The script is run from the command line and requires the ANTs module to be loaded. The following is an example of running the script for 3 dimensional data, requiring rigid body registration, saving all intermediate files, using the CIC cluster, 2 modalities, an output prefix of ‘antsexample_’, and where the file inputs.csv contains the filenames of all subjects, organized as described above:
>> module load ANTs
>> ./my-antsMultivariateTemplateConstruction2.sh -d 3 -r 1 -b 1 -c 1 -k 2 -o antsexample_ inputs.csv
The script will then begin to run. You’ll need to leave the terminal open (screen may be useful here if you are familiar with it). Depending on the number of files you have, the number of modalities, the resolution of your data, and usage on the cluster, the script can take quite some time to run. This will vary per application, but runtime is likely on the order of a few days to a week, as opposed to an overnight run.
There are two main types of output files that may be of use to you - the group average and the transform files.
A group average will be created for each modality. If you used two modalities, you will have a group average for each. These files will be names as outputprefix_template0.nii.gz, outputprefix_template1.nii.gz, … etc. You can expect template 0 to correspond to the modality specified in the first column of your inputs.csv file. If you used multiple modalities, the group average for the modality in column 2 of your inputs.csv file will be named template 1, the group average for modality in column 3 will be template 2, and so on.
Transform files should exist for each input file, describing the transformation for that subject to the group average. The GenericAffine.mat file describes the affine transform, Warp.nii.gz describes the non linear transform, and InverseWarp.nii.gz describes the inverse of the non linear transform. For a given input file with name filename and prefix outputprefix, try the following to identify the transform files:
>> ls outputprefix_filename*GenericAffine.mat outputprefix_filename*Warp.nii.gz
Contact Raihaan for questions (patelraihaan@gmail.com)