Generic batch description (last update April 12th 2010)

Transcription

1 Generic batch description (last update April 12th 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 for the preparation of the data 6.3. Parameters for the preprocessing 6.4. Parameters for the preprocessing quality check 6.5. Parameters for the first level analysis 6.6. Parameters for the contrasts summary sheets 6.7. Parameters for the stanplot step 7. How to run the batch in 5 minutes 8. Coming improvements 9. Where to find it 1. Introduction and general goal The goal of this document is to describe how to use the general batch system, used in INSERM U562/U992, which runs a standardized processing for functional (fmri) and anatomical (T1 MRI) images. A detailed description of the methods behind the code is not furnished here. For further information about the statistical methods, go and see SPM documentation. 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 SPM5. New versions for SPM8 are envisaged. 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: - 5 directories: lcogn_preproc: contains programs for the preprocessing lcogn_firstlevel: contains all programs for the first level analysis

2 lcogn_secondlevel: contains the batches for second level analysis ArtRepair: contains batches for the "artifact repair" step tools: contains other useful batches used in the main program - 4 files: startup.m batch to initialize SPM5 and directories paths parameters_main.m file containing all the parameters used by "main.m" main.m the main program (the one to be executed) README.txt file containing practical information as well as a summary of file organization In the "README.txt" file is described how the data must be organized. Pay special attention to the structure of the data: Laboratoire de NeuroImagerie Cognitive (LCOGN): =============================================== INSERM U562 / NeuroSpin CEA/DSV/I2BM Batch system for SPM5 ( INSTALLATION: Copy all batch files in a 'mfiles' directory in your study hierarchy: myprotocol Tools mfiles main.m parameters_main.m startup.m README.txt ArtRepair lcogn_preproc lcogn_firstlevel lcogn_secondlevel tools Subjects subject1 t1mri acquisition1 analysis spm_segmentation acquisition2... fmri acquisition1 session1 session2... analysis subject_parameters stats_mymodel1 stats_mymodel2... acquisition2... subject QualityCheck_files (automatically created) ArtRepairFiles (automatically created) ContrastsSummary (automatically created)

3 GroupAnalysis (automatically created) stats_mymodel (automatically created) RFX_Activation (automatically created) RFX_Asymmetry (automatically created) From there, run 'main' Matlab command. >> main Note: The command 'startup' setups paths for the system of batch and checks SPM installation. This batch system allows to perform 3 kinds of jobs: preprocessing, first level analyses, and second level analyses. IMPORTANT FOR FIRST LEVEL ANALYSIS: You need to adapt the two functions 'specif_model.m' and 'specif_contrasts.m' to specify your model and contrasts. 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 them by using the method described in our wiki: or with the "old" manual method described here (only in French): You may get your data directly in DICOM format, and you have to organize them as described in the previous section. Thus, just before running the batch system, you must have at least some data in two directories: /subject1/t1mri/acquisition1/ (the anatomy) /subject1/fmri/acquisition1/my_session1/ (one functional session) But check that you have filled in all the directories if you have several sessions in your study. 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 parameters_main.m file. 4) Adapt file "parameters_main.m" to your convenience (see next section for details). 5) Finally run "main.m". 6. Parameters tuning In this section the structure of file "parameters_main.m" is explained as well as how to adapt the different parameter in this file.

4 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. 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. % PREPARATION OF THE DATA 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 = 1; % 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 = 1; With this flat switched on, the initial NifTI files will be renamed by using the values of variables "origin_name" and "study_name" detailed at the end of subsection "Parameters for the preparation of the data". % PREPROCESSING todo_preprocessing = 1; This flag indicates whether the preprocessing has to be done. For details about the parameters to fill for this processing, go and see subsection "Parameters for the preprocessing". You can check the "main.m" file in order to check the preprocessing that will be computed. % QUALITY CHECK OF THE PREPROCESSING todo_artrepair_diagnosis = 1; This flag switches on the "artifact repair" quality check processing. Be careful: if there is no realignment preprocessing this step has no sense! For details about the parameters to fill for this processing, go and see subsection "Parameters for the preprocessing quality check".

