Instructions for FA normalization (April 15th 2010)

Transcription

1 Instructions for FA normalization (April 15th 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 batch system to normalize DTI images. 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 2. Environment The batch system described here runs on Matlab using SPM5. 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 SPM5 and directories paths main_dti_dyslexie_simple.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_dti_dyslexie_simple.m startup.m tools Subjects subject1 t1mri acquisition1... dti..._fa.*..._t2_diffusion.* original..._adc.*..._fa.*..._lpara.*..._lperp.*..._t2_diffusion.* subject

3 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: or with the "old" manual method described here (only in French): You may get your anatomical data directly in DICOM format. Put them (in DICOM or.img/.hdr format) inside directory /t1mri/acquisition1/. Your DTI data (preferably already corrected and in.ima/.dim format) should be placed inside directory /original/. Thus, just before running the batch system, you must have some data in three directories: /subject1/t1mri/acquisition1/ (the anatomy DICOM or.img/.hdr format) /subject1/original/ (original DTI images and results of the processing.ima/.dim format) /subject1/dti/ (DTI images that may be modified by the batch may be empty at the beginning) Important: Before running the batch and to avoid problems with the conversion (AimsFileConvert), be sure that your configuration file ".aimsrc" contains these parameters (specially the last two of them): attributes = { ' syntax ' : 'aims_settings', 'spm_input_spm2_normalization' : 1, 'spm_output_spm2_normalization' : 1, 'spm_output_4d_volumes' : 1, 'nifti_output_4d_volumes' : 1, 'spm_input_radio_convention' : 1, 'spm_output_radio_convention' : 1, } 5. Steps to run the batches 1) Launch Matlab 2) Run SPM5. 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_dti_dyslexie_simple.m" to your convenience (see next section for details). 5) Finally run "main_dti_dyslexie_simple.m". 6. Parameters tuning In this section the structure of file "main_dti_dyslexie_simple.m" is explained as well as how to adapt the different parameter in this file 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

4 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. SPM5 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. % FA NORMALIZATION FOR EACH SUBJECT TODO_FA_NORMALIZATION_T1 = 1; This flag switches on the first step of the DTI normalization process. It consists in normalizing the FA images of each subject with respect to a T1 template. 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. todo_convert_and_remove_dicoms = 0; % 0 = keep them in a "dicom" directory, 1 = remove them If this flag is switched on (value 1), the program will search for DICOM files and they will be converted do NifTI format. The initial DICOM files will be removed after conversion. If this flag value is 0, the DICOM files will be conserved in a directory called "dicom". todo_rename = 0; With this flat switched on, the initial NifTI files of the anatomical images will be renamed by using the value of variable "origin_name" detailed in subsection "Parameters". todo_t1_normalization = 1; todo_t2_fa_coregister = 1; todo_apply_normalization_to_fa = 1; These three flags indicate that the three different steps of the individual FA normalization has to be done: T1 normalization (in this case towards a children template), T2 and FA images coregistration towards the T1 original anatomy and finally application of the normalization to the coregistered FA using the transformation computed for the T1 normalization. % FA TEMPLATE CREATION TODO_FA_TEMPLATE_CREATION = 1;

5 This flag switches on the processing for the creation of a FA template by using the normalized FA for all the subjects. % NORMALIZATION OF ALL THE DTI IMAGES WITH RESPECT TO THE FA TEMPLATE TODO_ALL_DTI_NORMALIZATION = 1; When this flag is switched on the processing for normalizing (towards the created FA template) ALL the DTI images for ALL the subjects will be performed. Here the DTI images are: FA, ADC, lpara, lperp. todo_fa_normalization = 1; todo_apply_normalization_to_other_dti = 1; todo_smoothing_dti = 1; todo_rename_smoothed_dti = 1; These flags switch on the following steps of the normalization the DTI images: todo_fa_normalization normalization of the FA image of the subject towards the FA template created in the previous step todo_apply_normalization_to_other_dti application of the normalization of the FA to the other DTI images (ADC, lpara, lperp) todo_smoothing_dti smoothing of all the DTI images todo_rename_smoothed_dti renaming of the smoothed images so that the prefix contains the size of the smoothing kernel (parameter "dti_smoothing" commented in next section) 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/antoinette/ fa-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/antoinette/ fa-enfants'; The parameter "protocol_path" indicates the main directory where the data used in the study are stored. subjects_path = 'data-grands-lecteurs/lecteurs'; "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.

6 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. modality = 'dti'; "modality" indicates the directory containing the DTI images that could be modified by the batch processing (FA and T2). Typically it is "dti". dti_original_path = 'original'; "dti_original_path" indicates the directory containing all the DTI images of the subject (ADC, FA, lpara, lperp, T2). This directory will also contain the resulting images (normalized and smoothed). fawc = 'fa\.img$'; adcwc = 'adc\.img$'; lparawc = 'lpara\.img$'; lperpwc = 'lperp\.img$'; norm_fawc = '^w.*fa\.img$'; These five variables are the "filters" to select the corresponding images: fawc select FA images adcwc select ADC images lparawc select lpara images lperpwc select lperp images norm_fawc select normalized FA images For more information about this kind of "filters", you can type "help regexp" in Matlab. list_acquisitions = {''}; "list_acquisitions" contains the list of directories corresponding to different DTI acquisitions. Here, we have let this variable empty because the data are directly in directory "dti" (variable "modality"). For other cases, the typical value of this variable would be, for example: list_acquisitions = {'acquisition1'}; All this directory structure is necessary for compatibility with BrainVISA software. % Select the origin of the data (for renaming) origin_name = '3T_neurospin'; "origin_name" contains the list of characters that will be used for renaming the files and it indicates the origin of the data. % Smoothing kernel size (mm) dti_smoothing = 8; dti_smoothing indicates the size (in millimetres) of the smoothing kernel used to perform the smoothing of the normalized DTI images (which will create images sw*). The value of this variable will also be used in the last renaming step (if todo_rename_smoothed_dti is equal to 1) in order to rename the smoothed images so that they contain the value of the smoothing kernel. This will produce files named s8w* if the size of the smoothing kernel is 8 mm, s10w* if the size of the kernel is 10 mm, etc. logfile = 'proc.log';

7 logfile indicates the name of the.log file generated by the batch. children_template = '/neurospin/unicog/protocols/irmf/dyslexie_structanal_ghis_2009/template_me an_giovanni/children templates/ourtemplate/giovannitemplate.img'; children_template contains the complete path and file name of the T1 template to be used for the normalization. In this example, it is a children template. % Pour faire une bonne conversion.ima -->.img minf_model = fullfile(tools_path,'/mfiles/tools/model.minf'); minf_model contains the complete path and file name of a.minf file which is necessary for a correct conversion ".ima.img" of the T2 images. This file should be furnished within the package (by default in the local directory /mfiles/tools/). fa_template = fullfile(tools_path,'/mfiles/tools/fa_template.img'); fa_template contains the complete path and file name of the FA template. It will be the output of the first step of the program (FA template creation) and an input to the final step (normalization of the DTI images for all the subjects). By default this file is placed in the local directory /mfiles/tools/ Main program The rest of file "main_dti_dyslexie_simple.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/fa_normalization/ It will probably be downloadable from the Unicog wiki: Copy the.tar file and untar it (for example, in Linux use command tar xvf fa_normalization_mfiles.tar).