Utilities for Data Processing
We share a set of matlab scripts that may help the researchers to process the data generated by BrainSuite.
WARNING: These scripts have not been thoroughly tested and are made available as they are. Please use at your own risk. These scripts are developed using Matlab2012a.
Please feel free to send your feedback to me. (Anand Joshi: email: ajoshi@sipi.usc.edu )
Contents:
1. Smoothing functions on surfaces (main_smooth_func.m)
2. Group differences: ROIwise and pointwise (main_grp_diff_ptwise.m, main_grp_diff_roiwise.m)
3. Inverting the volumetric map (main_inv_map.m)
4. Regenerating stats file after manual corrections to the label file (main_manual_roi_corr.m)
5. Labeling of surfaces and volumes based on manually drawn cortical ROIs (main_sulci_surf_corr.m)
6. Computing surface and volume stats for arbitrary ROIs.
7. Create a new atlas for using with svreg (svreg_make_atlas).
8. Smooth surface function (svreg_smooth_surf_function).
1. Smoothing Functions on the surfaces
This function allows us to smooth surface valued data with respect to the geometry of the surface. There are two types of smoothing parameters, laplacian regularization and gradient regularization. The function can also perform anisotropic smoothing with respect to the cortex. function fs=smooth_surf_function(s,f,sl,sg,[anisotropy],[normalize])s: patch surface structure as is typically generated by readdfs functionf: a function specified on the surface as specified by Nx1 arraysl: is an Laplacian based regularizationsq: gradient based regularizationfs: smoothed functionanisotropy [optional]: Nx1 anisotropy terms if we want anisotropic smoothingnormalize: 1 if we want the smoothed function to integrate to the same as original unsmoothed functionf=smooth_surf_function(s,s.attributes,3.1,3.1).
A sample example usage is shown in main_smooth_func.m
2. Group Differences
2a. ROIwise group differences
We provide a sample script that performs a ROIwise group differences. We assume that the brainsuite and svreg sequences have been run on all the subjects in the two groups. Each subject is in its own subdirectory and inside its group directory.
A sample example usage is shown in main_grp_diff_roiwise.m
2b. Vertexwise group differences
We provide a sample script that performs a group differences, per vertex, of cortical feature such as curvature, thickness, etc. We assume that the brainsuite and svreg sequences have been run on all the subjects in the two groups. Each subject is in its own subdirectory and inside its group directory. Currently the script is set up for thickness differences.
A sample example usage is shown in main_grp_diff_piwise.m
3. Invert volumetric map from subject to atlas
By defaults, svreg computes a map from subject to atlas. Oftentimes, we need a map from atlas to subject. This can be done by using invert map computation. Here is a function for this task.inv_subject_map (subbasename, atlasbasename). The filenames and paths in this function need to be adjusted to work for your configuration.
A sample example usage is shown in main_inv_map.m.
4. Regenerate stats file after manual corrections are done on the volume labels.
Manual corrections can be made to svreg generated labels <subbasename. .svreg.corr.label.nii.gz> with the label painter tool on the BrainSuite GUI interface. http://brainsuite.org/delineation/roi/label-painter-tool/ It assumes that the corrected volumetric labels are stored in [subbasename,'.svreg.corr.manual.label.nii.gz']. Surfaces can be relabeled according to edited labels for the labels which are edited, and then volumetric and suface based statistics can be recomputed using the following function: manual_correct_rois_stats(subbasename).
A sample example of usage is shown in main_manual_roi_corr.m
5. Labeling of surfaces and volumes based on manually drawn cortical ROIs
ROI’s can be manually edited on the midcortical surface generated by SVReg by drawing a sulci that encircles the entire ROI visible on the midcortical surface. The start and stop point of the sulci should be as close as possible and saved as <subbasename. %%% .dfc> where %%% is the 3 digit ID that is assigned to a particular ROI found in the xml file: brainsuite_labeldescription.xml (located in the atlas folder or your SVReg output folder) or the label painter tool in the BrainSuite GUI interface. If the sulci does not fully enclose the whole ROI, the tool will enclose the sulci by finding the shortest path. Vertices enclosed by the sulci are relabeled according to the ROI ID number designated and unlabeled vertices are relabeled by nearest neighbor. After which the labels are transferred to inner and pial surfaces. Surfaces are saved with the extension <.cortex.svreg.surf_corr.dfs> Volume labels are then relabeled according to corrections made on the surface and saved as <subbasename.svreg.corr.surf_corr.label.nii.gz>. Multiple ROI’s can be corrected on each run but each sulci must be saved separately with corresponding ROI ID’s . Sulci must be placed in the SVReg output folder that is used as your input directory.
A sample is shown in main_sulci_surf_corr.m
6. Computing surface and volume stats for arbitrary ROIs
The script for calculating statistics for manually generated or edited ROIs. The script allows full control of the inputs including ROI numbers, names of volumetric and surface label files as well as output names.
A sample usage is shown in main_generate_stats_xls_manual.m.
7. Create a new atlas for svreg and BrainSuite
This function prepares a new atlas from a given subject. Please use the binary that is available for download from the link above. Users can create their own atlas and then use with SVReg. To create a new atlas, the function takes two arguments: subbasename and atlasbasename. subbasename is the new atlas that we want to create. We assume that the subject specified in subbasename is processed using brainsuite and svreg. atlasbasename is the atlas from BrainSuite that was used to process this subject. This is required in order for the script to copy a few files (.xml,.mat) into the new subject’s directory. If you want to perform manual editing of the labels, then please edit subbasename.svreg.label.nii.gz before running the script.
The subject directory is updated with all the files and subbasename now can be used as a new atlasbasename in svreg execution.
Usage: svreg_make_atlas.exe subbasename atlasbasename flag
Input Files Required:
- subbasename: File prefix of the subject that you want to convert into atlas.
atlasbasename: atlas from BrainSuite that was used to process this subject.
flag: -E means volumetric labels are manually edited.
8. Smoothing function on surface
Performs smoothing of a surface based function.Note: This binary is not included in the current public release of BrainSuite, but will be included in the next release. It is available upon request.This function is used to smooth function defined on surface, such as cortical thickness or curvature. Surface based smoothing is typically required for compensating for the results of mis-registration.This function prepares a new atlas from Please use the binary that is available for download.
Results: The output dfs file contains smoothed function and also the surface on which the function was smoothed.
Usage: svreg_smooth_surf_function.exe in_surf func_surf out_surf param (optional)
Input files required: input_surf.dfs: This is the surface on which smoothing will be performed.input_surf_function.dfs: .attributes field of this file contains the function on the input surface. The input_surf.dfs and input_surf_function.dfs could be same.output_surf.dfs: This is the output surface file that contains smoothed function in the attributes field.param (optional): This parameter contains smoothing parameter roughly, kernel fwhm in mm. Default value is 10