Diff for "AutomaticAnalysisManual" - MRC CBU Imaging Wiki
location: Diff for "AutomaticAnalysisManual"
Differences between revisions 7 and 8
Revision 7 as of 2006-06-02 00:32:55
Size: 16783
Editor: RhodriCusack
Comment:
Revision 8 as of 2006-06-02 00:34:47
Size: 18253
Editor: RhodriCusack
Comment:
Deletions are marked like this. Additions are marked like this.
Line 3: Line 3:
'''aa release 1.1'''
Rhodri Cusack, MRC CBU, Cambridge __rhodri.cusack [at] mrc-cbu.cam.ac.uk__
'''aa release 1.1''' Rhodri Cusack, MRC CBU, Cambridge __rhodri.cusack [at] mrc-cbu.cam.ac.uk__
Line 9: Line 8:
Line 12: Line 10:

|| ||''''''||[#s Summary]||
|| ||''''''||[#s Main Features]||
|| ||''''''||[#s System overview]||
|| ||''''''||[#s User script]||
|| ||'''4.'''||[#s4. Overview]||
|| ||'''4.'''||[#s4. Choosing the recipe]||
|| ||'''4.'''||[#s4. Modify parameter set selection]||
|| ||'''4.'''||[#s4. Setting your acquisition parameters]||
|| ||'''4.'''||[#s4. Set specific parameters that you wish to differ from the defaults]||
|| ||''''''||[#s Everyday tasks]||
|| ||'''5.'''||[#s5. Getting ready to use AA]||
|| ||'''5.'''||[#s5. Running an analysis]||
|| ||'''5.'''||[#s5. Restarting an analysis]||
|| ||'''5.'''||[#s5. How do I force an analysis to start all over again?]||
|| ||'''5.'''||[#s5. How do I force an analysis to start from a particular stage?]||
|| ||''''''||[#s Pitfalls - beware!]||
|| ||'''6.'''||[#s6. Check your data]||
|| ||'''6.'''||[#s6. Changing the aa_user script]||
|| ||''''''||[#s Reference]||
|| ||'''7.'''||[#s7. Available recipes]||
|| ||'''7.'''||[#s7. Available parameter sets]||
|| ||'''7.2.'''||[#s7.2. directory_conventions]||
|| ||'''7.2.'''||[#s7.2. options]||
|| ||'''7.2.'''||[#s7.2. tasklist]||
|| ||'''7.2.'''||[#s7.2. spmanalysis]||
|| ||'''7.2.'''||[#s7.2. acq_details]||
|| ||'''7.'''||[#s7. Individual parameters]||
|| ||'''7.3.'''||[#s7.3. acq_details]||
|| ||'''7.3.'''||[#s7.3. directory_conventions]||
|| ||'''7.3.'''||[#s7.3. options]||
|| ||'''7.3.'''||[#s7.3. spmanalysis]||
|| ||'''7.3.'''||[#s7.3. tasklist]||
|| ||'''7.'''||[#s7. Initialisation modules]||
|| ||'''7.4.'''||[#s7.4. aamod_checkparameters.m]||
|| ||'''7.4.'''||[#s7.4. aamod_make_subjects_short]||
|| ||'''7.4.'''||[#s7.4. aamod_autoidentifyseries.m]||
|| ||'''7.'''||[#s7. Modules]||
|| ||'''7.5.'''||[#s7.5. aamod_newsubj_init.m]||
|| ||'''7.5.'''||[#s7.5. aamod_copyfieldmaps.m]||
|| ||'''7.5.'''||[#s7.5. aamod_pvconv.m]||
|| ||'''7.5.'''||[#s7.5. aamod_copystructural.m]||
|| ||'''7.5.'''||[#s7.5. aamod_ana4dto3d.m]||
|| ||'''7.5.'''||[#s7.5. aamod_slicetiming.m]||
|| ||'''7.5.'''||[#s7.5. aamod_realign.m]||
|| ||'''7.5.'''||[#s7.5. aamod_undist.m]||
|| ||'''7.5.'''||[#s7.5. aamod_coreg.m]||
|| ||'''7.5.1'''||[#s7.5.1 aamod_norm.m]||
|| ||'''7.5.1'''||[#s7.5.1 aamod_undist_reslice.m]||

[[Anchor(s)]]
= Summary =
|| ||[#s Summary] ||
|| ||[#s Main Features] ||
|| ||[#s System overview] ||
|| ||[#s User script] ||
|| ||[#s4. Overview] ||
|| ||[#s4. Choosing the recipe] ||
|| ||[#s4. Modify parameter set selection] ||
|| ||[#s4. Setting your acquisition parameters] ||
|| ||[#s4. Set specific parameters that you wish to differ from the defaults] ||
|| ||[#s Everyday tasks] ||
|| ||[#s5. Getting ready to use AA] ||
|| ||[#s5. Running an analysis] ||
|| ||[#s5. Restarting an analysis] ||
|| ||[#s5. How do I force an analysis to start all over again?] ||
|| ||[#s5. How do I force an analysis to start from a particular stage?] ||
|| ||[#s Pitfalls - beware!] ||
|| ||[#s6. Check your data] ||
|| ||[#s6. Changing the aa_user script] ||
|| ||[#s Reference] ||
||
|| ||
|| || ||
|| || ||
|| || ||
|| || ||
|| || ||
|| || ||
|| || ||
|| || ||
|| || ||
|| || ||
|| || ||
|| || ||
|| || ||
|| || ||
|| || ||
|| || ||
|| || ||
|| || ||
|| || ||
|| || ||
|| || ||
|| || ||
|| || ||
|| || ||
|| || ||
|| || ||
|| || ||
|| || ||


[Anchor(s)]]
= Summary =
Line 66: Line 65:

[[Anchor(s)]]
=  Main Features =
[[Anchor(s)]]
= Main Features =
Line 86: Line 84:
=  System overview = = System overview =
Line 89: Line 87:

||<^
>''Component'' ||<^>''Description'' ||<^>''Location of file'' ||<^>''Expertise needed to write new ones''||
||<^>User script ||<^>In overall control. Selects a recipe, adds study specific information, and changes any defaults ||<^>User's directory ||<^>Beginner||
||<^>Recipes ||<^>Specifies which parameter sets to use ||<^>Centrally ||<^>Beginner/ Intermediate||
||<^>Parameter sets ||<^>Set default parameters. There are five different basic types of parameter set ||<^>Centrally ||<^>Intermediate||
||<^>Modules ||<^>Run individual stages of processing ||<^>Centrally ||<^>Advanced||
||<^>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.
[[Anchor(s)]]
= User script =
||<style="vertical-align: top;">''Component'' ||<style="vertical-align: top;">''Description'' ||<style="vertical-align: top;">''Location of file'' ||<style="vertical-align: top;">''Expertise needed to write new ones'' ||
||<style="vertical-align: top;">User script ||<style="vertical-align: top;">In overall control. Selects a recipe, adds study specific information, and changes any defaults ||<style="vertical-align: top;">User's directory ||<style="vertical-align: top;">Beginner ||
||<style="vertical-align: top;">Recipes ||<style="vertical-align: top;">Specifies which parameter sets to use ||<style="vertical-align: top;">Centrally ||<style="vertical-align: top;">Beginner/ Intermediate ||
||<style="vertical-align: top;">Parameter sets ||<style="vertical-align: top;">Set default parameters. There are five different basic types of parameter set ||<style="vertical-align: top;">Centrally ||<style="vertical-align: top;">Intermediate ||
||<style="vertical-align: top;">Modules ||<style="vertical-align: top;">Run individual stages of processing ||<style="vertical-align: top;">Centrally ||<style="vertical-align: top;">Advanced ||
||<style="vertical-align: top;">Engine ||<style="vertical-align: top;">Main automatic analysis engine, which contols module execution ||<style="vertical-align: top;">Centrally ||<style="vertical-align: top;">Advanced ||


= =The most important of these by far from the user’s point of view is the “User script”. The next section describes this. [[Anchor(s)]]

=
User script =
Line 101: Line 100:
This is the master script, which controls the analysis. Most studies can be analysed with this alone.  This is the master script, which controls the analysis. Most studies can be analysed with this alone.
Line 105: Line 104:
 ||<^>''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||
||<^>4 ||<^>Setting study specific details ||<^>(1.0) Always||
||<^>5 ||<^>Set any other parameters that need to differ from the defaults ||<^>(0.6) If you wish to change single parameters||
||<^>6 ||<^>Calling aa_doprocessing to do the processing[[BR]] ||<^>(0.01) Usually never||
 . ||<style="vertical-align: top;">''Section'' ||<style="vertical-align: top;">''Probability you need to change it and when'' ||



||<style="vertical-align: top;"
>1 ||<style="vertical-align: top;">Choosing a recipe ||<style="vertical-align: top;">(0.2) If you use a non-standard acquisition sequence or wish to do a quite different type of analysis ||
||<style="vertical-align: top;">2 ||<style="vertical-align: top;">Changing any of the parameter sets in the recipe ||<style="vertical-align: top;">(0.1) If you wish to change a single parameter set controlling part of the automatic processing from what is specified in a recipe ||
||<style="vertical-align: top;">3 ||<style="vertical-align: top;">Initialising using the parameter sets ||<style="vertical-align: top;">(0.01) Usually never ||
||<style="vertical-align: top;">4 ||<style="vertical-align: top;">Setting study specific details ||<style="vertical-align: top;">(1.0) Always ||
||<style="vertical-align: top;">5 ||<style="vertical-align: top;">Set any other parameters that need to differ from the defaults ||<style="vertical-align: top;">(0.6) If you wish to change single parameters ||
||<style="vertical-align: top;">6 ||<style="vertical-align: top;">Calling aa_doprocessing to do the processing[[BR]] ||<style="vertical-align: top;">(0.01) Usually never||

Line 114: Line 118:
Line 117: Line 120:
Line 124: Line 126:
Line 129: Line 130:
Line 132: Line 132:
% General auto TR recipe; slice order Siemens product sequence default  % General auto TR recipe; slice order Siemens product sequence default
Line 136: Line 136:
Line 139: Line 138:
  % do this here
 . % do this here
Line 146: Line 144:
Line 151: Line 148:
  % The study directory   . % The study directory
Line 155: Line 152:
  % Add subjects and session numbers for EPI data  . % Add subjects and session numbers for EPI data
Line 161: Line 158:
 % Condition names for each session, must be same for all subjects  . % Condition names for each session, must be same for all subjects
Line 165: Line 162:
  % Number of dummy scans at the start of each session  . % Number of dummy scans at the start of each session
Line 169: Line 166:

Line 173: Line 168:
   
Line 180: Line 172:

Line 186: Line 176:




The four sections you are mostly likely to need to change (1, 2, 4 and 5) are now discussed in turn. 
The four sections you are mostly likely to need to change (1, 2, 4 and 5) are now discussed in turn.
Line 196: Line 182:
|| ||aap=''[recipename]''(aap);|| || ||aap=''[recipename]''(aap); ||

Line 199: Line 187:
Line 202: Line 189:

||''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||
||''Name: '' || ||aarecipe_general ||
||''Description:'' ||Standard automatic TR recipe ||
||''Parameter set choice: '' || ||
||<style="vertical-align: top;">''Type'' ||<style="vertical-align: top;">''Parameter set'' ||
||<style="vertical-align: top;">directory_conventions ||<style="vertical-align: top;">aap_directory_conventions_ver00 ||
||<style="vertical-align: top;">options ||<style="vertical-align: top;">aap_options_ver00 ||
||<style="vertical-align: top;">tasklist ||<style="vertical-align: top;">aap_tasklist_cbudefault_ver00 ||
||<style="vertical-align: top;">spmanalysis ||<style="vertical-align: top;">aap_spmanalysis_tr1p1_ver00 ||
||<style="vertical-align: top;">acq_details ||<style="vertical-align: top;">aap_acq_details_ver00 ||
Line 218: Line 204:
|| ||aap.recipe.directory_conventions=’aap_directory_conventions_mynewstyle’|| || ||aap.recipe.directory_conventions=’aap_directory_conventions_mynewstyle’ ||

Line 223: Line 211:

||<^>''Type'' ||<^>''Description''||
||<^>directory_conventions ||<^>Specifies directory and file conventions, for example:[[BR]]- directory names for each subject (4d_files, proc_fieldmaps etc.)[[BR]]- raw data directory (by default /cbu/wbic_data)[[BR]]||
||<^>options ||<^>General aa program options, for example:[[BR]]- whether to automatically identify the field maps and SPGR in the incoming dataset[[BR]]- 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:[[BR]]- TR & slice acquisition time[[BR]]- smoothing FWHM[[BR]]- evolution time of fieldmaps||
||<^>acq_details ||<^>Acquisition details. Several of the defaults are overridden in the user script, for example:[[BR]]- study directory[[BR]]- subject list||
||<style="vertical-align: top;">''Type'' ||<style="vertical-align: top;">''Description'' ||
||<style="vertical-align: top;">directory_conventions ||<style="vertical-align: top;">Specifies directory and file conventions, for example:[[BR]]- directory names for each subject (4d_files, proc_fieldmaps etc.)[[BR]]- raw data directory (by default /cbu/wbic_data)[[BR]] ||
||<style="vertical-align: top;">options ||<style="vertical-align: top;">General aa program options, for example:[[BR]]- whether to automatically identify the field maps and SPGR in the incoming dataset[[BR]]- whether to copy structurals to the central store ||
||<style="vertical-align: top;">tasklist ||<style="vertical-align: top;">The list of tasks to be performed (e.g., modules to be executed) for each study ||
||<style="vertical-align: top;">spmanalysis ||<style="vertical-align: top;">SPM & imaging analysis parameters, for example:[[BR]]- TR & slice acquisition time[[BR]]- smoothing FWHM[[BR]]- evolution time of fieldmaps ||
||<style="vertical-align: top;">acq_details ||<style="vertical-align: top;">Acquisition details. Several of the defaults are overridden in the user script, for example:[[BR]]- study directory[[BR]]- subject list ||

Line 234: Line 223:

||<^>aap.acq_details.root = '/cbu/scratch2/rhodri.cusack/newsimultaneous';[[BR]] ||<^>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'};[[BR]] ||<^>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;[[BR]] ||<^>Number of dummy scans at the start of each session that need to be thrown away.||
||<style="vertical-align: top;">aap.acq_details.root = '/cbu/scratch2/rhodri.cusack/newsimultaneous';[[BR]] ||<style="vertical-align: top;">Specifies the directory where the processed study data are stored. This directory should exist before you run the script.||
||<style="vertical-align: top;">aap.acq_details.sessions={'ns1_block1','ns1_block2','ns2_passive','ns2_active'};[[BR]] ||<style="vertical-align: top;">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.||
||<style="vertical-align: top;">aap.acq_details.numdummies=18;[[BR]] ||<style="vertical-align: top;">Number of dummy scans at the start of each session that need to be thrown away.||
Line 243: Line 232:
Line 245: Line 233:
Line 253: Line 240:
aap.directory_conventions.rawdatadir='/imaging/rhodri/newsimultaneous';    aap.directory_conventions.rawdatadir='/imaging/rhodri/newsimultaneous';
Line 257: Line 243:
Line 262: Line 247:
|| ||aap.spm.defaults.normalise.write.vox=[3 3 3];|| || ||aap.spm.defaults.normalise.write.vox=[3 3 3]; ||

Line 266: Line 253:
=  Everyday tasks = = Everyday tasks =
Line 271: Line 258:
|| ||>> aa|| || ||>> aa ||

Line 290: Line 279:
|| ||cd /cbu/scratch2/rhodri.cusack/mystudydir||
|| ||rm done_aamod_studyinit||
|| ||cd /cbu/scratch2/rhodri.cusack/mystudydir ||
|| ||rm done_aamod_studyinit ||
Line 301: Line 291:
|| ||cd /cbu/scratch2/rhodri.cusack/mystudydir||
|| ||cd W030511.ls1||
|| ||rm done_aamod_realign||
[[Anchor(s)]]
=  Pitfalls - beware! =
|| ||cd /cbu/scratch2/rhodri.cusack/mystudydir ||
|| ||cd W030511.ls1 ||
|| ||rm done_aamod_realign ||


[[Anchor(s)]]
= Pitfalls - beware! =
Line 308: Line 300:
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.   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.
Line 314: Line 305:
Line 317: Line 307:
||<^>''Name'' ||<^>''File directory'' ||<^>''Description''||
||<^>diagnostic_aamod_ana4dto3d_rawmean ||<^>Session ||<^>raw mean as generated by ana4dto3d||
||<^>diagnostic_aamod_ana4dto3d_rawvar ||<^>Session ||<^>raw variance as generated by ana4dto3d||
||<^>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||
 
||<style="vertical-align: top;">''Name'' ||<style="vertical-align: top;">''File directory'' ||<style="vertical-align: top;">''Description'' ||
||<style="vertical-align: top;">diagnostic_aamod_ana4dto3d_rawmean ||<style="vertical-align: top;">Session ||<style="vertical-align: top;">raw mean as generated by ana4dto3d ||
||<style="vertical-align: top;">diagnostic_aamod_ana4dto3d_rawvar ||<style="vertical-align: top;">Session ||<style="vertical-align: top;">raw variance as generated by ana4dto3d ||
||<style="vertical-align: top;">diagnostic_aamod_tsdiffana ||<style="vertical-align: top;">Session ||<style="vertical-align: top;">output from tsdiffana ||
||<style="vertical-align: top;">diagnostic_aamod_realign ||<style="vertical-align: top;">Subject ||<style="vertical-align: top;">realignment display from SPM ||
||<style="vertical-align: top;">diagnostic_aamod_undist ||<style="vertical-align: top;">Subject ||<style="vertical-align: top;">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. ||
||<style="vertical-align: top;">diagnostic_aamod_coreg ||<style="vertical-align: top;">Subject ||<style="vertical-align: top;">SPM output from coregistration of structural and undistorted EPI ||
||<style="vertical-align: top;">diagnostic_aamod_norm ||<style="vertical-align: top;">Subject ||<style="vertical-align: top;">SPM output from normalisation ||

http://www.mrc-cbu.cam.ac.uk/~rhodri/aa/aa_topbar.gif

aa release 1.1 Rhodri Cusack, MRC CBU, Cambridge rhodri.cusack [at] mrc-cbu.cam.ac.uk

Acknowledgements: Thank you to Matthew Brett, Jessica Grahn, Daniel Mitchell, Rik Henson & Matt Davis, who have contributed to the code and this manual.

CONTENTS

Table Of Contents

[#s Summary]

[#s Main Features]

[#s System overview]

[#s User script]

[#s4. Overview]

[#s4. Choosing the recipe]

[#s4. Modify parameter set selection]

[#s4. Setting your acquisition parameters]

[#s4. Set specific parameters that you wish to differ from the defaults]

[#s Everyday tasks]

[#s5. Getting ready to use AA]

[#s5. Running an analysis]

[#s5. Restarting an analysis]

[#s5. How do I force an analysis to start all over again?]

[#s5. How do I force an analysis to start from a particular stage?]

[#s Pitfalls - beware!]

[#s6. Check your data]

[#s6. Changing the aa_user script]

[#s Reference]

||

[Anchor(s)]]

Summary

The system automates the analysis of neuroimaging data. This version has been configured to work on data from the Wolfson Brain Imaging Centre, reading Bruker data and analysing it with SPM. It is written in Matlab.

Anchor(s)

Main Features

  • Automatic. Almost completely automatic analysis, currently up to the end of normalisation.

  • Flexible control. Users that are new to neuroimaging don’t get bombarded with options, but are directed to what is essential, while all other settings take sensible defaults. More experienced users can easily change a range of settings, and advanced users can add or replace modules to the system to change any behaviour

  • Restartable. If the users stops the script, or if it crashes (e.g., because of a machine fault, or because the right data aren’t there) then when restarted it will begin at the stage where it left off.

  • Modular. The system is modular at two levels, to make it easy to switch in or out relevant parts.

  • Automatic good citizen behaviour. Field maps and structurals are automatically detected. Structurals are copied to /imaging/local/structurals/cbu automatically by default.

  • Easy to maintain. The code components are stored in a central repository (/cbu/imagers/spm/aa ?) which means that new components can be made available, or existing ones changed in new releases

  • Record keeping. Unlike SPM used from the GUI, the system records exactly which parameters were used, and allows easy recreation of a dataset from the raw data at a later date.

  • Simple interface for new modules. It is easy for Matlab programmers to write new modules and incorporate them into the processing stream.

Anchor(s)

System overview

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

In overall control. Selects a recipe, adds study specific information, and changes any defaults

User's directory

Beginner

Recipes

Specifies which parameter sets to use

Centrally

Beginner/ Intermediate

Parameter sets

Set default parameters. There are five different basic types of parameter set

Centrally

Intermediate

Modules

Run individual stages of processing

Centrally

Advanced

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. Anchor(s)

User script

Anchor(s4.)

4. Overview

This is the master script, which controls the analysis. Most studies can be analysed with this alone.

There are 6 sections to the user script:

  • ||<style="vertical-align: top;">

    Section ||<style="vertical-align: top;">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

4

Setting study specific details

(1.0) Always

5

Set any other parameters that need to differ from the defaults

(0.6) If you wish to change single parameters

6

Calling aa_doprocessing to do the processingBR

(0.01) Usually never

An example, which will process 3 subjects each with 4 sessions up to and including normalisation is below:

An example, which will process 3 subjects each with 4 sessions up to and including normalisation is below:

% Automatic analysis

% User master script

% Rhodri Cusack MRC CBU Cambridge 2005

% (1) RESET ALL PARAMETERS

aap=[];

% (2) ANALYSIS RECIPE

% General auto TR recipe; slice order Siemens product sequence default

aap=aarecipe_general(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 = '/home/rhodri/pvs/cbu';

  • % Add subjects and session numbers for EPI data

aap=aas_addsubject(aap,'*CBU050011/*',[5 11]);

aap=aas_addsubject(aap,'*CBU050012/*',[4 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;

% (6) 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, 4 and 5) are now discussed in turn.

Anchor(s4.)

4. 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 in the “Reference” section.

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

Anchor(s4.)

4. 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 Error! Reference source not found.) with a line like

aap.recipe.directory_conventions=’aap_directory_conventions_mynewstyle’

(NB: no ‘.m’ on end)

There are 5 different types of parameter sets. A full list of the available parameter sets is given in the “Reference” section.

Type

Description

directory_conventions

Specifies directory and file conventions, for example:BR- directory names for each subject (4d_files, proc_fieldmaps etc.)BR- raw data directory (by default /cbu/wbic_data)BR

options

General aa program options, for example:BR- whether to automatically identify the field maps and SPGR in the incoming datasetBR- 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:BR- TR & slice acquisition timeBR- smoothing FWHMBR- evolution time of fieldmaps

acq_details

Acquisition details. Several of the defaults are overridden in the user script, for example:BR- study directoryBR- subject list

Anchor(s4.)

4. 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';BR

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'};BR

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;BR

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, ‘*CBU050011\*’,[5 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 mank 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.

Anchor(s4.)

4. 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.

Anchor(s)

Everyday tasks

Anchor(s5.)

5. Getting ready to use AA

Once you’ve started a Matlab/SPM session, type

>> aa

at the Matlab prompt to add the automatic analysis paths

Anchor(s5.)

5. 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

Anchor(s5.)

5. Restarting an analysis

To restart an analysis, just type the script name again. It will start from where it left off.

Anchor(s5.)

5. 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 /cbu/scratch2/rhodri.cusack/mystudydir

rm done_aamod_studyinit

Anchor(s5.)

5. 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 /cbu/scratch2/rhodri.cusack/mystudydir

cd W030511.ls1

rm done_aamod_realign

Anchor(s)

Pitfalls - beware!

Anchor(s6.)

6. 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_ana4dto3d_rawmean

Session

raw mean as generated by ana4dto3d

diagnostic_aamod_ana4dto3d_rawvar

Session

raw variance as generated by ana4dto3d

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

Anchor(s6.)

6. Changing the aa_user script

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.

Anchor(s)

CbuImaging: AutomaticAnalysisManual (last edited 2013-03-07 21:24:14 by localhost)