The basic principles in template construction #520

younghoo · 2017-11-10T06:14:45Z

Hi, what is the general logic of ANTs template construction process? I used to think that template construction is a process of "averaging-registration-iteration". For example, there are three brain images (A, B, C) and I could make a template out of the three images. So I average A/B/C to get a mean image, and then register A/B/C to mean image to get A1/B1/C1. A1/B1/C1 are again averaged to update the mean image. This process is iterated several times until the mean image converges.

But I think ANTs' process is different because I guess there are pairwise registration (i.e. A->B, B->C) from naming conventions. It is difficult for me to understand the underlying mathematics but I try my best to have a simplified and coarse understanding of this process.

Many thanks!

ntustison · 2017-11-10T14:59:45Z

There are no A <--> B, B <--> C registrations. Your initial conceptualization is correct except you left out the shape update step. So it goes

Initialization: Average all images to create an initial template

Register all images to the template.
Average all warped images to create a new template.
Average all the transforms from 1 to create a single transform.
Apply the transform from 3 the template to warp the template towards the true mean shape.
Use a sharpening filter on the adjusted template to enhance edges.
Go back to 1.

aghayoor · 2018-01-29T23:50:18Z

@ntustison : Nick, based on my understanding from your explanation of the template building process, it seems that all the input images should be approximately aligned to create a plausible initial average image.

If there is any translation/rotation offsets between the input images, should we rigidly co-register all the input images before we start the template building process?

ntustison · 2018-01-29T23:58:00Z

Look at the -r option in the template building scripts.

aghayoor · 2018-01-30T00:16:56Z

Thank you.

wangken1994 · 2019-07-03T00:42:55Z

@ntustison
Can I build DT image template with buildtemplateparallel.sh?

ntustison · 2019-07-03T04:38:24Z

Neither buildtemplateparallel.sh or any of the other template-building scripts handle tensor images. However, DT-derived templates (e.g., FA) can be created using those tools.

wangken1994 · 2019-07-03T09:08:00Z

Thanks for your reply! @ntustison
I also tried the procedures of template construction you listed above. But I met some errors in

Apply the transform from 3 the template to warp the template towards the true mean shape.

My data are FA images derived from DTI, like 1-fa.nii.gz, 2-fa.nii.gz and 3-fa.nii.gz. My codes are shown below:
Step1: Create an initial template
Step1-1: Rigid alignment

for((i=2;i<4;i++)) \ 
do antsRegistrationSyNQuick.sh \
-d 3 \
-f 1-fa.nii.gz \
-m ${i}-fa.nii.gz \
-o ${i}to1 \
-t r\ 
done

Step1-2: Apply Transforms

for((i=2;i<4;i++)) \ 
do antsApplyTransforms \
-d 3 \
-e 0 \
-i ${i}-fa.nii.gz \
-r 1-fa.nii.gz \
-o ${i}to1-fa.nii.gz \
-t ${i}to10GenericAffine.mat \
done

Step1-3: Create initial template

AverageImages 3 InitTemp-fa.nii.gz 0 1-fa.nii.gz 2to1-fa.nii.gz 3to1-fa.nii.gz

Step2: Procedures 1 to 4 of your suggestion

Register all images to the template.

Average all warped images to create a new template.

Average all the transforms from 1 to create a single transform.

Apply the transform from 3 the template to warp the template towards the true mean shape.

Step2-1: Register all images to the initial template

for((i=1;i<4;i++)) \
do antsRegistrationSyNQuick.sh \
-d 3 \
-f InitTemp-fa.nii.gz \
-m ${i}-fa.nii.gz \
-o ${i}toInit-fa \
-t a \ 
done

for((i=1;i<4;i++)) \
do antsApplyTransforms \
-d 3 \
-e 0 \
-i ${i}-fa.nii.gz \
-r InitTemp-fa.nii.gz \
-o ${i}toInit-fa.nii.gz \
-t ${i}toInit-fa0GenericAffine.mat \
done

Step2-2: Average all warped images to create a new template.

AverageImages 3 MeanToInit-fa.nii.gz 0 *toInit-fa.nii.gz

Step2-3: Average all the transforms from 1 to create a single transform.

MATLAB:
T1=load('...\1toInit-fa0GenericAffine.mat');
T2=load('...\2toInit-fa0GenericAffine.mat');
T3=load('...\3toInit-fa0GenericAffine.mat');
AffineTransform_double_3_3=(T1.AffineTransform_double_3_3+T2.AffineTransform_double_3_3+T3.AffineTransform_double_3_3)/3;
fixed=(T1.fixed+T2.fixed+T3.fixed)/3;
save('...\meanToInit.mat','AffineTransform_double_3_3','fixed')