5 % FIRST LEVEL ANALYSIS todo_firstlevelprocessing = 1; This flag indicates whether the first level processing has to be done. For details about the parameters to fill for this processing, go and see subsection "Parameters for the first level analysis". You can check the "main.m" file in order to check the first level processing that will be computed. % POST-PROCESSING todo_smooth_con = 1; todo_smooth_gmwm = 1; todo_symmetry = 1; todo_segm_postproc = 1; todo_remove_nan = 1; These flags switch on the following post-processing: todo_smooth_con smoothing of the contrasts todo_smooth_gmwm smoothing of the gray and white matters todo_symmetry computation of the symmetry images (symmetrical images and difference between the original and the symmetrical image) todo_segm_postproc reorganization of the gray and white matter files todo_remove_nan removes values "nan" (not-a-number) in the voxels of the images % QUALITY CHECK OF THE FIRST LEVEL ANALYSIS todo_contrastssummary = 1; This flag switches on the processing that generates the summary sheets which are useful as quality check of the first level processing. For details about the parameters to fill for this processing, go and see subsection "Parameters for the contrasts summary sheets". todo_stanplot = 0; This flag indicates if the "stanplot" quality check has to be computed. For details about the parameters to fill for this processing, go and see subsection "Parameters for the stanplot step". % RFX ANALYSIS todo_rfxanalysis_on_epi= 0; todo_rfxanalysis_on_asymmetry= 0; These flags indicate if the indicated "random effect" analysis has to be computed Parameters for the preparation of the data Description: In this subsection, the parameters for the preparation of the data are described. These steps consist in defining the directories where the data are placed and the names of the input and output files. Code/parameter description:

6 todo_rename_with_subject_name = 1; This is a flag that indicates whether the name of the subject has to be included or not in the file names. In order to avoid confusion between files, we recommend letting this flat to value 1. protocol = '/neurospin/unicog/protocols/irmf/maindatabaselocalizers_pinelmoreno_2008'; [5_min_run] The parameter "protocol_path" indicates the main directory where all the data and tools used in the study are stored. list_subjects = {'subject1','pn071234'}; [5_min_run] "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. anatwc = '^anat.*\.img$'; "anatwc" is the filter to find the anatomical data. In this example the file.img starting with "anat" will be selected. modality = 'fmri'; "modality" indicates the directory containing the functional data. Typically it is "fmri". list_acquisitions = {'acquisition1'}; "list_acquisitions" contains the list of directories corresponding to different functional acquisitions. Typically there is only one acquisition ("acquisition1"). All this directory structure is required for compatibility with BrainVISA software. list_sessions = {'audio1','audio2','audio3','visu1','visu2'}; [5_min_run] "list_sessions" contains the list of functional sessions (also called "blocks" or "runs") of the study. Another example of a list of sessions could be this (for "localizer" protocol there is only one session): list_sessions = {'localizer'}; origin_name = '3T_neurospin'; study_name = 'illiterates_3t_neurospin'; [5_min_run] "origin_name" and "study_name" are variables containing the lists of characters that will be used for renaming the files. "origin_name" must contain a string indicating the origin of the data and "study_name" the something related to the title of the study.

