This wiki page will walk-through an example to make an initial model. You may not need all the steps or you may need more steps based on your individual situation, but this will hopefully be a rough guide as to the steps involved. Please first go through this guide (Using an Initial Model) so you are familiar with how initial models are used. It is likely that the initial model you want already exists at MICe so ask around and check this directory (/hpf/largeprojects/MICe/tools/initial-models/). If the images you want to register are already in the standard space we use at MICe, then making a model is much easier (see option 1 in Using an Initial Model) and will not be covered here. If, however, the files you want to register are in a native space that is DIFFERENT to the standard space used at MICe, then this guide may be useful for you to make an initial model.
There are 5 files you need to make (see option 2 in Using an Initial Model):
- image.mnc - this is the initial model in standard space
- image_mask.mnc - this is the initial model's mask in standard space
- image_native_to_standard.xfm - this is the rigid transformation aligning the native space to the standard space.
- image_native.mnc - this is the initial model in native space
- image_native_mask.mnc - this is the initial model's mask in native space
This guide will show you how to make all of these files. In this example, I will create a directory and place all the files with the proper names in that directory.
mkdir ../spring-b0-DTI-80-micron-basket-jul-2021
Initial model in standard space
Here is an example of a native image:
First register many (or all) the native images together using MBM.py and the bootstrap flag
MBM.py \
--bootstrap \
--pipeline-name=bootstrap_b0 \
--subject-matter mousebrain \
--num-executors 30 \
--time 48:00:00 \
--no-common-space-registration \
--no-run-maget --maget-no-mask \
--lsq12-protocol /hpf/largeprojects/MICe/tools/protocols/linear/Pydpiper_testing_default_lsq12.csv \
--files ../b0_images/*.mnc
Check the information of the consensus average. This file we will be the starting point of our initial model.
mincinfo bootstrap_b0_nlin/bootstrap_b0-nlin-3.mnc # file: bootstrap_b0_nlin/bootstrap_b0-nlin-3.mnc # image: unsigned short 0 to 65535 # image dimensions: zspace xspace yspace # dimension name length step start # -------------- ------ ---- ----- # zspace 180 0.0777778 -25.9611 # xspace 180 -0.0777778 29.9611 # yspace 324 -0.0771605 12.4614
Copy the consensus average file so you can modify it without worry.
cp bootstrap_b0_nlin/bootstrap_b0-nlin-3.mnc reg_avg.mnc
Sometimes, you may need to modify direction cosines to align the directions. If you don't need to, running this command will do nothing (so there is no real risk to run it)
minc_modify_header -dinsert xspace:direction_cosines=1,0,0 reg_avg.mnc minc_modify_header -dinsert yspace:direction_cosines=0,1,0 reg_avg.mnc minc_modify_header -dinsert zspace:direction_cosines=0,0,1 reg_avg.mnc
Use register to align our consensus average to one of the existing initial models at MICe. Make sure to use 5 or more tag points and be careful about your left/right axis.
register /hpf/largeprojects/MICe/tools/initial-models/Pydpiper-40-micron-basket-dec-2014/basket_mouse_brain_40micron.mnc reg_avg.mnc
Also, note the start and length information from the reference init model.
mincinfo /hpf/largeprojects/MICe/tools/initial-models/Pydpiper-40-micron-basket-dec-2014/basket_mouse_brain_40micron.mnc # file: /hpf/largeprojects/MICe/tools/initial-models/Pydpiper-40-micron-basket-dec-2014/basket_mouse_brain_40micron.mnc # image: unsigned short 0 to 65535 # image dimensions: zspace yspace xspace # dimension name length step start # -------------- ------ ---- ----- # zspace 241 0.04 -4.2 # yspace 478 0.04 -8.19 # xspace 315 0.04 -6.27
Transform our consensus average to this new orientation.
mincresample -like /hpf/largeprojects/MICe/tools/initial-models/Pydpiper-40-micron-basket-dec-2014/basket_mouse_brain_40micron.mnc \ -transform rough_align.xfm \ reg_avg.mnc reg_avg_rough_orient.mnc
Our consensus average is now sampled the same way as the reference initial model
mincinfo reg_avg_rough_orient.mnc # file: reg_avg_rough_orient.mnc # image: unsigned short 0 to 65535 # image dimensions: zspace yspace xspace # dimension name length step start # -------------- ------ ---- ----- # zspace 241 0.04 -4.2 # yspace 478 0.04 -8.19 # xspace 315 0.04 -6.27
You may have to do some finer adjustments to our consensus average. In this example, the consensus average still needs to be rotated about the y-axis by roughly 1 degree
To perform the rotation sensibly, use the center of the volume as the center of rotation. To find center of mass, use the information from the mincinfo command run earlier. Here is an example for to calculate center of mass in the y-coordinate.
0.5 * ( 478 * 0.04 ) - 8.19 # 1.37
In the same way, center of mass in the x and z coordinates can be determined.
To rotate by 1 degree along the y axis, create a transformation file (using param2xfm) and resample the file with this transformation (using mincresample).
param2xfm \ -center 0.03 1.37 0.62 \ -rotations 0 1 0 fine_align1.xfm mincresample -use_input_sampling \ -transform fine_align1.xfm \ reg_avg_rough_orient.mnc reg_avg_fine_align.mnc
This fine-adjustment is sufficient.
Furthermore, I noticed that the sagittal mid-place is x=162 (green line). But the middle of the volume in the x-dimension is 157.5 (red line).
This means to center the brain in the volume, we need to move the sampling window 4.5 voxels to the right (i.e. 0.18mm to the right).
mincresample -use_input_sampling \
-xstart -6.09 \
reg_avg_fine_align.mnc reg_avg_centered.mnc
Lastly, we want to set the resolution closer to our native images (80um in this case). We change length correspondingly to ensure that the volume remains the same. For example, the new length for the x-axis is:
315 * 0.04 / 0.08 # 157.5
Similarily, you can determine the new dimension lengths for the other dimensions and pass them to mincresample using the nelements argument.
mincresample \
-step 0.08 0.08 0.08 \
-nelements 158 239 121 \
reg_avg_centered.mnc reg_avg_centered_proper_resolution.mnc
Notice the resolution is now correct.
mincinfo reg_avg_centered_proper_resolution.mnc # file: reg_avg_centered_proper_resolution.mnc # image: unsigned short 0 to 65535 # image dimensions: zspace yspace xspace # dimension name length step start # -------------- ------ ---- ----- # zspace 121 0.08 -4.2 # yspace 239 0.08 -8.19 # xspace 158 0.08 -6.09
This file will go on to be the initial model in standard space. Copy the file into final directory:
cp reg_avg_centered_proper_resolution.mnc ../spring-b0-DTI-80-micron-basket-jul-2021/b0_DTI_80um.mnc
Initial model mask in standard space
There are many ways to make a mask. In this example, I will create a mask by register an atlas to our initial model. The atlas I will be using is the DSURQEE atlas and the resultant transformation is called atl_to_modl.xfm
# Do an affine registration
antsRegistration -d 3 \
-o affine_atl_to_modl \
-a 1 -z 1 \
-t Affine[0.25] -m MI[reg_avg_centered_proper_resolution.mnc,/hpf/largeprojects/MICe/tools/atlases/Dorr_2008_Steadman_2013_Ullmann_2013_Richards_2011_Qiu_2016_Egan_2015_Elder_2019_40micron/DSURQEE_40micron_average.mnc,1,32,Regular,0.25] \
--convergence [1000x500x250x100,1e-6,10] \
--shrink-factors 8x4x2x1 \
--smoothing-sigmas 0.2x0.1x0.05x0mm \
--minc -v 1 --use-histogram-matching 1
# resample the atlas and its mask
mincresample \
-like reg_avg_centered_proper_resolution.mnc \
-transform affine_atl_to_modl.xfm /hpf/largeprojects/MICe/tools/atlases/Dorr_2008_Steadman_2013_Ullmann_2013_Richards_2011_Qiu_2016_Egan_2015_Elder_2019_40micron/DSURQEE_40micron_average.mnc \
atl_avg_affine.mnc
mincresample -nearest -label \
-like reg_avg_centered_proper_resolution.mnc \
-transform affine_atl_to_modl.xfm /hpf/largeprojects/MICe/tools/atlases/Dorr_2008_Steadman_2013_Ullmann_2013_Richards_2011_Qiu_2016_Egan_2015_Elder_2019_40micron/DSURQEE_40micron_mask.mnc \
atl_mask_affine_nondilated.mnc
# generously dilate the mask before using it in the non-affine registration
mincmorph \
-successive DDDDDDDDDDDDDDDDDDDDD \
atl_mask_affine_nondilated.mnc atl_mask_affine.mnc
# Do a non-affine registration
antsRegistration -d 3 \
-o non_affine_atl_to_modl \
-x atl_mask_affine.mnc \
-a 1 -z 1 \
-t SyN[0.1,2,0] \
-m MI[atl_avg_affine.mnc,reg_avg_centered_proper_resolution.mnc,1,32,Regular,0.25] \
--convergence [1000x1000x1000x1000,1e-6,10] \
--shrink-factors 8x4x2x1 \
--smoothing-sigmas 0.2x0.1x0.05x0mm \
--minc -v 1 --use-histogram-matching 1
# concatenate the affine and non-affine transformations
xfmconcat affine_atl_to_modl.xfm non_affine_atl_to_modl.xfm atl_to_modl.xfm
We can transform the atlas mask so it aligns with our initial model.
mincresample -nearest -label \ -like reg_avg_centered_proper_resolution.mnc \ -transform atl_to_modl.xfm \ /hpf/largeprojects/MICe/tools/atlases/Dorr_2008_Steadman_2013_Ullmann_2013_Richards_2011_Qiu_2016_Egan_2015_Elder_2019_40micron/DSURQEE_40micron_mask.mnc \ mask_nondilated.mnc
Before using the mask as for our initial model is it best to dilate and erode the mask. You want it to cover the entirety of the brain and still have a 0.3-0.7 mm buffer. Exactly how much you want to dilate and erode is something you should decide manually. In this example, this is the command I used:
mincmorph -successive EEDEEDEEDEEDEEDEEDEEDEEDDDDDDDDDDDDDDDD mask_nondilated.mnc mask.mnc
We are now done making the standard mask. Copy it to the final directory with the proper name.
cp mask.mnc ../spring-b0-DTI-80-micron-basket-jul-2021/b0_DTI_80um_mask.mnc
Native-to-standard space transformation
Look at the native and standard brains from earlier:
Notice that rotating by 180 degrees about the z-axis roughly accounts for the native-to-standard transformation. However, we want to define the center of mass to be the center of rotation. We can use mincinfo to find center of mass.
mincinfo reg_avg_centered_proper_resolution.mnc # file: reg_avg_centered_proper_resolution.mnc # image: unsigned short 0 to 65535 # image dimensions: zspace yspace xspace # dimension name length step start # -------------- ------ ---- ----- # zspace 121 0.08 -4.2 # yspace 239 0.08 -8.19 # xspace 158 0.08 -6.09
From this information, we can determine that the xyz-coordinates of the center of mass (in mm) is (0.23,1.37,0.64)
To create the native-to-standard transformation, use param2xfm.
param2xfm -center 0.23 1.37 0.64 -rotation 0 0 180 native_to_standard.xfm
We have completed making the native-to-standard transformation. Copy it to the final directory with the proper name.
cp native_to_standard.xfm ../spring-b0-DTI-80-micron-basket-jul-2021/b0_DTI_80um_native_to_standard.xfm
Initial model in native space
By inverting the native-to-standard transformation, we can take our standard initial model and move it to native space.
mincresample -use_input_sampling \
-invert -transform native_to_standard.xfm \
reg_avg_centered_proper_resolution.mnc \
native_cropped_nodimorder.mnc
There are two things we still have to do before we use these native model. First, we have to change the dimension order. Note that the consensus average has dimension order Z-X-Y.
mincinfo bootstrap_b0_nlin/bootstrap_b0-nlin-3.mnc # file: bootstrap_b0_nlin/bootstrap_b0-nlin-3.mnc # image: unsigned short 0 to 65535 # image dimensions: zspace xspace yspace # dimension name length step start # -------------- ------ ---- ----- # zspace 180 0.0777778 -25.9611 # xspace 180 -0.0777778 29.9611 # yspace 324 -0.0771605 12.4614
But our native model has dimension order Z-Y-X.
# mincinfo native_cropped_nodimorder.mnc # file: native_cropped_nodimorder.mnc # image: unsigned short 0 to 65535 # image dimensions: zspace yspace xspace # dimension name length step start # -------------- ------ ---- ----- # zspace 121 0.08 -4.2 # yspace 239 0.08 -8.19 # xspace 158 0.08 -6.09
Use mincreshape to change the dimension order.
mincreshape \
-dimorder zspace,xspace,yspace \
native_cropped_nodimorder.mnc \
native_cropped.mnc
The second (and last) thing we have to do to the native model is to pad it so the volume is the same as the volume of our native images. You can manually compute how length and start coordinate need to change in order to pad native_cropped.mnc symmetrically to be the same volume as the consensus average. For example, here is the computation for the x coordinate.
# length of x-axis of the nlin volume Lx1 = 180 * abs(-0.0777778) # length of x-axis of the cropped volume Lx2 = 158 * abs(0.08) # difference in length dLx = Lx1 - Lx2 # To pad left, reduce start value by half the length new_start_x = -6.09 - dLx/2 #(value is -6.770002) # To pad right, increase length value new_length_x = 158 + dLx/0.08 #(value is 175)
You can repeat this procedure for the other dimensions. Then use the mincresample command.
mincresample \ -start -6.770002 -11.130001 -6.360002 \ -nelements 175 313 175 \ native_cropped.mnc native.mnc
We have completed making the native model. Copy it to the final directory with the proper name.
cp native.mnc ../spring-b0-DTI-80-micron-basket-jul-2021/b0_DTI_80um_native.mnc
Initial model mask in native space
Repeat the same transformations you did for create the initial model in native space, except this time use the standard mask as the input and add the -nearest and -labels flags to mincresample.
# transform to native
mincresample -nearest -labels -use_input_sampling \
-invert -transform native_to_standard.xfm \
mask.mnc native_cropped_nodimorder_mask.mnc
# reorder dimensions
mincreshape \
-dimorder zspace,xspace,yspace \
native_cropped_nodimorder_mask.mnc \
native_cropped_mask.mnc
# pad volume
mincresample -nearest -label \
-start -6.770002 -11.130001 -6.360002 \
-nelements 175 313 175 \
native_cropped_mask.mnc native_mask.mnc
We have completed making the native model mask. Copy it to the final directory with the proper name.
cp native_mask.mnc ../spring-b0-DTI-80-micron-basket-jul-2021/b0_DTI_80um_native_mask.mnc
The final directory should now contain the following files:
- b0_DTI_80um.mnc - this is the initial model in standard space
- b0_DTI_80um_mask.mnc - this is the initial model's mask in standard space
- b0_DTI_80um_native_to_standard.xfm - this is the rigid transformation aligning the native space to the standard space.
- b0_DTI_80um_native.mnc - this is the initial model in native space
- b0_DTI_80um_native_mask.mnc - this is the initial model's mask in native space
You can now use this initial model in your registration.
MBM.py \
--init-model=../spring-b0-DTI-80-micron-basket-jul-2021/b0_DTI_80um.mnc \
--pipeline-name=b0 \
--subject-matter mousebrain \
--num-executors 30 \
--time 48:00:00 \
--no-common-space-registration \
--no-run-maget --maget-no-mask \
--lsq12-protocol /hpf/largeprojects/MICe/tools/protocols/linear/Pydpiper_testing_default_lsq12.csv \
--files ../b0_images/*.mnc