Step2-4: Apply the transform from 3 to warp the template towards the true mean shape.

antsApplyTransforms \
-d 3 \
-e 0 \
-i MeanToInit-fa.nii.gz \
-r InitTemp-fa.nii.gz \
-o MeanToInit-faShaped.nii.gz \
-t meanToInit.mat

The errors occured in the Step2-4, and the script can't run.
As you mentioned

Apply the single transform to warp the template towards the true mean shape

, I modify the shape of MeanToInIt-fa.nii.gz (Average of all warped images) to InitTemp-fa.nii.gz (Initial template) with single transform meanToInit.mat. Am I correct?

ntustison · 2019-07-03T13:39:52Z

The protocol for template construction is contained in the scripts. You don't need to attempt to reproduce the steps on your own.

wangken1994 · 2019-07-04T03:53:56Z

@ntustison The reason why I reproduced the steps is that I want to construct the DTI template with these separated steps, since buildtemplateparallel.sh can't be applied to DTI.

The next question is that how to use ANTs scripts to act shape-correction of template.
I refer a shape-correction method from a paper:

This is achieved by first computing an average of the deformation fields that warp each subject into alignment with the template, then warping the template with the inverse of the average deformation field.

This figure shows my procedure, that's register the subjects 1, 2, 3 to template Temp, and average the deformed subjects 1_Temp, 2_Temp, 3_Temp to get the new template Temp_new. At the same time, average the transformations 1_Temp_trans, 2_Temp_trans, 3_Temp_trans to get the mean transformation mean_trans.
Now I want to do shape correction to Temp_new. My codes are shown below:

antsApplyTransforms \
-d 3 \
-e 0 \
-i Temp_new \
-r Temp \
-o Temp_new_shaped \
-t [mean_trans.mat, 1]

i.e Take the old template as the reference image and the new template as the input image with antsApplyTransforms. Am I correct? Besides, the antsApplyTransforms can't run with above codes.

Best!

ntustison · 2019-07-04T17:22:46Z

That's basically the procedure as you've outlined above (although you need to make sure you average the linear part as well). I would encourage you to look at the code in the antsMultivariateTemplateConstruction.sh scripts as that describes exactly what is done.

mairadee · 2019-09-11T09:44:20Z

Hi, may I please know with what commands did you fix the error in your Step2-4, also if I may know the correct call for the step for the sharpening filter. would be very grateful if someone can help.
Thank you in anticipation.

ntustison · 2019-09-11T16:04:40Z

Sharpening is performed in the averaging call.

mairadee · 2019-09-12T08:15:51Z

Sharpening is performed in the averaging call.

Thank you Sir for the prompt response, for my project your assistance would be worthwhile.
For your Step-4 which is to 'Apply the transform from 3 the template to warp the template towards the true mean shape.' I use the Initial Template as reference and the New Template (from step 2) as INPUT ,using the Mean transform (from step 3), but the ApplyTransforms doesn't proceed, it gives error, How should I fix it? Thanks. Maira

mairadee · 2019-09-12T16:34:31Z

@ntustison Can you please help me here?

ntustison · 2019-09-12T17:11:32Z

@mairadee Please provide more information. Simply stating that a failure occurs with a particular program isn't very helpful.

Before further discussion, however, is there a particular reason why you're trying to reproduce the steps of template building instead of simply using the script directly?

mairadee · 2019-09-13T10:30:22Z

@ntustison I've attached the input files of the subject with 4 timepoints and even if I run the script with following options
**antsMultivariateTemplateConstruction2.sh -d 4 -i 3 -k 1 -f 4x2x1 -s 2x1x0vox -q 30x20x4 -t SyN -m CC -c 0 -o MY T1W3D

simluc841F_T1W3D_mri.nii.gz
simluc842F_T1W3D_mri.nii.gz
simluc843F_T1W3D_mri.nii.gz
simluc844F_T1W3D_mri.nii.gz

The template output is as follows but the script ends witht e following message
MY2template0.nii.gz

Exception caught:
itk::ExceptionObject (0x603f960)
Location: "unknown"
File: /home/ec2-user/ants-binaries/ITKv4-install/include/ITK-4.7/itkImageToImageFilter.hxx
Line: 248
Description: itk::ERROR: ImageToImageFilter(0x41b29a0): Inputs do not occupy the same physical space!
InputImage Origin: [-1.3003742e+02, 1.6185423e+02, -6.4711087e+01], InputImage_1 Origin: [-1.3003741e+02, 1.6185423e+02, -6.4711090e+01]
Tolerance: 2.0000000e-06