7 6.3. Parameters for the preprocessing Description: In this subsection the parameters to be tuned in order to run the preprocessing are described. Code/parameter description: TR = 2.4; [5_min_run] TR is the repetition time. You must write here the repetition time used for your acquisitions. todo_distorsion_correction = 0; todo_distortion_correction is a flag that, when switched on (=1), indicates that the preprocessing of distortion correction has to be computed, by using the B0 map acquisitions. In this case, the following directory names have to be declared (otherwise, they are not required): b0map_directory = 'b0map'; b0map_mag_dir = 'mag'; b0map_phase_dir = 'phase'; b0map_directory will contain two other directories with the B0 map images: mag containing the magnitude images and phase the phase images. In the case that distortion correction is going to be computed, some other parameters are necessary: TE1_ms = 10; TE2_ms = 12.46; Enter short and long TE values from FieldMap sequence: typically 10 and ms for the standard 3x3x3 mm 3 protocol (their absolute values do not matter; only their difference does; yet you have to enter two TE values). EPI_readout_time_ms = 30.72; Enter the total EPI 1 readout time as the product of the number of lines read per slice (typically 64 for EPI 3x3x3) times the inter-echo time between the reading of lines (typically 0.48 ms appears in the sequence tab, as écart écho ), i.e. EPI readout time = 64x0.48 = ms. Thank you to Alexis Amadon for having developed the distortion correction code. He has also furnished a document with more details (EPI_distortion_corrections.doc/.pdf). The following two parameters are related to the acquired slices: slice_order = 'sequential_ascending'; [5_min_run] slice_order indicates the order of the acquisition of the slices. 1 EPI = echo-planar imaging

8 ref_slice = 1; [5_min_run] ref_slice indicates the reference slice. When the slice order is interleaved, it is better to use the middle slice as reference (typically ref_slice = 18). Otherwise the first slice can be used. voxelsize = [3 3 3]; [5_min_run] voxelsize indicates the size of the voxel of the resulting imaging (the output). The voxel size of the input images (the original ones) is detected automatically. The following smoothing parameters are directly related to this voxel size: smoothing = 5; con_smoothing = 8; [5_min_run] smoothing indicates the size of the smoothing performed on the EPI images (which will create images swastudyname_). con_smoothing indicates the size of the smoothing performed on the contrasts images (which will create images scon_ from images con_). 5 and 8 mm are the typical and general values because: 5 mm intra-subject allows the data to obey the theory of Gaussian fields, without losing too much resolution; 8 mm inter-subject allows to compensate inter-subject variability, i.e. it allows activations to overlap from one subject to another. gmwm_smoothing = 3; gmwm_smoothing indicates the size of the smoothing of the grey and white matters. todo_normalization = 1; [5_min_run] todo_normalization is a flag that indicates whether the images have to be normalized or not. Thus, it is possible to avoid doing the normalization in the preprocessing by letting todo_normalization = 0. todo_normalizationont1template = 1; [5_min_run] If todo_normalizationont1template is switched on (=1) then the normalization is performed related to the SPM T1 template. Otherwise, an EPI template may be used and it has to be defined by EPItemplate, as for example: EPItemplate = '/neurospin/unicog/protocols/irmf/maindatabaselocalizers_pinelmoreno_2008/t ools/template/sym_mean10twinsepi.img'; 6.4. Parameters for the preprocessing quality check Description:

9 In this subsection are described the parameters to be tuned for the quality check of the preprocessing, the artifact repair, which tries to repair the excess of movement of the subject. Code/parameter description: ArtRepair_mvt_thr = 0.5; ArtRepair_mvt_thr indicates the threshold for detecting abnormal variation of BOLD intensity (artifact, fast movement, bad reconstruction...). The following lines define, if the artifact repair step is switched on, the list of images ( list_ima ) to be analyzed. This variable "list_ima" contains the beginning of native EPIs names of each block. if todo_artrepair_diagnosis for i=1:length(list_sessions) list_ima{i} = study_name; end else % if we name the images "by hand" list_ima = {'cat','par','lan','cat','par','lan'}; end list_ima (beginning of native EPIs names of each block) can also be defined manually if the images have not been renamed automatically by the batch system. Be careful: the number of elements in "list_ima" must be the same as in "list_sessions". Thank you to Philippe Pinel who has developed this quality check step! 6.5. Parameters for the first level analysis Description: Here only the name of the model used in the first level analysis has to be defined. It will be the name of the directory containing the first level results too. Code/parameter description: list_modelname = {'mymodel'}; list_modelname defines the directory where the results of the first level analysis will be stored. In section Structure you can see where in the directory organization this directory will be (stats_mymodeln) Parameters for the contrasts summary sheets Description: If this stage is performed, one summary sheet will be created for each subject (in.pdf format in local directory /fmri/acquisitionn/ in each subject folder and in.tif format in the global directory /QualityCheck_files/ContrastsSummary/ in the database folder). These sheets contain some images and graphics which allow to verify the correct processing of the data. Here there is a description of a summary sheet: - Title: subject name and directory of the data

