<> ---- . '''Contents '''<> ---- . For an overview of the benefits of using aa see AutomaticAnalysisIntroduction <> = Overview = == The components == === The modules === aa has a modular design. Each module handles a single task, which may be peformed once per study, per subject or per session. All modules have a name that begins "aamod_" (e.g., aamod_realign). There are a few modules that process your input parameters or perform other setup tasks, which are run every time you launch an aa analysis. These are called "initialisation modules". === The engine === The engine (usually via the aa_doprocessing command) takes a description of the tasks you wish to perform, and then runs the appropriate modules. It also provides a number of helper subroutines to support the modules (beginning aas_), and also some useful utilities such as the aa_benchmark command to measure analysis times, and the aa_report tool to generate an HTML summary. === Specifying an analysis === The components of the aa system are arranged in a hierarchy. At the top ''recipes'' describe whole processing pipelines. They are made up of a selection of ''parameter sets, ''each of which defines a group related parameters. Finally, the individual ''parameters'' actually specify what happens. aa recipes begin with 'aarecipe_' and parameter sets 'aap_' In your user script you must choose a recipe. If you wish, you may then override single parameters. Occasionally, you may also wish to override whole parameter sets from a recipe chosen. The entire specification is contained in a single Matlab structure, usually called 'aap'. This has many elements, to store each of the paramter sets, and one that specifies the SPM default settings. An overview of the different types of components is shown in this table: ||''Component'' ||''Description'' ||''Location of file'' ||''Expertise needed to write new ones'' || ||User script ||Sets up a description of the analysis to be performed. Selects a recipe, adds study specific information, and changes any defaults ||User's directory ||Beginner || ||Recipes ||A full description of the processing pipeline. This is implemented by choosing a group of parameter sets. ||Centrally ||Beginner/ Intermediate || ||Parameter sets ||Groups of related parameters. There are five different basic types of parameter set ||Centrally ||Intermediate || ||Modules ||Run individual stages of processing ||Centrally ||Some Matlab experience || ||Engine ||Main automatic analysis engine, which contols module execution ||Centrally ||Advanced || The most important of these by far from the user’s point of view is the “User script”. The next section describes this. <> = User script = == Overview == This specifies an analysis. Many studies can be analysed up to and including the stage of normalisation with changes to this alone. With some changes to the specificaiton of the experimental design in aamod_model_firstlevel, you may run all the way up to and including second level statistics. There are sections to the user script: || ||''Section'' ||''Probability you need to change it and when'' || ||1 ||Choosing a recipe ||(0.2) If you use a non-standard acquisition sequence or wish to do a quite different type of analysis || ||2 ||Changing any of the parameter sets in the recipe ||(0.1) If you wish to change a single parameter set controlling part of the automatic processing from what is specified in a recipe || ||3 ||Initialising using the parameter sets ||(0.01) Usually never || || ||Setting study specific details ||(1.0) Always || || ||Set any other parameters that need to differ from the defaults ||(0. If you wish to change single parameters || || ||Calling aa_doprocessing to do the processing<
> ||(0.01) Usually never|| An example, which will process 3 subjects each with sessions up to and including normalisation is below: ---- ''% Automatic analysis '' % User master script % Rhodri Cusack MRC CBU Cambridge 200 % (1) RESET ALL PARAMETERS aap=[]; % (2) ANALYSIS RECIPE % General auto TR recipe; slice order Siemens product sequence default aap=aarecipe_general_ver01(aap); % (3) MODIFY STANDARD RECIPE MODULE SELECTION HERE IF YOU'D LIKE . % do this here % ( GET ALL THE PARAMETERS FOR THIS RECIPE aap=aa_init(aap); % ( 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 = '/home/rhodri/pvs/cbu'; . % Add subjects and session numbers for EPI data aap=aas_addsubject(aap,'*CBU0011/*',[11 12]); aap=aas_addsubject(aap,'*CBU0012/*',[12 10]); . % 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; % ( SET ANY OTHER PARAMETERS YOU WOULD LIKE TO BE DIFFERENT FROM THE DEFAULTS % (7) SET ANY SPM DEFAULTS IF NEEDED aap.spm.defaults.normalise.write.vox=[3 3 3]; % (8) DO PROCESSING aa_doprocessing(aap); ---- The four sections you are mostly likely to need to change (1, 2, and are now discussed in turn. NB: Be careful about changing the aa_user script after you’ve run part of an analysis. The problem with doing this is that if the changes you make would have affected the parts that have already been completed, you won’t be able to use the script to exactly recreate your data in future. <> == Choosing the recipe == These are chosen with the line || ||aap=''[recipename]''(aap); || e.g., aap=aarecipe_general(aap); An example recipe is shown below. Descriptions of the parameter sets are in the next section. A full list of recipes is on the AutomaticAnalysisManualReference page. ||''Name: '' || ||aarecipe_general || ||''Description:'' ||Standard automatic TR recipe || ||''Parameter set choice: '' || || ||''Type'' ||''Parameter set'' || ||directory_conventions ||aap_directory_conventions_ver00 || ||options ||aap_options_ver00 || ||tasklist ||aap_tasklist_cbudefault_ver00 || ||spmanalysis ||aap_spmanalysis_tr1p1_ver00 || ||acq_details ||aap_acq_details_ver00 || <> == Modify parameter set selection == A recipe comprises a description of the parameter sets that should be included. Once you’ve chosen a recipe you may override some of the different parameter sets. You would do this in stage 2 of the user script (see above) with a line like ||aap.recipe.directory_conventions=’aap_directory_conventions_mynewstyle’ || (NB: no ‘.m’ on end) There are different types of parameter sets. A full list of the available parameter sets is given in the AutomaticAnalysisManualReference section. ||''Type'' ||''Description'' || ||directory_conventions ||Specifies directory and file conventions, for example: raw data directory (by default /mridata/cbu) || ||options ||General aa program options, for example: whether to automatically identify the field maps and structurals in the incoming dataset; whether to copy structurals to the central store || ||tasklist ||The list of tasks to be performed (e.g., modules to be executed) for each study || ||spmanalysis ||SPM & imaging analysis parameters, for example: TR & slice acquisition tim; smoothing FWHM; evolution time of fieldmaps || ||acq_details ||Acquisition details. Several of the defaults are overridden in the user script, for example:<
>- study directory<
>- subject list || <> == Setting your acquisition parameters == You always need to do this, to tell the system which files to analyse. The essential lines with explanation and notes are these: ||aap.acq_details.root = '/cbu/scratch2/rhodri.cusack/newsimultaneous';<
> ||Specifies the directory where the processed study data are stored. This directory should exist before you run the script.|| ||aap.acq_details.sessions={'ns1_block1','ns1_block2','ns2_passive','ns2_active'};<
> ||These are names of the blocks in your experiment. This must be the same for all subjects. Here, there were four blocks. I find it easiest to use intuitive names that describe the behavioural condition.|| ||aap.acq_details.numdummies=18;<
> ||Number of dummy scans at the start of each session that need to be thrown away.|| Too make it easy to see the correspondence between subject and session number, I now recommend subject names are added with the aas_addsubject command: aap=aas_addsubject(aap, ‘*CBU0011\*’,[11]); The full syntax of this command is in Error! Reference source not found., but the first string specifies the raw data for this subject (you may use wildcards) and the numbers in square brackets the series numbers for the EPI data. There should be as many of these are there are blocks, as specified in aap.acq_details.sessions and described above. By default, MPRAGE structural and GRE_FIELDMAPPING fieldmap scans are automatically detected. This will lead to an error if for some reason you have collected more than one fieldmap or structural scan for a given subject. In this case you can specify those scans which should be ignored in a final optional parameter. For example, if you wished to ignore aborted structural scans with series numbers 2 and 3, you might type: aap=aas_addsubject(aap, ‘*CBU0011\*’,[11],[2 3]); <> == Set specific parameters that you wish to differ from the defaults == Once you’ve set up the parameters using a recipe and any different parameter sets you’d like, there may still be one or two parameters that you need to change. You do this at this stage. For example, in the sample script, if my data were no longer in /mridata/cbu I would add the line: aap.directory_conventions.rawdatadir='/imaging/rhodri/newsimultaneous'; A full list of parameters with descriptions is given in section Error! Reference source not found.. == Set any SPM defaults == Any SPM defaults can be changed. You do this using lines like the following: || ||aap.spm.defaults.normalise.write.vox=[3 3 3]; || The aap.spm.defaults structure gets copied into the GLOBAL “defaults” variable before running SPM functions. <> = Everyday tasks = <> == Getting ready to use AA == Once you’ve started a Matlab/SPM session, type || ||>> aa_ver1 || at the Matlab prompt to add the automatic analysis paths <> == Running an analysis == Once you’ve made your user script, just type its name to run it. When it starts to run, it does some checks, and so you may see some warnings. These give you advanced notice that your script may have problems at some stage <> == Restarting an analysis == To restart an analysis, just type the script name again. It will start from where it left off. <> == How do I force an analysis to start all over again? == Change to the study directory and delete the “done_aamod_studyinit” flag ''Example'' ''Type at UNIX prompt. When you run an analysis again it will redo the realignment stage and all stages after it for this subject.'' || ||cd /imaging/rhodri/mystudydir || || ||rm done_aamod_studyinit || <> == How do I force an analysis to start from a particular stage? == To track how far through the analysis it has got, the system writes small files that start with “done_...” and end with the module name. Where a module has to be executed once per study, the done_ file will be in the study directory. Where it has to be executed once per subject, it will be in the subject directory. Where it has to be done for every session, it will be in the individual session directories. If you delete one of these flags, then this stage and all others after it will be re-run. Note it isn’t always completely obvious whether a module is once-per-subject (e.g., realignment) or once-per-session (e.g., slice timing). See the Reference section 0 to check. ''Example'' ''Type at UNIX prompt. When you run an analysis again it will redo the realignment stage and all stages after it for this subject.'' || ||cd /imaging/rhodri.cusack/mystudydir || || ||cd CBU060500 || || ||rm done_aamod_realign || <> = Pitfalls - beware! = <> == Check your data == Although the processing is automated, this doesn’t mean that things will never go wrong. Your data may have a problem – scanning glitches or excessive subject movement, for example – or there maybe something wrong with the analysis. Just as you would when doing it by hand, you should check your data at various stages. === Diagnostic JPEGs === One way of checking your data is to check through the images dumped in the analysed study, subject and block directories. These files begin with “diagnostic_aamod” end have a “.jpg” suffix. These are described in the table below. Current output is all graphical, in the form of JPEG files. These may be viewed using a Windows graphics viewer, or with xv on unix. Examples are below ||''Name'' ||''File directory'' ||''Description'' || ||diagnostic_aamod_anato3d_rawmean ||Session ||raw mean as generated by anato3d || ||diagnostic_aamod_anato3d_rawvar ||Session ||raw variance as generated by anato3d || ||diagnostic_aamod_tsdiffana ||Session ||output from tsdiffana || ||diagnostic_aamod_realign ||Subject ||realignment display from SPM || ||diagnostic_aamod_undist ||Subject ||evaluation of undistortion. Top pair of images are in distorted space and should be similar in shape and coregistered with each other. Left is distorted fieldmap magnitude, right is raw EPI. Bottom two images are in undistorted space and should be similar in shape and coregistered with each other, although not necessarily with the top two images. || ||diagnostic_aamod_coreg ||Subject ||SPM output from coregistration of structural and undistorted EPI || ||diagnostic_aamod_norm ||Subject ||SPM output from normalisation || <>Rhodri Cusack, MRC CBU, Cambridge<>. Thank you to Matthew Brett, Jessica Grahn, Daniel Mitchell, Rik Henson & Matt Davis, who contributed to the code and this manual.