aa Scripting SPM analyses using aa Rhodri Cusack

aa Automates analysis of neuroimaging data using SPM. Automatic Advantages over simple batch systems Restartable Hierarchical & modular, e.g., “recipes” Well behaved Record keeping Modules have simple interface Easy to start using & to keep up to date Two versions: one for SPM 5 & the new scanner, and one for SPM 2 and the old scanner Popular! 34/34 users that expressed a preference (actually, that have analyzed data from CBU scanner on Linux systems, and have not blocked disc access) 34/34 aa

Typical user script % Automatic analysis % User master script % Rhodri Cusack MRC CBU Cambridge 2006 % (1) RESET ALL PARAMETERS aap=[]; % (2) ANALYSIS RECIPE % General auto TR recipe; slice order Siemens product sequence default aap=aarecipe_general_withmodel_ver02(aap); % (3) MODIFY STANDARD RECIPE MODULE SELECTION HERE IF YOU'D LIKE % do this here % (4) GET ALL THE PARAMETERS FOR THIS RECIPE aap=aa_init(aap); % (5) DEFINE STUDY SPECIFIC PARAMETERS aap.options.aa_minver=1.0; % will only work on aa version 1.0 or above % The study directory aap.acq_details.root = '/imaging/rhodri/aa_demo'; % Add subjects and session numbers for EPI data aap=aas_addsubject(aap,'*CBU050011/*',[5 11]); % Condition names for each session, must be same for all subjects aap.acq_details.sessions={'mystery1','mystery2'}; % Number of dummy scans at the start of each session aap.acq_details.numdummies=18; % Slice acquisition order aap.spmanalysis.sliceorder=[32:-1:1]; % 32 descending % (6) SET ANY OTHER PARAMETERS YOU WOULD LIKE TO BE DIFFERENT FROM THE DEFAULTS % (7) SET ANY SPM DEFAULTS IF NEEDED % (8) DO PROCESSING aa_doprocessing(aap);

aa Recipes currently available

aa Typical user script % Automatic analysis % User master script % Rhodri Cusack MRC CBU Cambridge 2006 % (1) RESET ALL PARAMETERS aap=[]; % (2) ANALYSIS RECIPE % General auto TR recipe; slice order Siemens product sequence default aap=aarecipe_general_withmodel_ver02(aap); % (3) MODIFY STANDARD RECIPE MODULE SELECTION HERE IF YOU'D LIKE % do this here % (4) GET ALL THE PARAMETERS FOR THIS RECIPE aap=aa_init(aap); % (5) DEFINE STUDY SPECIFIC PARAMETERS aap.options.aa_minver=1.0; % will only work on aa version 1.0 or above % The study directory aap.acq_details.root = '/imaging/rhodri/aa_demo'; % Add subjects and session numbers for EPI data aap=aas_addsubject(aap,'*CBU050011/*',[5 11]); % Condition names for each session, must be same for all subjects aap.acq_details.sessions={'mystery1','mystery2'}; % Number of dummy scans at the start of each session aap.acq_details.numdummies=18; % Slice acquisition order aap.spmanalysis.sliceorder=[32:-1:1]; % 32 descending % (6) SET ANY OTHER PARAMETERS YOU WOULD LIKE TO BE DIFFERENT FROM THE DEFAULTS % (7) SET ANY SPM DEFAULTS IF NEEDED % (8) DO PROCESSING aa_doprocessing(aap);

aa File structure

aa Typical user script % Automatic analysis % User master script % Rhodri Cusack MRC CBU Cambridge 2006 % (1) RESET ALL PARAMETERS aap=[]; % (2) ANALYSIS RECIPE % General auto TR recipe; slice order Siemens product sequence default aap=aarecipe_general_withmodel_ver02(aap); % (3) MODIFY STANDARD RECIPE MODULE SELECTION HERE IF YOU'D LIKE % do this here % (4) GET ALL THE PARAMETERS FOR THIS RECIPE aap=aa_init(aap); % (5) DEFINE STUDY SPECIFIC PARAMETERS aap.options.aa_minver=1.0; % will only work on aa version 1.0 or above % The study directory aap.acq_details.root = '/imaging/rhodri/aa_demo'; % Add subjects and session numbers for EPI data aap=aas_addsubject(aap,'*CBU050011/*',[5 11]); % Condition names for each session, must be same for all subjects aap.acq_details.sessions={'mystery1','mystery2'}; % Number of dummy scans at the start of each session aap.acq_details.numdummies=18; % Slice acquisition order aap.spmanalysis.sliceorder=[32:-1:1]; % 32 descending % (6) SET ANY OTHER PARAMETERS YOU WOULD LIKE TO BE DIFFERENT FROM THE DEFAULTS % (7) SET ANY SPM DEFAULTS IF NEEDED % (8) DO PROCESSING aa_doprocessing(aap);

aa Typical user script % Automatic analysis % User master script % Rhodri Cusack MRC CBU Cambridge 2006 % (1) RESET ALL PARAMETERS aap=[]; % (2) ANALYSIS RECIPE % General auto TR recipe; slice order Siemens product sequence default aap=aarecipe_general_withmodel_ver02(aap); % (3) MODIFY STANDARD RECIPE MODULE SELECTION HERE IF YOU'D LIKE % do this here % (4) GET ALL THE PARAMETERS FOR THIS RECIPE aap=aa_init(aap); % (5) DEFINE STUDY SPECIFIC PARAMETERS aap.options.aa_minver=1.0; % will only work on aa version 1.0 or above % The study directory aap.acq_details.root = '/imaging/rhodri/aa_demo'; % Add subjects and session numbers for EPI data aap=aas_addsubject(aap,'*CBU050011/*',[5 11]); % Condition names for each session, must be same for all subjects aap.acq_details.sessions={'mystery1','mystery2'}; % Number of dummy scans at the start of each session aap.acq_details.numdummies=18; % Slice acquisition order aap.spmanalysis.sliceorder=[32:-1:1]; % 32 descending % (6) SET ANY OTHER PARAMETERS YOU WOULD LIKE TO BE DIFFERENT FROM THE DEFAULTS % (7) SET ANY SPM DEFAULTS IF NEEDED % (8) DO PROCESSING aa_doprocessing(aap);

aa Typical user script % Automatic analysis % User master script % Rhodri Cusack MRC CBU Cambridge 2006 % (1) RESET ALL PARAMETERS aap=[]; % (2) ANALYSIS RECIPE % General auto TR recipe; slice order Siemens product sequence default aap=aarecipe_general_withmodel_ver02(aap); % (3) MODIFY STANDARD RECIPE MODULE SELECTION HERE IF YOU'D LIKE % do this here % (4) GET ALL THE PARAMETERS FOR THIS RECIPE aap=aa_init(aap); % (5) DEFINE STUDY SPECIFIC PARAMETERS aap.options.aa_minver=1.0; % will only work on aa version 1.0 or above % The study directory aap.acq_details.root = '/imaging/rhodri/aa_demo'; % Add subjects and session numbers for EPI data aap=aas_addsubject(aap,'*CBU050011/*',[5 11]); % Condition names for each session, must be same for all subjects aap.acq_details.sessions={'mystery1','mystery2'}; % Number of dummy scans at the start of each session aap.acq_details.numdummies=18; % Slice acquisition order aap.spmanalysis.sliceorder=[32:-1:1]; % 32 descending % (6) SET ANY OTHER PARAMETERS YOU WOULD LIKE TO BE DIFFERENT FROM THE DEFAULTS % (7) SET ANY SPM DEFAULTS IF NEEDED % (8) DO PROCESSING aa_doprocessing(aap);

aa Typical user script % Automatic analysis % User master script % Rhodri Cusack MRC CBU Cambridge 2006 % (1) RESET ALL PARAMETERS aap=[]; % (2) ANALYSIS RECIPE % General auto TR recipe; slice order Siemens product sequence default aap=aarecipe_general_withmodel_ver02(aap); % (3) MODIFY STANDARD RECIPE MODULE SELECTION HERE IF YOU'D LIKE % do this here % (4) GET ALL THE PARAMETERS FOR THIS RECIPE aap=aa_init(aap); % (5) DEFINE STUDY SPECIFIC PARAMETERS aap.options.aa_minver=1.0; % will only work on aa version 1.0 or above % The study directory aap.acq_details.root = '/imaging/rhodri/aa_demo'; % Add subjects and session numbers for EPI data aap=aas_addsubject(aap,'*CBU050011/*',[5 11]); % Condition names for each session, must be same for all subjects aap.acq_details.sessions={'mystery1','mystery2'}; % Number of dummy scans at the start of each session aap.acq_details.numdummies=18; % Slice acquisition order aap.spmanalysis.sliceorder=[32:-1:1]; % 32 descending % (6) SET ANY OTHER PARAMETERS YOU WOULD LIKE TO BE DIFFERENT FROM THE DEFAULTS % (7) SET ANY SPM DEFAULTS IF NEEDED % (8) DO PROCESSING aa_doprocessing(aap);

aa The hierarchy user script –purpose: to set up aap structure, which describes processing to be done recipes –describe a default processing pipeline –in fact, just specify a group of parameter sets aap_directory_conventions_ver00 aap_tasklist_withmodel_ver00... modules –initialisation modules run at start of each processing run aamod_evaluatesubjectnames –main modules only run once (per study/ subject/ session) aamod_realign... helper functions –helper functions aas_getsubjpath aas_getsesspath aas_getimages... engine –main tools aa_doprocessing aa_report... on site off site during installation

aa Checking output Although processing happens automatically it is VITAL THAT YOU CHECK YOUR DATA at various stages of processing You should do this in the normal way with SPM aa provides two ways to help you further –diagnostic jpeg images tsdiffana motion correction coreg normalisation undistortion –aa_report function After analysis, type –aa_report(‘study root path’) –Or aa_report if already in study root Use version of aa that original analysis was run with –aa_ver1_devel and aa_ver11 incompatible

aa First level model & contrasts At present, if you wish to automate first level (single subject) modelling, you must modify these modules: –aamod_firstlevel_model –aamod_firstlevel_contrasts Simple second level models will then run automatically –one-sample t-test for each contrast at first level Next day results!

aa Documentation wiki matlab reference

aa Installation outside CBU

aa Other features Benchmarking –After analysis, type aa_benchmark(‘study root path’) Or aa_benchmark if already in study root

aa Adding or overriding modules You may add a new component –Place in same directory as aa_user script, or in your matlab path …or override an existing one –As above, but give it the same name as the component you’re overriding Type which [commandname] (e.g., which aamod_realign) to find out which version of a function you are currently using Naming conventions Modulesaamod_ Recipesaarecipe_ Parameter sets (tasklists etc…)aap_ Engineaa_ Helper subroutinesaas_

aa aap_tasklist_general_ver02 % Automatic analysis % Rhodri Cusack MRC CBU Cambridge % aap_tasklist_general_ver02 function [aap]=aap_tasklist_general_ver02(aap) % these initialisation modules are always run at the start of a batch script run aap.tasklist.initialisationmodules={'aamod_checkparameters','aamod_evaluatesubjectnames','aamod_make_sub jects_short','aamod_autoidentifyseries_timtrio'}; % EPI file prefix definitions now moved here as depends so strongly on % tasklist - second parameter for functions that have EPI input, blank if not aap.tasklist.epiprefix=[];% reset prefix list aap.tasklist.stages=[];% reset list of stages aap=aas_addtask(aap,'aamod_study_init'); aap=aas_addtask(aap,'aamod_newsubj_init'); aap=aas_addtask(aap,'aamod_converttmaps'); aap=aas_addtask(aap,'aamod_copystructural'); aap=aas_addtask(aap,'aamod_convert_epis'); aap=aas_addtask(aap,'aamod_tsdiffana','f'); aap=aas_addtask(aap,'aamod_realign','f'); aap=aas_addtask(aap,'aamod_slicetiming','rf'); aap=aas_addtask(aap,'aamod_coreg_noss','arf'); aap=aas_addtask(aap,'aamod_norm_noss','arf'); aap=aas_addtask(aap,'aamod_norm_write','arf'); aap=aas_addtask(aap,'aamod_smooth','warf');

aa Structure of modules % AA module - smoothing % Kernel size determined by aap.spm_analysis.FWHM % Rhodri Cusack MRC CBU Cambridge Jan 2006 function [aap,resp]=aamod_smooth(aap,task,i) resp=''; switch task case 'domain' resp='subject'; % this module needs to be run once per subject case 'description' resp='SPM5 smooth'; case 'summary' subjpath=aas_getsubjpath(i); resp=sprintf('Smooth run on %s\n',subjpath); case 'report' case 'doit' % get the subdirectories in the main directory subj_dir = aas_getsubjpath(aap,i); … case 'checkrequirements' otherwise aas_log(aap,1,sprintf('Unknown task %s',task)); end;

aa Writing your own modules - helper functions Getting subject path subjpth=aas_getsubjpath(aap,subjnum); Getting session path sesspth=aas_getsesspath(aap,subjnum,sessnum); Getting EPI images with particular prefix imagefns=aas_getimages(aap,subjnum,sessnum,prefixes,minimg,maximg) e.g., aas_getimages(aap,1,3,’wra’); Finding files fn=aas_findfiles(aap,’/imaging/rhodri/blah*/blah.nii’); Running shell command fn=aas_shell(’ls’);

aa Summary Using aa to script SPM analyses is popular –Easy-to-use –Robust –Encourages efficient practice –Easy to extend