10 - Superior half of the sheet: 6 selected contrasts on transparent brains in order to check that the first level processing has been correctly performed and that there has not been any stimulation problem (i.e. audio problem, stimuli not visible ). For each contrast it is displayed: The corresponding title (specified in variable "contrasts_names" see parameters description below ). The transparent brain (MIP = maximum intensity projection) of the contrast. On the right bottom area, the number of "active" voxels in the ROI corresponding to this contrast is indicated, i.e. the number of voxels containing a value higher than the T-value "threshold" (see variables description below). There is also the mean value of the number of "active" voxels in the ROI of this contrast and the standard deviation for the group of subjects (all the subjects in directory Subjects of the protocol or subjects in "list_subjects"). Finally, you can find either "Conclusion OK", if the quality criterion is verified, or "Conclusion NOK" (in red bold), if it is not. The quality criterion is defined as follows: the contrast is not good if the number of "active" voxels is inferior to 10% of the mean for the group. 1 axial slice of one symmetrized contrast in order to verity that the symmetry processing has been correctly computed. 1 EPI sagittal slice for checking the normalization of the functional images. 1 anatomical (sagittal) slice for checking the normalization of the anatomy. - Inferior half of the sheet: the movement curves (translation and rotation). Left hand side: movement curves for the three dimensions of the translation (x, y, z) and for the three dimensions of the rotation (pitch, roll, yaw). The values in the ordinate axis are fixed between -4 and +4 millimeters for translation and between -4 and +4 degrees for rotation. Right hand side: amplitude values (max min) for the different dimensions of the translation and the rotation. - Inferior part: summary of the sheet. The score indicates the number of contrasts which have "Conclusion OK" with respect to the total number of shown contrasts (6). Code/parameter description: - "To do list": todo_allsubjects = 1; "todo_allsubjects" is a flag that should be put to 1 if you want to compute the summary sheets for ALL the subjects on your "database". If, on the contrary, you prefer to compute the sheets only for a set of subjects, this flag should be equal to 0. In this case, the sheet will be computed for the list of subjects specified by list_subjects. todo_computemeanvalues = 1; "todo_computemeanvalues" indicates if the mean and the standard deviation described above (superior half of the sheet, right bottom area of each contrast

11 image) must be computed. Switching on this flag only has a meaning if the ROIs are defined (roi_path and list_roi described below). todo_printsummaryfiles = 1; "todo_printsummaryfiles" should be equal to 1 in order to print the summary sheets into.tif and.ps/.pdf files. With this flat equal to 0, the batch will only show on the screen the results, which is not very useful per se todo_location = 1; "todo_location" this flag HAS TO be switched on (=1) the FIRST TIME the batch is run on a set of data: matrix XYZ (which contains the correspondences of the voxel coordinates in mm) will be computed. Thus, this should be computed when the sizes of the images in the database are changed. If the batch has been run once with this flag equal to 1, the matrix has already been computed, and we may switch off (=0) this flag (in order to gain in computation time). - General parameters: these parameters give some detailed information about the contrasts to be displayed, the paths to the data, the ROIs (regions of interest), etc. summarysheets_dir = fullfile(protocol_path,'qualitycheck_files','contrastssummary'); "summarysheets_dir" is the output directory where the summary sheets in format.tif will be copied into (remember that the sheets in format.ps/.pdf are copied in a directory local to each subject's). It is not necessary to change it if the directory is convenient for you. Otherwise you can change it for example like this: summarysheets_dir = '/neurospin/my_path/contrastssummary'; list_contrastnumbers = [ ]; "list_contrastnumbers" contains the list of contrast numbers to be displayed on the sheet. Another example: list_contrastnumbers = [21: ]; % localizer list_contrasts = {'spmt_0013.img',... % V Strings - others 'spmt_0010.img',... % V Faces - others 'spmt_0002.img',... % V all active 'spmt_0040.img',... % A all active 'spmt_0041.img',... % A words - pseudowords 'spmt_0038.img'}; % V Checker rest "list_contrasts" contains the list of file names corresponding to the contrasts indicated in list_contrastnumbers. Another example: % localizer: list_contrasts = {'spmt_0021.img',... % left click - right click 'spmt_0022.img',... % right click - left click 'spmt_0023.img',... % video - audio 'spmt_0024.img',... % audio - video 'spmt_0029.img',... % computation - sentences 'spmt_0031.img'}; % video sentences - checkerboard contrasts_names = {'V Strings - others',... 'V Faces - others',... 'V all active',... 'A all active',... 'A words - pseudowords',... 'V Checker rest'};

12 "contrasts_names" is the list of character strings that will be used as titles for each contrast (typically the definition of the contrast). Another example: % localizer: contrasts_names = {'left click - right click',... 'right click - left click',... 'video - audio',... 'audio - video',... 'computation - sentences',... 'video - checkerboard'}; roi_path = '/neurospin/unicog/protocols/irmf/maindatabaselocalizers_pinelmoreno_2008/t ools/contrastssummary/roi'; "roi_path" is the path to the images of the regions of interest (ROIs) for the different contrasts. list_roi = {'leftclic_motorcortex.nii',... %contrast 21: left click-right click 'rightclic_motorcortex.nii',... %contrast 22: right click-left click 'video_occipitotemporal.nii',...%contrast 23: video-audio 'audio_temporal.img',... %contrast 24: audio-video 'calculation_parietal.nii',... %contrast 29: computation-sentences 'reading_lefthemisphere.nii'}; %contrast 31: video sentences-checkerboard "list_roi" contains the list of the file names corresponding to the ROIs for the different contrasts. threshold = 2.36; "threshold" is the T-value threshold used for displaying the contrasts. size_extent = 10; "size_extent" is the minimal size of the clusters to be displayed. Another typical value: size_extent = 20; EPIname = 'con_0002.img'; "EPIname" defines the contrast image to be displayed in the summary file. sym_name = 'symmetry_images/diff_con_0002.img'; % Symmetry image "sym_name" selects the symmetry image to be printed in the summary sheet. ANATname = '^wm.*\.img$'; % anatomical image to be displayed in the summary file "ANATname" defines a filter for selecting the anatomical image to be displayed in the summary sheet (typically the normalized anatomy should be taken). - Some examples:

13 Example 1 of summary sheet (subject 086) a correctly processed subject: Here the final score is 6/6 because all the contrasts verify the quality criterion.

14 Example 2 of summary sheet (subject 043) a subject with some movement: Here the final score is 4/6 because contrasts "left click right click" and "video checkerboard" do not verify the quality criterion. In the "left click right click" contrasts, some voxels are displayed but they are not in the ROI corresponding to this contrast. This causes the "Conclusion NOK". By taking a look to the movement curves, we can conclude that the problems in the contrasts may come from the important movement of the subject during the scanning.

15 6.7. Parameters for the stanplot step Description: stanplot (for "standardized plot", of course!) is a tool for computing and displaying the BOLD curves outcoming from any SPM5 model. There are to versions of "stanplot": one for a unique model, the other allows to compute the average of one or several groups of subjects. The latter is quite slow because it manipulates a quite big amount of data! The main interest of this tool is that it is generic for any SPM5 model with onsets, a command line is sufficient to plot the curves. It can also be integrated into a batch system as it is the case here. It is recommended to manipulate this tool with caution (see "help" below). Two essential points: - It is strongly recommended to systematically include in ALL your SPM models an "F-test of real interest" with all your variables of interest (also derivatives), excluding the constants and other movement variables. This program uses this F-test in order to exclude the parasite effects and the result (mainly at the group level) is much better. - The program generates two outputs: a simple average fixed on the events and an estimation by FIR model. There are some advantages and drawbacks for both approaches. "Event-related averaging" works perfectly well for slow-event paradigms in this case you would rather NOT use FIR! However, for fastevent paradigms, it is the opposite: FIR method extracts the BOLD curves much clearly than the "event-related averaging". NB for block paradigms none of these two options works very well except if you have only declared the onset of the block and not the onsets of every event inside each block In that case, "event-related averaging" is the solution. "stanplot" has an integrated help: you can take a look at the commentaries in the code or type "help" before each function ("stanplot_singlemodel_b.m", "stanplot_group_b_params.m"). However, a short description of the different parameters can be found below. This program uses old tools coming from "spm_graph" and are inspired by a presentation done by Sepideh Sadaghiani in a "methods meeting" at NeuroSpin (thanks to her!). Thank you to Stanislas Dehaene who has developed this tool! Code/parameter description: % SINGLE Finterest = 1; "Finterest" (usually = 1) indicates which contrast in the SPM model refers to the F test of real interest. nruns = 4; groupvar = repmat([ 0 2:5 zeros(1,12)],1,nruns); %groupvar = [ ]

16 "groupvar" is a "remapping" vector which allows you to regroup conditions at will. It must be as long as the numbers of runs the numbers of conditions in each run. For each such condition declared in the model, "groupvar" gives the output condition. Use zero for conditions that you don't want to see in the plot. timeaxis = [-4:1:12]; "timeaxis" specifies the time range and resolution of the resulting plot, in seconds. E.g. timeaxis = [-4:1:12] will give you a plot from -4 to 12 seconds, with a spacing of 1 second between the successive time points. baselinepoints = 3; "baselinepoints" specifies the number of initial points of the curve that serve as a baseline. The mean of these points will be subtracted from each curve. voxelcoord = [ ]; "voxelcoord" contains the voxel xyz coordinates in mm (it is an optional argument). E.g. [ ] for the VWFA. If they are not passed, then the program attempts to find them from the current cursor location in the current SPM figure 1. legend_30 = ['Cond 2';'Cond 3';'Cond 4';'Cond 5']; legend_32 = ['Cond 2';'Cond 3';'Cond 4';'Cond 5']; Variables called "legend_nm" indicate the legends for the figures. ATTENTION: the number of legend titles must be the same as the number of conditions different from zero in "groupvar" (for one run). Here you have some "legend" tips for removing conditions: if we have : groupvar =[ ] then, we must adapt the legend this way: legend('ff',' ','FR','JR'); % GROUP (this part replaces old function "getsubjectsdata.m") ngroups=2; "ngroups" gives the number of groups of subjects. groupn{1} = 'all'; groupn{2} = 'allb'; "groupn{n}" contain the name of the groups of subjects. Another example: groupn{1} = 'BonsLecteurs'; groupn{2} = 'Dyslexiques'; nsub(1) = 2; nsub(2) = 2; "nsub{n}" give the number of subjects in each group. totsub = sum(nsub); "totsub" indicates the total number of subjects. Another example: nsub(1) = 22; nsub(2) = 19; totsub = sum(nsub); %% total number of subjects 7. How to run the batch in 5 minutes If you just want to run the batch very quickly in order to compute the preprocessing, you can do it by adapting a few parameters and take more time to think about the rest. Thus, if you only intend to run the preprocessing of your data, follow the instructions below.

17 1) In the "to do" list set to 1 only these flags: todo_initializations, todo_convert_and_remove_dicoms, todo_rename, todo_preprocessing. Thus, the list of flags must remain: % INITIALIZATIONS todo_initializations = 1; % PREPARATION OF THE DATA todo_clean_old_results = 0; todo_convert_and_remove_dicoms = 1; todo_rename = 1; % PREPROCESSING todo_preprocessing = 1; % QUALITY CHECK OF THE PREPROCESSING todo_artrepair_diagnosis = 0; % FIRST LEVEL ANALYSIS todo_firstlevelprocessing = 0; % POST-PROCESSING todo_smooth_con = 0; todo_smooth_gmwm = 0; todo_symmetry = 0; todo_segm_postproc = 0; todo_remove_nan = 0; % QUALITY CHECK OF THE FIRST LEVEL ANALYSIS todo_contrastssummary = 0; todo_stanplot = 0; % RFX ANALYSIS todo_rfxanalysis_on_epi= 0; todo_rfxanalysis_on_asymmetry= 0; 2) Set these parameters for the step "preparation of the data" to your will: protocol = '/neurospin/unicog/protocols/irmf/maindatabaselocalizers_pinelmoreno_2008'; list_subjects = {'subject1','pn071234'}; list_sessions = {'audio1','audio2','audio3','visu1','visu2'}; origin_name = '3T_neurospin'; study_name = 'illiterates_3t_neurospin'; Some other parameters may remain untouched most of the times: todo_rename_with_subject_name = 1; anat_path = 't1mri/acquisition1'; anatwc = '^anat.*\.img$'; modality = 'fmri'; list_acquisitions = {'acquisition1'}; 3) Finally, adapt the parameters for the preprocessing:

