Hm toothless. I could have sworn you had.... teeth

Details

What's new?

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:

> MICe-build-model.pl -nlin-registration-method mincANTS {other options} mouse_1.mnc mouse_2.mnc ...

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:

1. Perform a rough/quick registration
   
   1. using minctracc
   2. using mincANTS with more regularization on the deformation fields
   3. using MAGeT
2. Create a mask for the final average of this registration pipeline
   1. atlas_to_atlas
   2. mincANTS
3. Map the mask back to the native files and
4. Mask them out
5. Check masked files
6. Rerun mincANTS pipeline

Step 1a: rough/quick registration using minctracc

Below is the command you can use to run a quick minctracc registration. The -nlin-partial argument will only perform 2 non linear stages.

> MICe-build-model.pl -nlin-registration-method minctracc -nlin-partial -pipeline-name quick_minctracc {other options} mouse_1.mnc mouse_2.mnc ..

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.

> MICe-build-model.pl -nlin-registration-method mincANTS -nlin-protocol /projects/mice/share/arch/linux-x86_64-eglibc2_11_1/bin/mincANTS_protocol_regularization_on_def_field.pl -pipeline-name conservative_mincANTS {other options} mouse_1.mnc mouse_2.mnc ..

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:

> MAGeT.py --mask-only --masking-method=mincANTS --atlas-library=/projects/mice/userid/directory_with_atlases --output-dir=MAGeT_for_masking {other options such as --sge etc.} mouse_1.mnc mouse_2.mnc ...

Step 2: create a mask for the final average

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

# general call:
> mincANTS 3 -m CC[source.mnc,target.mnc,1,3] -m CC[source_dxyz.mnc,target_dxyz.mnc,1,3] -i 100x100x100x100 -x source_mask.mnc -t SyN[0.4] -r Gauss[1,6] -o mincANTS_transform_for_mask.xfm --number-of-affine-iterations 0

# specific call for:
# -VVW Sert atlas (source) (56 micron)
# -nlin-3.mnc (target from a regularized mincANTS pipeline) (56 micron)
> mincblur -no_apodize -gradient -fwhm 0.056 nlin-3.mnc nlin-3_fwhm_0.056
> mincblur -no_apodize -gradient -fwhm 0.056 VVW_Sert_version_1_average.mnc VVW_Sert_version_1_average_fwhm_0.056
> mincANTS 3 -m CC[VVW_Sert_version_1_average.mnc,nlin-3.mnc,1,3] -m CC[VVW_Sert_version_1_average_fwhm_0.056_dxyz.mnc,nlin-3_fwhm_0.056_dxyz.mnc,1,3] -i 100x100x100x100 -x VVW_Sert_version_1_mask.mnc -t SyN[0.4] -r Gauss[1,6] -o mincANTS_transform_for_mask.xfm --number-of-affine-iterations 0

In this case, the resampled_atlas.mnc is created as follows:

# general call:
> mincresample -like your-nlin-image.mnc -keep_real_range -nearest_neighbour -transform mincANTS_transform_for_mask.xfm source_labels.mnc resampled_atlas.mnc

# specific call for:
# -VVW Sert atlas (source) (56 micron)
# -nlin-3.mnc (target from a regularized mincANTS pipeline) (56 micron)
> mincresample -like nlin-3.mnc -keep_real_range -nearest_neighbour -transform mincANTS_transform_for_mask.xfm VVW_Sert_version_1_labels.mnc resampled_atlas.mnc

#Next you will have to binarize the label file, and fill the holes in it to get the actual mask:
> mincmorph -successive B[0.5:999]DDDDDDDDEEEEEE resampled_atlas.mnc mask_for_nlin2.mnc

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.

#general call
mincresample -like your-nlin-image.mnc -keep_real_range -nearest_neighbour -transform mincANTS_transform_for_mask.xfm source_mask.mnc mask_for_your_nlin_image.mnc

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)

# Assuming the following directory structure:
#
# native_files/
# quick_minctracc_lsq12/
# quick_minctracc_lsq6/
# quick_minctracc_nlin/
# quick_minctracc_processed/
#
# With the following samples in your pipeline:
#
# mouse1/
# mouse2/
# mouse3/
# mouse4
#
# Run the following for a single file (mouse1)
#
> cd quick_minctracc_processed
> mincresample -like ../native_files/mouse1.mnc -transform mouse1/transforms/mouse1-to-native.xfm -nearest_neighbour mask_for_nlin2.mnc mouse1_mask.mnc

#
# Run the following for all files in a for loop in bash:
#
> cd quick_minctracc_processed
> for file in *; do mincresample -like ../native_files/${file}.mnc -transform ${file}/transforms/${file}-to-native.xfm -nearest_neighbour mask_for_nlin2.mnc ${file}_mask.mnc; done

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.

> mincmath -mult ../native_files/mouse1.mnc mouse1_mask.mnc ../native_files/mouse1_masked.mnc

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.

> MICe-build-model.pl -nlin-registration-method mincANTS -no-inormalize {other options} mouse_1_masked.mnc mouse_2_masked.mnc ...

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."