This page describes how to generate deformation fields that can be applied to MINC files. These simulated deformation fields were used to assess registration algorithms.. Specifically, we look at how accurate we are at finding neuroanatomical differences between groups of mice using image registration (minctracc, mincANTS). Also, we look at whether the sensitivity for detecting shape differences vary across the brain. A paper published on this work can be found here: http://www.sciencedirect.com/science/article/pii/S105381191300640X
Software
The software that supports this project is under version control and located here:
https://github.com/mcvaneede/generate_deformation_fields
Prerequisites:
> sudo apt-get install build-essential gfortran automake libtool
The MINC libraries need to be installed as well. These can be found on GitHub:
https://github.com/BIC-MNI/libminc
Recommended MINC tools (this will install the library mentioned above as well):
https://github.com/BIC-MNI/minc-toolkit-v2
or
https://github.com/BIC-MNI/minc-toolkit
General way of installation (automake and libtool should be installed):
> ./autogen.sh > ./configure --prefix=/path/to/where/tools/will/be/installed --with-minc2 --with-build-path=/path/to/where/minc/installation/lives > make > make install
The cython part of the code is not installed automatically at the moment. To compile the cython code make sure the cython library is installed and that the path to the library is in the $PYTHONPATH environment variable. Then run:
> cd scripts > python setup.py build_ext --inplace > python setup.py install --prefix=/path/to/where/tools/will/be/installed --install-lib=/path/to/where/python/libs/should/go
in the scripts directory.
Testing the installed software
For more information about how the software works, and what is expected from the input files, see the sections below
The git repository contains a folder called test_files. These are two files that are used to create a test deformation field:
- target_tolerance_space_test_file.mnc
- target_determinant_test_file.mnc
This is what they look like and what they indicate (shown using the program "register", which is part of the minc-toolkit. The left and middle image show the tolerance space and target determinant file respectively, on the right is the overlay between the two images):
These can be used to test the code as follows:
# run the code on the test files: > create_deformation.py -t 0.00001 -m target_tolerance_space_test_file.mnc target_determinant_test_file.mnc test_deformation.xfm # calculate the Jacobian determinant from the output grid file: > mincblob -det test_deformation_grid.mnc test_deformation_grid_determinant.mnc # add 1 to the volume, because mincblob has subtracted the value 1 from all values... > mincmath -add -const 1 test_deformation_grid_determinant.mnc test_deformation_grid_determinant_plus_one.mnc # compare your output with the output in the test_files directory: > mincdiff test_deformation_grid_determinant_plus_one.mnc target_determinant_test_file_deformation_grid_det_p1.mnc # You will find that differences are found in the header of the files, such as the date, name of the file # etc., but this is not important. The last two lines should say: Binary image comparison: Images are identical. # which means that the actual data contained in the MINC files are identical.
What is needed in order to make a deformation field?
The desired deformation field is created using a Jacobian determinant map. The Jacobian determinant of a deformation field specifies whether the change in each voxel is due to atrophy or expansion. Voxels with a value less than 1 shrink (atrophy), voxels with a value greater than 1 grow (expansion). A determinant of 1 means no change. So first we need a region of interest (ROI) in which we want to create a change. This can be any shape (e.g., labels of neuroanatomical regions, squares, spheres...). Furthermore we need a map that indicate areas that are allowed to grow or shrink to account for the intended change. So we need the two following files:
- target determinant map (ROI has values either smaller than 1 (atrophy) or larger than 1 (expansion), other voxels have the value 1 (no change))
- tolerance map (map that indicate voxels which are allowed to either grow or shrink with the value 1)
In this example we will shrink the striatum of the brain by 20%. We have the following files: on the left a slice through the MR image that we want to deform. In the middle a segmentation of the striatum that we use to create a target determinant map from, and on the right a ring of voxels outside of the brain that will be used as tolerance space.
Here is the same image, but with the outline of the striatum segmentation in red shown on all images, and the outline of the tolerance space in yellow shown on all images:
How to work with the software
A target determinant can be created from a mask or structure label. In the following example the file striatum.mnc is a binary file where voxels with the value 1 belong to the striatum and voxels with the value 0 are non-striatum voxels. The output determinant file will shrink the striatum by 20%:
> minccalc -expression 'if(A[0] == 1) {out = 0.8;} else {out = 1;}' striatum.mnc striatum_determinant_20_percent_shrinkage.mncThe method above would be the most used (and probably most useful) way to create a determinant, because in general you will have fairly specific ROI that you want to change. Alternatively, you can use a program that will create a target determinant in the form of an octahedron. At the moment, this program is very limited in the kinds of determinants it can create, because only octahedrons can be created. The parameters are given in voxel space. The output determinant will shrink the octahedron area by 40%:
# base_test_file.mnc -- is used to determine the dimensions/resolution of the output file # the center (-c) is given in voxel coordinates > create_determinant.py -c 10,10,10 -d 0.6 -r 5 base_test_file.mnc base_test_file_det_0.6_at_10_10_10_radius_5.mnc
Alternatively,
(optional) If you created several areas that require change, merge these into one file. Example for two input files:
> minccalc -expression 'if(A[0] == 1 && A[1] == 1) {out = 1;} else if(A[0] == 1 && A[1] != 1) {out = A[1];} else if(A[0] != 1 && A[1] == 1) {out = A[0];} else {out = A[0] + A[1];}' base_test_file_det_10_10_10_r_5.mnc base_test_file_det_20_20_20_r_3.mnc base_test_file_det_combined.mnc(optional) Blur the final determinant file, example:
> blur_determinant.py -b 0.24 base_test_file_det_combined.mnc base_test_file_det_combined_blur_0.24.mnc
- Create a tolerance map; a map indicating voxels that are allowed to grow and shrink semi-freely (e.g., CSF, background). The jacobian determinant for a voxel indicates the amount of growth or shrinkage at that voxel. If the value is 1, that means no change, if it is 2 the voxel is doubled in volume/size, and if it is 0.5, the voxel is half the size of its original size. Given that the range of Jacobian runs from (0,infinity), the meaning of a value in the tolerance map is as follows
- Tolerance map value 0: voxel is only allowed to change within the limits of the overall tolerance (set by -t)
- Tolerance map value 1: voxel's determinant can range from 0.5-2, i.e., twice the size or half the size
- Tolerance map value 2: voxel's determinant can range from 0.333-3, i.e., three times the size or one third of the size
etc.
# In this example, we have access to a segmentation where the lateral ventricles have label values 57 and 77. # We use the program minc_label_ops to segment out these two structures from the segmentation and binarize them # minc_label_ops is part of: https://github.com/Mouse-Imaging-Centre/minc-stuffs > minc_label_ops --select=57,77 --binarize brain_atlas_labels.mnc lateral_ventricles.mnc # you can also create a ring of tolerance space around the brain if you have a brain mask. Using the atlas you can run # the following. The -successive flag for mincmorph allows you to specify multiple operations in sequence. The first # part B[0.5:999] will binarize the file. All voxels with a value between 0.5 and 999 will become 1, all others 0. # The Ds (DDDD and DDDDDDDDDD) will then dilate (add a layer of voxels around the current "object") the shape 4 and # 10 times respectively. > mincmorph -successive B[0.5:999]DDDD brain_atlas_labels.mnc dilated_mask.mnc > mincmorph -successive B[0.5:999]DDDDDDDDDD brain_atlas_labels.mnc more_dilated_mask.mnc > minccalc -expression 'if(A[0] == 1 && A[1] == 0) {out = 1;} else {out = 0;}' more_dilated_mask.mnc dilated_mask.mnc tolerance_ring_around_brain.mnc
Create a deformation field that will produce the growth and shrinkage indicated in the determinant file, example:
# Input files: # mouse_brain.mnc -- anatomical MR scan # striatum.mnc -- segmentation of the striatum, 1 indicates striatum, 0 is background # tolerance_space.mnc -- binary ring of voxels around the brain (1 is ring, 0 is background) # # In order to shrink the striatum by 20% we ran the following command > minccalc -expression 'if(A[0] == 1) {out = 0.8;} else {out = 1;}' striatum.mnc striatum_determinant_20_percent_shrinkage.mnc # # This gives us the following input files:
create_deformation.py \ -t 0.00001 \ -i 100000 \ -m tolerance_space.mnc \ striatum_determinant_20_percent_shrinkage.mnc \ deformation_field_20_percent_shrinkage_striatum.xfm
If we now look at the Jacobian determinant of the deformation field we just produced, it will become clear why we need the tolerance space:
# calculate the determinant: mincblob -det deformation_field_20_percent_shrinkage_striatum_grid.mnc deformation_field_20_percent_shrinkage_striatum_grid_determinant.mnc # and we have to add 1 to all voxels, because internally, mincblob subtracts 1 from all calculated values... mincmath -add -const 1 deformation_field_20_percent_shrinkage_striatum_grid_determinant.mnc deformation_field_20_percent_shrinkage_striatum_grid_determinant_plus_one.mnc
This is what that file looks like:
There are a couple of things to note here. The black region (striatum area) has the value 0.8001 (i.e., when you apply this transformation to your input file, it will indeed shrink the striatum by 20%). The gray areas have a Jacobian determinant of 1 meaning no change, and the light gray / white areas have Jacobian determinants ranging from 1-2. This area will grow in size when the transformation is applied. The reason this is necessary, is because the algorithm initializes a zero vector field, and iteratively updates all vectors to approximate the desired determinant. In order to shrink one area, some other area needs to grow to accommodate that change. This also means that it is important to use tolerance space in areas that either naturally change in volume, or as in this case, use areas outside of the brain altogether.
Applying the transformation to the input file
# assuming that the MR brain image on the left of each of the plots is called MR.mnc, this is how you would apply the deformations: mincresample \ -like MR.mnc \ -transformation deformation_field_20_percent_shrinkage_striatum.xfm \ MR.mnc \ MR_striatum_20_percent_smaller.mnc
To view the other available options:
> create_deformation.py --help
(Note: important to use blur_determinant for blurring)
(Note 2: creating deformation fields for areas that grow seems to be broken at the moment for large amounts of growth, e.g. jacobian determinant of 2, but works well for values like 1.2)
NeuroImage paper
Work published using this code can be found here: http://www.sciencedirect.com/science/article/pii/S105381191300640X
ISMRM 2010 poster
Preliminary data for this project was presented at ISMRM 2010. The poster presented at ISMRM 2010 can be found here.
Movie showing the deformation creation process
In the following video. the process of creating the deformation field is visualized. The deformation field starts off as a zero vector field, and the vectors are being updated along the way to create the desired jacobian determinant. To create the video, intermediate deformation fields were written out to disk and the input file was resampled using these deformation fields. On the left side in the movie you see the brain being deformed throughout this process. Overlaid in green is the deformation grid at that slice, showing how voxels are being deformed. In blue are areas of that brain that are shrinking and in red are areas of the brain (or outside of the brain) that are growing. On the right side of the image is a plot which represents the volume changes in the striatum, the lateral ventricle and the cortex during the process. The striatum is intended to reduce its size by 50%, and the ventricle is allowed to double or half its size to accommodate for this change. In addition to that there is a ring outside of the brain where deformations can also freely occur. As you can see, the cortex initially grows in size. This happens when the striatum is getting smaller, and the deformations to allow for this are moving to the outside of the brain. When these deformations reach the outside of the brain, the cortex is reduced to its initial size at the end of the process.