Please ensure you are using the latest quarantine. For a list of all quarantines see this page: Registration Quarantines (deprecated)
Hm toothless. I could have sworn you had.... teeth
|Established||September 22, 2011|
|Setting the environment|
|-mask-out-brains||Masks out the brain after the lsq6 stage. Works for mouse brains only. This option needs to be run with the -individual-mask option. Also note that the masking done here is fairly "coarse" so to speak. This will not do a perfect job. To get a better mask for your input files, see below.|
|-w-rotations||Settings for minctracc (registration algorithm) for lsq6 and lsq12: Comma separated list of optimization weight of rotations around x, y, z|
|-w-scales||Settings for minctracc (registration algorithm) for lsq6 and lsq12: Comma separated list of optimization weight of scaling along x, y, z|
|-w-shear||Settings for minctracc (registration algorithm) for lsq6 and lsq12: Comma separated list of optimization weight of shears a,b and c|
|-w-translations||Settings for minctracc (registration algorithm) for lsq6 and lsq12: Comma separated list of optimization weight of translations in x, y, z|
|-use-ram-disk-for-large-rotations||Use the ram disk as the temporary directory for the minctracc version capable of handling large rotations.|
|-lsq6-rotational-resample-step||Step size to which images should be resampled before using rotational minctracc.|
|-lsq6-rotational-registration-step||Step size that will be used in minctracc for the registrations in rotational minctracc.|
|section on replacing the fluid layer||We have determined why the bright rim appears around the brain, and given that it happens through preparation/fixation artifacts, these brains are actually not usable. So you should not have to use the options in this section.|
|-lsq12-max-pairs||Maximum number of pairwise lsq12 registration to compute per scan. If you are running a study with many subjects (40, 60, 100...) it is not necessary to perform all possible pair-wise affine registrations. This number really blows up, and running all pair-wise registrations won't really give you a different answer. You can set this to 20 in those cases. One note, there is a bug in the code which could cause the program to get in an infinite loop if you set this parameter to a number slightly smaller than the number of samples in your pipeline (e.g., 20 with 22 subjects). In those cases, simply set it to 0, so it will run all possible pairs.|
|-nlin-registration-method||This options specifies which non linear registration algorithm should be used. The two options are minctracc and mincANTS. The default here is still minctracc, but mincANTS should be used, because it produces better (more defined, less noisy) deformation fields.|
It's okay, you just scared him.
Most important change
This most important change in this quarantine compared to the previous one ("how old") is that you have the option to use either minctracc or mincANTS for the non linear part of the registration. minctacc is true and tried, we've been using it for many years and delivers good registration results. One issue that does arise with minctracc is that the final deformation fields (we ultimately use these to analyze our data) are quite noise, and we have to apply a fair bit of blurring to them to reduce the noise and use them in our analysis. mincANTS produces much more defined deformation fields, and is thus the preferred method for registration. Below you see an image comparing the unblurred Jacobian determinants of a minctracc deformation field and that of a mincANTS deformation field. The image on the right (mincANTS) clearly produces more well-defined results.
By default the registration pipeline code in the Toothless quarantine uses minctracc for its non linear registration. It's important to specify mincANTS instead:
Use mincANTS when running a registration pipeline:
Possible issue with mincANTS (bumps or indentations)
So first we tell you to use mincANTS, and then we tell you that you might have issues while using it. Nice, right? But don't despair, we also have a solution to the possible issues that might arise. The three images below give examples of how the registration might go wrong. When you have run your registration pipeline it is important that you check how well your final nlin files align (these are located in the _processed folder, and have the form */resampled/*-resampled-final-nlin.mnc where * is the basename of your input files). The three images below compare two -resampled-final-nlin.mnc files from a mincANTS pipeline. The image on the right has contours imposed on it, and these are also overlaid on the image on the left (red lines) to be able to compare the alignment of the boundary of the brain. Then areas of misalignment are indicated in either yellow or blue. These artifacts seem to arise because of bright tissue present in the MR scans around the brain.
Solution for mincANTS issue
As mentioned earlier, the problems seem to stem from bright tissue/areas around the brain that vary from brain scan to brain scan. This means that we can solve the problem by masking out the input files. How can we get masks for the input files:
- Perform a rough/quick registration
- using minctracc
- using mincANTS with more regularization on the deformation fields
- using MAGeT
- Create a mask for the final average of this registration pipeline
- Map the mask back to the native files and
- Mask them out
- Check masked files
- Rerun mincANTS pipeline
Step 1a: rough/quick registration using minctracc
You only have to run 1 registration, either the quick minctracc, or the regularized mincANTS or MAGeT. Which of the three will work best is hard to predict. Certain however, is that the quick minctracc registration runs a lot faster than mincANTS. The speed of MAGeT will depend on the number of input atlases used and whether or not the minctracc or mincANTS protocol is being used.
Below is the command you can use to run a quick minctracc registration. The -nlin-partial argument will only perform 2 non linear stages.
Step 1b: registration using mincANTS with more regularization on the deformation fields
Below is the command you can use to run a different mincANTS registration. This registration is more restricted in terms of the deformation allowed, and as such is (most likely) not the best to use for your analysis, but it will probably overcome most if not all the the misregistration issues at the boundaries of the brain.
The content of that protocol can be found here: mincANTS_protocol_regularization_on_def_field.pl
Step 1c: registration using MAGeT
MAGeT is described in more detail here. Currently, the masking procedure works as a standard multi-atlas registration. A single input atlas can be used, but the algorithm will work better with multiple input atlases. An example command for running MAGeT to create masks only (without also creating labels) is:
Step 2: create a mask for the final average
Again, here you have the choice between creating a mask using minctacc (atlas_to_atlas), and mincANTS. And once again, minctracc will be a lot faster, however especially in this case, mincANTS could produce a significantly better result.
If you used MAGeT to register your brains, you will already have a mask for each brain, and steps 2 and 3 are unnecessary. In addition, MAGeT will complete step 4 automatically and place the masked file in the resampled directory, so you can proceed directly to step #5.
Step 2a: atlas_to_atlas
You just ran a partial minctracc, or conservative mincANTS registration, and you will now need to create a mask for the final average of that pipeline: nlin-2.mnc (or nlin-3.mnc if you ran the mincANTS registration). You can find that file in the _nlin folder of your pipeline. To create a mask, you need to create labels for the nlin-2.mnc (or nlin-3.mnc) file. Follow the instructions on the Atlas to Atlas Segmentation page to create a "resampled_atlas.mnc".
Step 2b: mincANTS
If you find that the atlas_to_atlas registration does not produce a usable mask, you can run a mincANTS registration. Just as with the atlas_to_atlas procedure, you should chose a template brain/segmentation from the set of brains we have: Mouse Brain Atlases
What you'll need:
- source file, and the gradients of the source file at the file resolution (so if you have a 56micron file, you'll need create source_fwhm_0.056_dxyz.mnc using mincblur). This will be one of the mouse brain atlases we have
- target file, and the gradients of the target file (nlin-2.mnc or nlin-3.mnc)
- source mask file
In this case, the resampled_atlas.mnc is created as follows:
As an alternative to using the resampled_atlas and binarizing it, you could also apply the transform directly to the source mask. All of the ex-vivo atlases described in Mouse Brain Atlases have masks (in addition to the average and labels). Eventually, all of the in-vivo brains will have atlases as well.
Step 3: map the mask to native files
In the _processed directory of the quick minctracc registration pipeline you will find a folder belonging to each of your input files. These in turn have folders that contain log files, temporary files, resampled files and transformation files. The transformation that brings files from the final atlas space into native space is simply called ...-to-native.xfm. This is the transformation you will use to map the mask into the native space of your input files. (For more information about bash programming, have a look here: Bash programming)
Step 4: mask out native files
The last thing to do now is to mask out your native files. The example below is only for mouse1.mnc from the example.
Step 5: check the masked files
Make sure that your input files were masked properly. Load them up in any of the visualization programs (OCCIviewer, Display or register) to see that no gross parts were cut out, or big chunks of tissue are still present around the brain. If you do find that that is the case, you should manually adjust the mask for that file in either Amira or Display to get a properly masked file.
Step 6: re-run mincANTS pipeline
You are now ready to rerun your mincANTS pipeline with the masked brains. Make sure you use the -no-inormalize option, because using it on masked brains can potentially flip the contrast in them.
By default there is no resampled atlas
When the Toothless quarantine was created the option -resample-atlas was on by default, meaning that a classified atlas was aligned to your final non-linear average (using the Morris-Water-Mazer (MWM) average mouse brain). We found out however that this procedure does not always created very accurate atlases, so we decided to turn it off by default. You can still run it by specifying the option explicitly, but keep in mind that your labels might not be correct. Check them carefully! (For more information about how to create atlases, look here: Atlas to Atlas Segmentation and here: Mouse Brain Atlases)
Possible issue with lsq12 max pairs
If you are running a study with many subjects (40, 60, 100...) it is not necessary to perform all possible pair-wise affine registrations. This number really blows up, and running all pair-wise registrations won't really give you a different answer. You can set this to 20 in those cases. One note, there is a bug in the code which could cause the program to get in an infinite loop if you set this parameter to a number slightly smaller than the number of samples in your pipeline (e.g., 20 with 22 subjects). In those cases, simply set it to 0, so it will run all possible pairs.
"Remember, a dragon will always, always... go for the kill."