18 TR = 2.4; slice_order = 'sequential_ascending'; ref_slice = 1; voxelsize = [3 3 3]; smoothing = 5; todo_normalization = 1; todo_normalizationont1template = 1; The rest of the parameters are not necessary for this step. For example: con_smoothing = 8; gmwm_smoothing = 3; will only be necessary for the post-processing stage, and if you do not intend to compute the distortion correction, you only have to put this flag to 0: todo_distortion_correction = 0; The remaining parameters for the distortion correction, the preprocessing quality check, the first level analysis, the contrasts summary sheets and the "stanplot" will not be taken into account. In order to ease the "5 minutes parameter tuning", the essential parameters are marked with "[5_min_run]" in this document. 8. Coming improvements This is a list of some improvements that will be included in the next version of the batch system described here: - Check if images swa* already exist in order not to re-process them. - Separate flag todo_convert_and_remove_dicoms in two different flags because it is ambiguous (one could want to convert without removing DICOM files). - Add the extension of DICOM files (.MRDC,.dcm...) as a parameter. - Add to the package an example of files of a generic first level model (.xls file). For example, the one of illiterates study. - Set automatically flag todo_location = 1; the first time (if "XYZ.mat" does not exist), otherwise set todo_location = 0; automatically too. - Make function "rename_files.m" more robust and more generic: now, if a "study_name" different from the three envisaged names ("15T_shfj", "3T_shfj", "3T_neurospin") is chosen, nothing happens in the renaming step! In addition to this, there are some other problems with this function: if the post-processing is not computed (for white and gray matters) and the main batch is re-run (with only flag todo_rename = 1;), then images files are renamed incorrectly:

19 anat contains normalized white matter manat contains normalized anatomy wmanat contains non-normalized white matter Tip: normally created images what they become when "rename_files.m" is executed anat anat GM_anat anat manat manat? wgm_anat anat? wmanat wmanat? WM_anat anat? wwm_anat anat? First conclusion (to verify): problem in "if" clauses (c1, c2, w, wm...). Images *WM* and *GM* are not correctly renamed! 9. Where to find it The batch system described in this document can be downloaded from the Unicog wiki: In the intranet of NeuroSpin it is also available in: /neurospin/unicog/resources/matlab_scripts/fmri_generic_batch/ Copy the.tar file and untar it (for example, in Linux use command tar xvf fmri_generic_batch_ tar).