Instructions for template creation and T1 normalization using SPM8 "new segmentation" and "Dartel" (September 27th 2010) Index 1. Introduction and general goal 2. Environment 3. Structure 4. Preparation of the data before running the batch 5. Steps to run the batches 6. Parameters tuning 6.1. To do list 6.2. Parameters 6.3. Main program 7. Where to find it 1. Introduction and general goal The goal of this document is to describe how to use the SPM8 batch system to normalize white and grey matter images by using adapted templates (for children data). First, by using the T1 images and the TOM adapted template (Template O- Matic Toolbox), the grey matter, white matter and CSF images (c1, c2, c3) are obtained, in addition to normalized grey and white matter images (rc1, rc2). Next, a new template is created using Dartel and the normalized grey and white matter images of all our subjects. Finally, all the grey matter, white matter and CSF images (smwc1, smwc2, smwc3) are normalized towards the template created with Dartel. A detailed description of the methods behind the code is not furnished here but the following scheme shows the used algorithm (in French). Only parameter tuning and how to run the program are described in this document.
2. Environment The batch system described here runs on Matlab using SPM8. The programs have been tested on Linux Mandriva 2008 but they should be easily adaptable for Windows or Mac. 3. Structure Any protocol "database" which is going to be processed with this batch system should be organized following the directories structure described here. This is the standardized structure we use. All batches are in directory /mfiles/. This directory contains: - 1 directory /tools/ which contains other useful batches used in the main program - 2 files: startup.m batch to initialize SPM8 and directories paths main_t1_dyslexie.m the main program (which contains all the parameters used and is the one to be executed)
The data must be organized following the directory structure detailed here: myprotocol Tools mfiles main_t1_dyslexie.m startup.m tools all-enfants subject1 t1mri acquisition1 subject2...... 4. Preparation of the data before running the batch In order to get ready to run the batch system, it is necessary to get the data you want to process. You can get the anatomy by using the method described in our wiki: http://www.unicog.org/pm/pmwiki.php/intranet/importingdataacquiredonthesiemenstrio3t http://www.unicog.org/pmwiki/pmwiki.php/main/importingdatafromthesiemenstrio3t (old wiki) or with the "old" manual method described here (only in French): http://www.unicog.org/pmwiki/pmwiki.php/main/tlchargementdesdonnesetleurorganisation There is no DICOM conversion in this batch system. Therefore, get your data in.img/.hdr format (or in.nii format) and put them inside directory /t1mri/acquisition1/. Just before running the batch system, you must have the anatomical data for each subject in their directory: /subject1/t1mri/acquisition1/ (the anatomy.img/.hdr or.nii format) Note: As our children data have already been used, it is possible to import them by using the scripts "loop_import_anat_enfants.sh" and "import_anat_enfants.sh" in: /neurospin/unicog/protocols/irmf/dyslexie_structanal_ghis_2009/vbm/t1- ENFANTS/Tools/scripts/ Then, run the scripts from the command line with:./loop_import_anat_enfants.sh Two new subjects (af080227 et lp090006) have been added with scripts "loop_import_anat_enfants_bis.sh" and "import_anat_enfants_bis.sh" with this command:./loop_import_anat_enfants_bis.sh Getting the TOM template Follow these instructions in order to download and install the "Template O-Matic Toolbox" (TOM toolbox) for the creation of a first template adapted to the ages of our database. a) Installation of the TOM toolbox: - Follow instructions on the TOM description web page:
http://dbm.neuro.uni-jena.de/software/tom/description/ - If you do not have it, install SPM8 (for example with files spm8.zip and spm8_updates_r4010.zip) - Download TOM version for SPM8 from here: https://irc.cchmc.org/software/tom/downloads.php - As described on the TOM description web page, copy TOM8 directory in here: "C:\Program Files\SPM\spm8\toolbox" - Download and decompress NIH data for SPM8 (6 tissues). For example, in here: "D:\Documents and Settings\am985309\Mes documents\my_work_neurospin\from_home\inserm\travail\batches\children_t1_nor malization\tom8_nih" - The toolbox can be used by selecting "TOM8" in the "Toolbox" selector (in the SPM8 interface). b) Creation of the adapted template: - Run the TOM8 toolbox (SPM8 and then select Toolbox: TOM8) and in the "TOM8" menu select "Create new template" - Follow instructions in file "Readme-NIH-Data.txt" (in "C:\Program Files\SPM\spm8\toolbox\TOM8") - Fill in the different fields: Select TOM.mat select the 6 tissues data with file TOM.mat in the data directory: "D:\Documents and Settings\am985309\Mes documents\my_work_neurospin\from_home\inserm\travail\batches\children_t1_nor malization\tom8_nih" Write priors/template as single file or multiple files Priors for SPM8/VBM8 'new segment' (6-volume TPM-file and T1) Select template creation method Average approach (suggested in file "Readme- NIH-Data.txt") [but method "Matched pairs approach" is suggested in article Wilke et al., page 911!!] Age Vector: from file "ALL-age.txt" in: "Z:\protocols\IRMf\Dyslexie_StructAnal_Ghis_2009\VBM\t1-ENFANTS\Tools\agelum" copied here: "D:\Documents and Settings\am985309\Mes documents\my_work_neurospin\from_home\inserm\travail\batches\children_t1_nor malization" and modified (with the help from Matlab for converting from months to years "/12"): ALL-age_avec_sm070193_mois_par_groupes.txt ALL-age_avec_sm070193_mois_ans_tous.txt ALL-age_avec_sm070193_ans_propre_tous.txt
Edit value (copy-paste from file "ALL-age_avec_sm070193_ans_propre_tous.txt") Use gender information None Covariates [vide] Save animated gif-image Transversal slice (in mm) [recommended in file "Readme-NIH-Data.txt"] 60 (middle axial slice) Output Directory "D:\Documents and Settings\am985309\Mes documents\my_work_neurospin\from_home\inserm\travail\batches\children_t1_nor malization\created_tom_template" - Run the batch (green "play" button in the upper part of the window) Created files: T1_Template_Age8.625.hdr/.img T1 image TPM_Age8.625.nii 6 tissues in one only file Note: Conversion (not necessary finally) of TPM_Age8.625.nii to 6 separated files (one for each tissue): AimsFileConvert -i TPM_Age8.625.nii -o TPM_Age8.625.img --output_4d_volumes 0 - Finally, copy the created TOM template in here: /neurospin/unicog/protocols/irmf/dyslexie_structanal_ghis_2009/vbm/t1- ENFANTS/created_TOM_template/ 5. Steps to run the batches 1) Launch Matlab 2) Run SPM8. Once it is running you can exit SPM. 3) Run startup.m batch (in /mfiles/ directory). Note: This two steps are also executed if todo_initializations=1 in the parameters. 4) Adapt file "main_t1_dyslexie.m" to your convenience (see next section for details). 5) Finally run "main_t1_dyslexie.m". 6. Parameters tuning In this section the structure of file "main_t1_dyslexie.m" is explained as well as how to adapt the different parameter in this file. 6.1. To do list Description: In this part, all the possible steps to be computed have to be selected. Here, each variable will switch on or will switch off the different steps. If the value of the variable is 0, then the corresponding step will not be executed. If the value is equal to 1, then the processing will take place.
Note: The flags in capital letters indicate the main steps. The other flags correspond to "sub-steps" inside the main stages. Code/parameter description: % INITIALIZATIONS todo_initializations = 1; Put this flag to 1 in order to initialize the environment. SPM8 and the "startup.m" script will be run from the beginning. If you have already done the initializations once, you can put this value to 0. % T1 NORMALIZATION FOR EACH SUBJECT WITH RESPECT TO T-O-M TEMPLATE -------- TODO_NEW_SEGMENTATION_AND_TOM_NORMALIZATION = 1; This flag switches on the first step containing the "new segmentation" and the normalization with respect to the TOM template. This process allows to compute the segmentation of the T1 images of all the subjects and then the normalization of the grey and white matters towards the TOM template (the created template adapted to the age range of the subjects see section "Preparation of the data before running the batch, Getting the TOM template, b)"-). See the scheme in section "Introduction and general goal". todo_clean_old_results = 0; % 0 = do not remove anything, 1 = remove old results When this flag value is 1, it indicates that, if some old results are found, they will be removed before running the main part of the batch. % CHILDREN TEMPLATE CREATION (WITH DARTEL) -------------------------------- TODO_DARTEL_TEMPLATE_CREATION = 1; This flag switches on the processing for the creation (with Dartel) of a template by using the normalized grey and white matter images from all the subjects. % NORMALIZATION OF ALL THE TISSUE IMAGES WITH RESPECT TO THE MNI TEMPLATE - TODO_NORMALIZATION_TO_MNI = 1; When this flag is switched on, the processing for normalizing towards the created Dartel template (which is an MNI template) all the grey and white matters and CSF images for all the subjects will be performed (c1, c2, c3 smwc1, smwc2, smwc3). 6.2. Parameters Description: In this subsection, the different parameters necessary for the processing are described. Code/parameter description:
tools_path = '/neurospin/unicog/protocols/irmf/dyslexie_structanal_ghis_2009/vbm/t1- ENFANTS'; "tools_path" defines the directory containing the /mfiles/ directory (which contains all the batches and tools for this processing). protocol_path = '/neurospin/unicog/protocols/irmf/dyslexie_structanal_ghis_2009/vbm/t1- ENFANTS'; The parameter "protocol_path" indicates the main directory where the data used in the study are stored. subjects_path = 'all-enfants'; "subjects_path" defines the directory inside "protocol_path" that contains the directories defined by the list of subjects. list_subjects = {'aa080049','ac080056','ag080048'}; "list_subjects" contains the names of the subjects (which are the same as the names of their directories) to be processed. anat_path = 't1mri/acquisition1'; "anat_path" indicates the local directory where the anatomical data are stored for each subject. It contains typically the "t1mri" directory plus the directory of the acquisition (usually "acquisition1" if only one anatomy has been acquired). All this directory structure is necessary for compatibility with BrainVISA software. logfile = 'proc.log'; logfile indicates the name of the.log file generated by the batch. % TOM template % TOM_template = '/neurospin/unicog/protocols/irmf/dyslexie_structanal_ghis_2009/vbm/t1- ENFANTS/created_TOM_template/T1_Template_Age8.625.img'; TOM_template contains the complete path and file name of the created TOM template to be used for the first normalization step. It is not necessary for the processing here. % Tissues du TOM template TOM_tissues = '/neurospin/unicog/protocols/irmf/dyslexie_structanal_ghis_2009/vbm/t1- ENFANTS/created_TOM_template/TPM_Age8.625.nii'; TOM_tissues contains the complete path and file name of the file containing the 6 tissues for the TOM template to be used for the first normalization step. It IS necessary for the processing. % Children template (will be created with our data) template_image_root = 'Template'; template_image_root contains the name root of the children template created with Dartel. children_template_path = fullfile(tools_path,'/mfiles/tools/'); children_template_path contains the complete path of the children template created with Dartel. By default this path is the local directory /mfiles/tools/.
children_template = fullfile(tools_path,'/mfiles/tools/template_6.nii'); children_template contains the complete path and file name of the children template created with Dartel. It will be the output of the second step of the program (children template creation with Dartel) and an input to the final step (normalization towards the MNI of the c1, c2 and c3 images for all the subjects). By default this file is placed in the local directory /mfiles/tools/. 6.3. Main program The rest of file "main_t1_dyslexie.m" contains the code that performs the different stages of the algorithm and should not be modified a priori. 7. Where to find it The batch system described in this document is available in the intranet of NeuroSpin: /neurospin/unicog/resources/matlab_scripts/children_vbm_normalization/ It will probably be downloadable from the Unicog wiki: http://www.unicog.org/pm/pmwiki.php/intranet/fmriscriptsanddocs Copy the.tar file and untar it (for example, in Linux use command tar xvf children_vbm_normalization_mfiles.tar).