Using single precision for computations.
Input scalar image: ./MYtemplate0simluc844F_T1W3D_mriRepaired.nii.gz
Reference image: MYtemplate0.nii.gz
Transform file does not exist: ./MYsimluc844F_T1W3D_mri30GenericAffine.mat
Can't read initial transform ./MYsimluc844F_T1W3D_mri30GenericAffine.mat
ls: cannot access MYWarp.nii.gz: No such file or directory
ls: cannot access MYGenericAffine.mat: No such file or directory
shapeupdatetotemplate()

shapeupdatetotemplate---voxel-wise averaging of the warped images to the current template
Fri Sep 13 11:52:18 CEST 2019

ls: cannot access MYtemplate0*WarpedToTemplate.nii.gz: No such file or directory
ERROR shapeupdatedtotemplate - imagelist length is 0

Also the script creates an empty extra TEMPLATE folder
Another query, what are the _Repaired files for ?
Thankyou very much for your time.
Maira

mairadee · 2019-09-13T10:34:01Z

I ran another call for the same set of files as following:

**antsMultivariateTemplateConstruction2.sh -d 4 -i 4 -k 1 -f 6x4x2x1 -s 3x2x1x0vox -q 100x100x70x20 -t SyN -m CC -c 0 -o MY2 T1W3D

but still get the same message.

ntustison · 2019-09-13T13:50:46Z

Why are you using -d 4? These are 3-D images.

mairadee · 2019-09-13T13:59:07Z

