MincTools 101
By Etienne Aumont
Based on material provided over the years by Camille Legault-Denis
To better use this guide, I recommend you first get acquainted with the BASH commands first
For further MincTools documentation (syntax, options, etc), I highly recommend visiting the Minc Github
- File format
- Image processing
2.1 Resampling an image
2.2 Image registration - Statistics and calculations + how to use them to create masks
3.1 Image statistics
3.2 Calculating images
3.3 Cluster size thresholding
Before we do anything, if you're working on one of TNL's computers, you will probably need to activate Minc every time you open a session.
source /opt/minc/1.9.18/minc-toolkit-config.sh
#If you're using the Minc VM, change "1.9.18" with "1.9.17"
MincTools is a bioimaging processing software that works with 3D and 4D images in a Minc (.mnc) format. It's designed to be convenient and easy to edit. However, there are many other image formats out there.
- The Nifti (.nii) format is the most widely used in research and it has similar properties to the Minc format.
- The Dicom (.dcm) format is the international standard in radiology, it is mostly used for viewing. A 3D .dcm image is often made out of many files, each representing one slice.
The minc format includes information in a header. You can read the header by using this:
mincheader PETfile.mnc
#This command gives a much simpler output:
mincinfo PETfile.mnc
Most importantly, you will obtain the dimensions in x, y and z and the voxel size. The header also contains information such as the scanner parameters.
Converting files between formats
nii2mnc file.nii new_file.mnc: to create a copy of nii files into mnc. If the scaling of the new image is off, just add the -float option
If you don't have an output file, it will keep the same file name with the new extension. If there is no input or the input is a repository, it will convert all of the images in the current/target repository.
mnc2nii file.nii new_file.mnc: to create a copy of nii files into mnc.
dcm2mnc new_file.mnc: to transform dicom slices into an mnc image.
Convert a 4D image into 3D
Raw PET images are typically 4D images, with one 3D image per time window (e.g. six 5-minutes frames). To average the frames:
mincaverage 4D_image.mnc 3D_avg_image.mnc –avgdim time
Each raw image has its dimensions. To be able to match individual voxels from 2 images, we must resample them. Resampling consists of slicing new voxel limits to fit in the same dimensions as a target image.
For this, we use the mincresample function. for example:
mincresample PETfile.mnc –like T1_MRI.mnc resampled_PET.mnc
The default option it uses is trilinear, which takes the average contribution of every original voxel. For example, if New_voxel1 overlaps 8 old voxels, its value will be the average of all 8 old voxels, weighted for the area they share. One of the 8 could only share a small corner (say 0,5%), while another one could overlap most (say 60%) of the new voxel. The trilinear method is suitable for images where decimals make sense.
To transform a mask file, which is made of integers (generally only 0 and 1), you don't want the values of the new voxels to be an average of the old ones that overlap them. For this, we need the nearest neighbor method, which sets the value of the new voxel at the value of the old voxel that overlaps it the most. For example:
mincresample mask.mnc –like T1_MRI.mnc –nearest mask_in_MRI_space.mnc
The result will be a mask with voxels aligned to the MRI's dimensions.
Resampling is not 100% accurate, and it loses some information. This is why we only do it once on any given image.
To register an image, Minc offers a basic tool with the function minctracc see documentation here
This tool is useful to perform basic image registration such as:
minctracc –nmi –lsq6 PETfile.mnc T1_MRI.mnc output_autoreg.xfm
-nmi is for normalized mutual information, the optimization method to find the best fit between 2 images
-lsq6 is for a rigid-body registrations. It stands for 6 parameters: 3 translations and 3 rotations (x, y and z axes), useful when you want to align 2 images from one participant.
- lsq7 adds a scaling factor if one image is smaller than another.
- lsq9 has different scaling factors for each axies. We call this an affine linear transformation.
- lsq12 adds shearing parameters for a more complex linear transformation. The added dimensions make the process more computer intensive and add some margin for errors.
- Nonlinear transformations (like what ANTS does) are best performed on a dedicated computer, as it takes several hours to calculate as opposed to ~1 to 5 mins for lsq6 to lsq 12.
You may have more than one transformation to do. For example, a linear and a non-linear transformation to transform the native space PET image into a standard space image. For this, you may concatenate (merge) several .xfm transformation files using xfmconcat. For example:
xfmconcat output_autoreg.xfm nonlinear_ANTS_transformation.xfm linear_ANTS_transformation.xfm merged_transformation.xfm
Nonlinear transformations might have other files associated to them (e.g. a grid0 file). You might need to bring these files into the same directory as the final .xfm file for it to work.
The .xfm file is a transformation matrix: you can use it to transform, in this case, any other image from the subject's PET space to the MRI space. The mincresample function allows us to do that simultaneously with the resampling so that it's only done once. For example:
mincresample PETfile.mnc –like T1_MRI.mnc –transform merged_transformation.xfm standard_space_PET.mnc
This will do 2 things to produce the transformed_PET image:
- Apply the .xfm transformation on the PET file
- Resample the PET file
To transform a mask file with a nearest neighbor method:
mincresample mask_in_PET_native_space.mnc –like T1_MRI.mnc –nearest –transform merged_transformation.xfm mask_in_standard_space.mnc
You can also invert the transformation to bring a standard space mask into the native space
mincresample mask_in_standard_space.mnc –like T1_MRI.mnc –nearest -invert_transformation –transform merged_transformation.xfm mask_in_native_space.mnc
While blurring (otherwise known as spatial smoothing) is not necessary to perform region-of-interest analyses, PET images should be blurred before performing voxel-wise analyses. The blurring is done using a gaussian filter that calculates a new value to each voxel based on the values of the voxels around it. The gaussian filter is basically a normal distribution to determine how much smaller a voxel's contribution will be depending on how far from the target voxel it is. You can consider voxels that are further away by using a larger gaussian filter. The size of the filter is defined by its full-width at half maximum (fwhm). For PET, we typically use something that is at least 6 mm, sometimes as high as 10 mm.
To apply this, we use mincblur like this:
mincblur –fwhm 8 input.mnc ouput.mnc
-fwhm 8 means that the gaussian filter has a size of 8 mm fwhm A _blur.mnc is sometimes automatically added to the output name when using for loops, which can be annoying.
The fwhm value might change from one center to another, depending on the PET-scanner's resolution. You might want to calculate the gaussian kernel size needed to obtain the same resolution for images of the two centers. For this, you need an original resolution for each scanner and a target resolution.
Example: I want a resolution of 8 mm fwhm for my PET images. Some are from site 1, which has a native resolution of 2.4 mm fwhm, and some are from site 2, which has a native resolution of 4 mm fwhm
Blur for site 1 images = sqrt(8² - 2.4²)
= sqrt(58.24)
= 7.63 mm
Blur for site 1 images = sqrt(8² - 4²)
= sqrt(48)
= 6.93 mm
I would need to blur images from site 1 at 7.63 mm fwhm, and from site 2 at 6.93 mm fwhm, to obtain a resolution of 8 mm fwhm on all images.
To calculate mean values within a region of interest, we use mincstats
mincstats –mask mask.mnc –mask_binvalue 1 PETfile.mnc –mean
-mask_binvalue is the value of the voxels in your mask. It's generally "1", but if your mask has more than one label, for example, Braak stages, you will need to specify the mask number instead.
You can request several other things apart from the mean, just enter -help to see your options.
Something else that can be useful is obtaining the voxel count of a mask.
mincstats mask.mnc –binvalue 1 -count
It's also possible to obtain statistics about voxels that correspond to a criteria. For example:
mincstats PETfile.mnc -floor 1.5
This will give summary statistics regarding all the voxels that surpass a value of 1.5.
You can also use -ceiling of -range instead.
This can also be done within a masked region.
mincstats PETfile.mnc -floor 1.5 -mask braak_mask.mnc -mask_binvalue 3
This will give me statistics pertaining voxels with a value of > 1.5 within the Braak III region.
When you want to know how similar two images are, you can run minccmp to obtain measures of similarity between the two.
minccmp image1.mnc image2.mnc
We can also modify images by using simple mathematical formulas using the mincmath function. It allows to add, subtract, divide or multiply an image with another image or with a fixed value. For example, if I want to remove all of the voxels outside of the brain, I'd multiply a whole brain mask with an image. The whole brain mask is made of 1s inside the brain, and 0s outside of it, so a multiplication simply nullifies everything outside. Always include -float in mathematical operations to increase precision.
mincmath -float -mult PETfile.mnc mask.mnc masked_PET.mnc
You can use this function to perform many simple operations as well as making boolean tests (i.e. does X voxel fits y criteria?). For example:
mincmath -float -gt -const 1.5 PETfile.mnc PETmask.mnc
-gt stands for greater than. You also have -eq (equal to), -ge (greater or equal to) as well as -lt and -le (lower than and lower or equal to)
The -const option is used when you want to input a number rather than an image file. Here, I wanted to set the threshold at a fixed value of 1.5.
The resulting image will be a mask where all voxels that have a value of 1 have a value > 1.5 in the PET image.
This also works with images:
mincmath -float -gt image1.mnc image2.mnc 2_gt_than_1.mnc
The resulting mask will correspond to voxels where image2 > image1
**Averaging images **
mincmath is limited to simple mathematical operations. You can perform specific operations that are more complex with mincaverage:
mincaverage image1.mnc image2.mnc image3.mnc image4.mnc average_image.mnc -sdfile SD_image.mnc
This will create an average file of all of your images
-sdfile requests to also generate a standard deviation map
We can use all of these functions to select only regions that fit certain criteria as well as being in a sufficiently large cluster. This is particularly useful with statistical t-maps obtained from RMINC or VoxelStats. Here is how it goes:
mincmath -ge -const 1.92 t-map.mnc thresholded_t-map.mnc
#first, we threshold the image
mincmorph -group -3D06 thresholded_t-map.mnc clusters.mnc
#This orders the clusters by size
mincstats -histogram hist.txt -integer_histogram clusters.mnc
#This stores the voxel count of each cluster in a text file. Open it and find the smallest cluster you want to keep
mincmath -le -const [smallest cluster number] clusters.mnc mask.mnc
#Creating a mask that excludes the clusters that are too small
mincmath -mult thresholded_t-map.mnc mask.mnc final_mask.mnc
#To exclude the small clusters from the t-map, we multiply it with the previous mask
The result is a mask that only includes voxels that are both significant and part of a cluster that is large enough.