2016.10.27. I have updated the script.
2016.11.2. I have updated the script again.
2017.4.3. I have updated the script to fit to Windows systems. I apologize the inconvenience so far.
Thank you for coming to this webpage!
This webpage explains my MATLAB code to compute a lateralization index (LI) called AveLI. It is called AveLI because the index is in a sense an average of all lateralization indices within the regions of interest (ROIs).
The code works with files in analyze formats (*.img/hdr, *.nii) employed in SPM software. I confirmed the compatibility with SPM12 and SPM8. I believe SPM5 is also OK. Please let me know if you find any problems. In any way, you have to have SPM in your MATLAB path.
You can download the script (aveli.m) from here. Save the linked file as "aveli.m" in your matlab path.
The rationale for the AveLI is written in the following paper. Thank you for citing.
Matsuo K, Chen SH, Tseng WY. 2012.
AveLI: A robust lateralization index in functional magnetic resonance imaging using unbiased threshold-free computation.
J Neurosci Methods 205(1):119-129.
It's easy. Preparation
Do the first level statistics using the SPM. Then, you will obtain various statistical files by SPM such as spmT_*, con_* and beta_* files. The spmT files contain t-values of the statistics in the voxels. The con files contain contrast estimate values (beta) of the contrast defined. The beta files also contain beta values; but this time, these are only from the original conditions. You can examine the LIs in more sophisticated contrasts using the con files if you specify. Please select among them or others according to your consideration. Here, these files to examine the LIs are called data files.
Prepare left and right ROI (region of interest) masks. You may want to use anatomy template masks by Marina, FreeSurfer and/or WFU PickAtlas toolbox. Needless to say, these masks should be in the same brain space as the data files above (such as the MNI template space after the spatial normalization). Do double-check the left and right orientations of your images.
Type "aveli" on the matlab command line.
Specify data files you want to know the LIs at the pop-up window. You can specify multiple files. Importantly, all data files should have the same voxel dimensions with each other (e.g., 91 x 109 x 91).
Specify the left ROI mask file.
Specify the right ROI mask file. This should be a different file from the left one.
* For the ROI masks, you can only choose 1 file for each side.
The code computes the lateralization indices and reports them on the command lines as well as in a text file saved in the current working directory. The computation may take some time. In particular, if you use larger ROI masks, it may take a long time..
Summary: files to be prepared for AveLI computations
Data files: you can examine multiple files that have the same voxel resolutions in the same brain template space with each other (e.g., 91 x 109 x 91 in the MNI space).
Left and right ROI files: the ROI files should also be in the same brain template space (e.g., MNI). This time, the ROI files can have different voxel resolutions from the data files; the code manages the difference. You may want to prepare binary files; but even when you do not, the code makes new ROI files with the same resolutions to be used. (see below)
You may see something like the following on your monitor:
The warning message in red above says:
Warning: spm_imcalc_ui is deprecated. Use spm_imcalc instead.
> In spm_imcalc_ui at 33
In aveli at 150
This may occur when the AveLI script uses spm_imcalc_ui in SPM8. SPM12 quit to use this function now. Thus, I switched to use spm_imcalc in that case (updated 2016.10.27.)
You may see warning messages like the following:
The messages come from the SPM ImCalc (image calculator) code. Just in case, I perform the ImCalc to make new ROI binary masks that have the same resolution with the data files.
You will see the warning message if the image types are different between data files and ROI files. For example, you may have con_* files of float32 and ROI files of unit8. Or, your con_* files may have a resolution of 121 x 145 x 121 and your ROI files may have another resolution of 91 x 109 x 91. In these cases, the ImCalc code shows the messages, warning the existence of the difference between the files. The code generates new ROI files with the resolution of 121 x 145 x 121 in this case. Technically, the type of the new files is int16; I used the nearest neighbor method for the interpolation according to the ImCalc default setting and a cut-off threshold of 0.5. The same extension with the original ROI file is used (i.e., .nii or .img/hdr).
In many cases, you do not have to worry about them. The new ROI files generated will be saved in the current directory.
After the execution, you will find new files in the current directory. (You may want to make a directory (folder) first and then run aveli inside the directory.)
You can first find the AveLI value(s) on the MATLAB command lines.
In this example, the second session has an NaN for the AveLI. NaN means "not a number". The NaN most likely occurs when the ROIs contain no positive values in the voxels in the data files. For example, in many cases, the lateral parietal cortex around the angular gyrus shows negative beta values during language tasks, as it belongs to the default mode network (DMN). In such a case, the AveLI shows NaN. This is because that the AveLI computation only uses positive values in data files.
The saved text file (AveLI_*date_time*.txt file) shows information similar to the results shown on the monitor but more detailed such as follows:
You can import it into Microsoft Excel if you like (tab separation).
You may want to compare the AveLI values with classical LIs of supra-threshold voxel numbers. You can obtain ones as follows:
Perform the SPM statistics using the threshold you prefer.
Save the results map using the "thresholded SPM" option.
Run the aveli code by specifying the saved map as a data file.
In the results, baseLI(voxel) indicates the simple voxel number LI, i.e., (left voxel number - right voxel number) / (left voxel number + right voxel number).
I am thinking of adding an option that uses representative voxels within the ROIs in order to shorten the computation time when larger ROIs are used (such as the whole hemispheres). Not to be missed!
I really owe this work to Joyce of Max-Planck-Institut for her extensive corporation to test the previous and current versions of the code. I'd also like to show my gratitude to my former colleagues in Taiwan for their kind understanding to the work. I am also thankful to the supports by my current colleagues here in Hamamatsu University School of Medicine, Japan.