-d: ImageDimension: 2 or 3 (for 2 or 3 dimensional registration of single volume)
ImageDimension: 4 (for template generation of time-series data) as mentioned in #L80
(https://github.com/ANTsX/ANTs/blob/master/Scripts/antsMultivariateTemplateConstruction2.sh)

ntustison · 2019-09-13T14:01:43Z

These are not time-series data. You should use -d 3. Here are some examples you should try.

mairadee · 2019-09-13T15:34:56Z

A call as simple as this
**antsMultivariateTemplateConstruction2.sh -d 3 -r 1 -b 1 -c 0 -k 1 -o example_T1W _T1W3D_mri **
would also produce a message similar at the end of the script. though I do get 4 Repaired, 4 metriclog.txt and 4 job_0.sh, and a Template, but its supposed to end successfully, right?

Exception caught:
itk::ExceptionObject (0x3c05c50)
Location: "unknown"
File: /home/ec2-user/ants-binaries/ITKv4-install/include/ITK-4.7/itkImageToImageFilter.hxx
Line: 248
Description: itk::ERROR: ImageToImageFilter(0x3bc06b0): Inputs do not occupy the same physical space!
InputImage Origin: [-1.3003742e+02, 1.6185423e+02, -6.4711087e+01], InputImage_1 Origin: [-1.3003741e+02, 1.6185423e+02, -6.4711090e+01]
Tolerance: 2.0000000e-06

Using single precision for computations.
Input scalar image: ./example_T1Wtemplate0simluc844F_T1W3D_mriRepaired.nii.gz
Reference image: example_T1Wtemplate0.nii.gz
Transform file does not exist: ./example_T1Wsimluc844F_T1W3D_mri30GenericAffine.mat
Can't read initial transform ./example_T1Wsimluc844F_T1W3D_mri30GenericAffine.mat
ls: cannot access example_T1WWarp.nii.gz: No such file or directory
ls: cannot access example_T1WGenericAffine.mat: No such file or directory
shapeupdatetotemplate()

shapeupdatetotemplate---voxel-wise averaging of the warped images to the current template
Wed Sep 13 13:57:57 CEST 2019

ls: cannot access example_T1Wtemplate0*WarpedToTemplate.nii.gz: No such file or directory
ERROR shapeupdatedtotemplate - imagelist length is 0

stnava · 2019-09-13T15:42:31Z

https://github.com/ntustison/TemplateBuildingExample Please verify you can run the above examples. If you can , then you may be able to diagnose the problem yourself by comparing the examples to your own failing case.

On Fri, Sep 13, 2019 at 11:34 AM MInderyas ***@***.***> wrote: A call as simple as this **antsMultivariateTemplateConstruction2.sh -d 3 -r 1 -b 1 -c 0 -k 1 -o example_T1W *_T1W3D_mri* ** would also produce a message similar at the end of the script. though I do get 4 Repaired, 4 metriclog.txt and 4 job_0.sh, and a Template, but its supposed to end successfully, right? Exception caught: itk::ExceptionObject (0x3c05c50) Location: "unknown" File: /home/ec2-user/ants-binaries/ITKv4-install/include/ITK-4.7/itkImageToImageFilter.hxx Line: 248 Description: itk::ERROR: ImageToImageFilter(0x3bc06b0): Inputs do not occupy the same physical space! InputImage Origin: [-1.3003742e+02, 1.6185423e+02, -6.4711087e+01], InputImage_1 Origin: [-1.3003741e+02, 1.6185423e+02, -6.4711090e+01] Tolerance: 2.0000000e-06 Using single precision for computations. Input scalar image: ./example_T1Wtemplate0simluc844F_T1W3D_mriRepaired.nii.gz Reference image: example_T1Wtemplate0.nii.gz Transform file does not exist: ./example_T1Wsimluc844F_T1W3D_mri30GenericAffine.mat Can't read initial transform ./example_T1Wsimluc844F_T1W3D_mri30GenericAffine.mat ls: cannot access example_T1W *Warp.nii.gz: No such file or directory ls: cannot access example_T1W*GenericAffine.mat: No such file or directory shapeupdatetotemplate() ------------------------------ shapeupdatetotemplate---voxel-wise averaging of the warped images to the current template Wed Sep 13 13:57:57 CEST 2019 ls: cannot access example_T1Wtemplate0*WarpedToTemplate.nii.gz: No such file or directory ERROR shapeupdatedtotemplate - imagelist length is 0 — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#520?email_source=notifications&email_token=AACPE7VSTEYDJ7B3XT2BMZTQJOXKDA5CNFSM4EDEOOUKYY3PNVWWK3TUL52HS4DFVREXG43VMVBW63LNMVXHJKTDN5WW2ZLOORPWSZGOD6VMNDA#issuecomment-531285644>, or mute the thread <https://github.com/notifications/unsubscribe-auth/AACPE7UOBMF3LTA77V32ILDQJOXKDANCNFSM4EDEOOUA> .

-- brian

mairadee · 2019-09-17T08:37:44Z

Hi again, thankyou very much for the prompt responses. I tried with the following call from one of the examples:

** buildtemplateparallel.sh -d 3 -o try_ -i 4 -g 0.2 -j 1 -c 0 -m 100x70x50x10 -n 1 -r 1 -s CC -t RI T1W3D **
it does say at the end 'Done creating prefix_Template'
but still gives that ITK Exception message as follows, any help is very regarded and appreciated.Thank you again

User Linear interpolation
Exception caught during WarpImageMultiTransform.

itk::ImageFileReaderException (0x2dfc640)
Location: "unknown"
File: /home/ec2-user/ants-binaries/ITKv4-install/include/ITK-4.7/itkImageFileReader.hxx
Line: 143
Description: Could not create IO object for reading file try_templatewarp.nii.gz
The file doesn't exist.
Filename = try_templatewarp.nii.gz

shapeupdatetotemplate 6

/usr/local/ANTS/bin/buildtemplateparallel.sh: line 347: 21061 Segmentation fault (core dumped) ${ANTSPATH}/MeasureMinMaxMean ${dim} ${templatename}warp.nii.gz ${templatename}warplog.txt 1

Backing up results from iteration 4

cp: cannot stat `try_templatewarp*log.txt': No such file or directory

Done creating: try_template.nii.gz
Script executed in 4912 seconds
1h 21m 52s

ntustison · 2019-09-17T13:05:26Z

Did you actually try running one of the examples? If not, please do that first before trying with your data.

karthikc777 · 2019-09-19T09:20:53Z

Hello Nick,

I also have a template-related question.

Basically, my approach is to create a initial custom template with (ANTSMultivariate) using a subset (20%) of T1w control brains, then warp the rest of the T1w brains (control, patients) to the initial custom template, average this custom template and affine transform it to the MNI 1mm template.

My aim is to have a study specific template in the MNI 1mm template space.

Based on your expertise, could you please comment whether this approach is logical?

Many thanks!

ntustison · 2019-09-19T14:03:16Z

Hi @karthikc777 ,

For many of our studies, we would do something similar where we create a template from a subset of the cohort of interest. Generally, we see convergence with a random sampling of 10-20 brains but typically go beyond this number if the cohort allows it just to play it on the safe side. We don't typically do the extra step of modifying the template with the remaining cohort because a) it's not going to improve the shape or intensity but, also, b) the template building process includes an intensity sharpening which will be negated somewhat if you do the follow up normalization + intensity averaging. Practically it probably won't make much difference but it's not something we do. Finally, we don't typically use the MNI template as everything gets reported in the cohort-specific template space so there's no need to add the additional complexity of normalization to MNI. However, because MNI use is so prevalent, many of our collaborators feel the need to include this step. Therefore, we'll do a final deformable normalization to MNI. We don't limit registration to affine due to the shape differences that are usually apparent between MNI and the cohort-specific template.

Nick

karthikc777 · 2019-09-19T15:12:24Z

Thanks for the quick and detailed reply :)

Best regards,
Karthik

mairadee · 2019-09-24T09:19:11Z

Thank you @ntustison for the support, we have asked our systems operator to check for the update of ANTS library and for ITK tool. I will try with you data and will contact you again for any queries. Thanks again.

ntustison closed this as completed Jan 29, 2018

gdevenyi mentioned this issue Apr 6, 2021

REQUEST: principles of template construction: Wiki page connecting the script to the math/principles in the paper? #1172

Closed

ntustison mentioned this issue Oct 27, 2021

ANTsPy Template Creation ANTsX/ANTsPy#306

Closed

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

The basic principles in template construction #520

The basic principles in template construction #520

younghoo commented Nov 10, 2017

ntustison commented Nov 10, 2017

aghayoor commented Jan 29, 2018 •

edited

Loading

ntustison commented Jan 29, 2018

aghayoor commented Jan 30, 2018

wangken1994 commented Jul 3, 2019

ntustison commented Jul 3, 2019

wangken1994 commented Jul 3, 2019

ntustison commented Jul 3, 2019

wangken1994 commented Jul 4, 2019

ntustison commented Jul 4, 2019

mairadee commented Sep 11, 2019

ntustison commented Sep 11, 2019

mairadee commented Sep 12, 2019

mairadee commented Sep 12, 2019

ntustison commented Sep 12, 2019

mairadee commented Sep 13, 2019 •

edited

Loading

mairadee commented Sep 13, 2019

ntustison commented Sep 13, 2019

mairadee commented Sep 13, 2019

ntustison commented Sep 13, 2019

mairadee commented Sep 13, 2019

stnava commented Sep 13, 2019 via email

mairadee commented Sep 17, 2019

ntustison commented Sep 17, 2019

karthikc777 commented Sep 19, 2019

ntustison commented Sep 19, 2019

karthikc777 commented Sep 19, 2019

mairadee commented Sep 24, 2019

The basic principles in template construction #520

The basic principles in template construction #520

Comments

younghoo commented Nov 10, 2017

ntustison commented Nov 10, 2017

aghayoor commented Jan 29, 2018 • edited Loading

ntustison commented Jan 29, 2018

aghayoor commented Jan 30, 2018

wangken1994 commented Jul 3, 2019

ntustison commented Jul 3, 2019

wangken1994 commented Jul 3, 2019

ntustison commented Jul 3, 2019

wangken1994 commented Jul 4, 2019

ntustison commented Jul 4, 2019

mairadee commented Sep 11, 2019

ntustison commented Sep 11, 2019

mairadee commented Sep 12, 2019

mairadee commented Sep 12, 2019

ntustison commented Sep 12, 2019

mairadee commented Sep 13, 2019 • edited Loading

shapeupdatetotemplate---voxel-wise averaging of the warped images to the current template Fri Sep 13 11:52:18 CEST 2019

mairadee commented Sep 13, 2019

ntustison commented Sep 13, 2019

mairadee commented Sep 13, 2019

ntustison commented Sep 13, 2019

mairadee commented Sep 13, 2019

shapeupdatetotemplate---voxel-wise averaging of the warped images to the current template Wed Sep 13 13:57:57 CEST 2019

stnava commented Sep 13, 2019 via email

mairadee commented Sep 17, 2019

shapeupdatetotemplate 6

Backing up results from iteration 4

ntustison commented Sep 17, 2019

karthikc777 commented Sep 19, 2019

ntustison commented Sep 19, 2019

karthikc777 commented Sep 19, 2019

mairadee commented Sep 24, 2019

aghayoor commented Jan 29, 2018 •

edited

Loading

mairadee commented Sep 13, 2019 •

edited

Loading

shapeupdatetotemplate---voxel-wise averaging of the warped images to the current template
Fri Sep 13 11:52:18 CEST 2019

shapeupdatetotemplate---voxel-wise averaging of the warped images to the current template
Wed Sep 13 13:57:57 CEST 2019