Size: 11412
Comment:
|
Size: 19049
Comment:
|
Deletions are marked like this. | Additions are marked like this. |
Line 8: | Line 8: |
= New in development version = | = New in aa_ver2_devel = == Parallel processing == See the new page AutomaticAnalysisParallel == Changed way task parameters are stored internally == Only relevant if you specify your own tasklist in the user script. Previously, when creating a new tasklist, you needed to put: {{{ % [OLD FORM, FOR aa_ver1.2] aap.tasklist.epiprefix=[]; % reset prefix list aap.tasklist.stages=[]; % reset list of stages % Then specify individual tasks... aap=aas_addtask(aap,'aamod_mytask'); % and so on }}} Now, aap.tasklist.stages is an array of structures, rather than an array of names, so you just need {{{ % [NEW FORM, FOR aa_ver2 onwards] aap.tasklist.stages=[]; % reset list of stages % Then specify individual tasks... aap=aas_addtask(aap,'aamod_mytask'); % and so on }}} I have done this because there were an increasing number of options associated with a stage (stages, epiprefix, tobecompleted, extraparameters) and having lots of separate lists is clumsy and inelegant An error will be generated if you leave the old epiprefix line in. '''Author:''' Rhodri Cusack == Improvements to first level statistical modelling module (aamod_firstlevel_model) == === Automatic insertion of correct time bin === Uses reference slice (from aap.spmanalysis.refslice) and slice order (from aap.spmanalysis.sliceorder) to calculate correct value for time bin (SPM.xBF.T0) parameter, assuming that your stimulus timings are measured relative to the start of each volumes (e.g., onset value "0" in model corresponds to start of first volume). '''Author:''' Rhodri Cusack with Rik Henson === Option to switch off masking === By default, data are truncated around the edge of the brain, where the EPI intensity is less than a fixed proportion of the mean. This can occasionally mask interesting effects near the surface of cortex. This is controlled by SPM.xM.TH and SPM.xM.I. Default is {{{ aap.spmanalysis.firstlevelmasking=1; }}} but add to your user script... {{{ aap.spmanalysis.firstlevelmasking=0; }}} ...to switch masking off '''Author:''' Rhodri Cusack with Daniel Mitchell === Option to control whether movement parameters are added to your model === Default is {{{ aap.spmanalysis.firstlevelmovementparameters=1; }}} Add to your user script... {{{ aap.spmanalysis.firstlevelmovementparameters=1; }}} to not add movement parameters '''Author:''' Rhodri Cusack === Optional extra parameter to specify output directory for model === I always find I need to run several models on each study. Previously, it was necessary to write a different user script for each one, as the singlesubj_stats and rfx_stats directories specifying the output names for the model directories could only have one value per aap structure (they were stored in aap.directory_conventions). I have made a new system to more elegantly manage this. Here is how it works: (1) Choose a recipe >without< a model (e.g., aarecipe_general_v02) (2) Copy aamod_firstlevel_model and aamod_firstlevel_contrasts from the aa modules directory (find by typing which aamod_firstlevel_model at matlab prompt) to the same directory as your user script and modify them to reflect your particular experiment. Also, you might want to change their names to describe the particular model (3) Assuming you changed their names to aamod_firstlevel_model_1_basic and aamod_firstlevel_contrasts_1_basic, use this chunk of code before the aa_doprocessing command in your user script: {{{ analysisname='1_basic'; clear myextraparams myextraparams.stats_suffix=analysisname; aap=aas_addtask(aap,['aamod_firstlevel_model_' analysisname],'swar',[],myextraparams); aap=aas_addtask(aap,['aamod_firstlevel_contrasts_' analysisname],[],[],myextraparams); aap=aas_addtask(aap,'aamod_secondlevel_model',[],[],myextraparams); }}} The optional fifth option in aas_addtask, here passed "myextraparams", provides extra details to the module. These may change if a module is called repeatedly with different input, for example. The three modules used here all accept a "stats_suffix" field, which will be added to the end of the directory name for the first or second level model. == Option to average across structurals when there is more than one == Put this in your user script {{{ aap.options.autoidentifystructural_average=1; }}} Structurals will be coregistered to the first structural and then averaged. '''Author:''' Rhodri Cusack with Elisabeth von dem Hagen == New recipe and example user scripts for dual echo == The new recipe aarecipe_dualecho_noslicetiming_ver01 (see AutomaticAnalysisRecipes) has been written for the dual echo sequence. Morgan also kindly provided aa_user_dualecho_GE and aa_user_dualecho_SE, which are in the examples directory '''Authors:''' Karen Taylor and Morgan Barense == Raw data prefix moved out of individual tasklists == Instead of the prefix for the raw data ('f' before) being incorporated into the prefix list part of the tasklist parameter set, it is now stored (together with 'CBU') in the directory_conventions parameter set '' aap.directory_conventions.rawdataafterconversionprefix='fCBU';'' This has two advantages (1) It is easy to change the 'f' into an 's' for use with the dual echo data - put in your user script: '' aap.directory_conventions.rawdataafterconversionprefix='sCBU';'' (2) The 'CBU' part can be modified easily by those from other sites. '''Author:''' Rhodri Cusack == Added facility for specifying series by position in file listing rather than filtering by name == Data from our scanner typically is named something like "Series_001_..." and so on. The number has been used to filter the data. The dual echo sequence puts the acquisition date & time instead of "001". You may now specify '' aap.directory_conventions.rawseries_usefileorder=1;'' to ask for raw series to be referred to by their order in file listing instead of name. This applies both for the ouput of aamod_autoidentifyseries* and for your EPI series specifications for each session. '''Author:''' Rhodri Cusack == Pick particular echoes == You may make the epi conversion routines and any subsequent stages of processing that use aas_getimages (all supplied modules) be specific to particular echoes. For our typical dual echo sequence, echo 1 is a gradient echo and echo 2 a spin echo. Put '' aap.directory_conventions.selectechonumbers=1; '' and then '' aap.acq_details.sessions_echonumbers=[1 2 1]; % for three sessions '' where this example is for a study with 3 "sessions". The first will be a gradient echo, the second a spin echo, and the third a gradient echo. The first two would possibly refer to the same acquisition run, but pick out different echoes. Note, you should be aware that it is theoretically possible that some stages of processing (motion correction?) will not take kindly to being supplied mixed images. If you are concerned about this, you should conduct completely separate GE & SE AA analyses (e.g., separate user scripts and output directories), one with all sessions_echonumbers as 1, the other all 2. '''Author:''' Rhodri Cusack == DICOM conversion now operates in chunks of 128 dicom files == This stops it creashing with the obscene number of files generated by non-mosaic format EPI (10000+ files per time series) '''Author:''' Rhodri Cusack = New in aa_ver12 = == Option to pick only last structural when there are multiple MPRAGEs == Put this in your user script aap.options.autoidentifystructural_chooselast=1; |
Line 46: | Line 196: |
'''Author:''' Rhodri Cusack |
|
Line 50: | Line 202: |
'''Authors:''' Doris Eckstein | '''Author:''' Doris Eckstein |
Line 64: | Line 217: |
'''Author:''' Rhodri Cusack |
Include(AutomaticAnalysisTopbar)
Contents TableOfContents
New in aa_ver2_devel
Parallel processing
See the new page AutomaticAnalysisParallel
Changed way task parameters are stored internally
Only relevant if you specify your own tasklist in the user script. Previously, when creating a new tasklist, you needed to put:
% [OLD FORM, FOR aa_ver1.2] aap.tasklist.epiprefix=[]; % reset prefix list aap.tasklist.stages=[]; % reset list of stages % Then specify individual tasks... aap=aas_addtask(aap,'aamod_mytask'); % and so on
Now, aap.tasklist.stages is an array of structures, rather than an array of names, so you just need
% [NEW FORM, FOR aa_ver2 onwards] aap.tasklist.stages=[]; % reset list of stages % Then specify individual tasks... aap=aas_addtask(aap,'aamod_mytask'); % and so on
I have done this because there were an increasing number of options associated with a stage (stages, epiprefix, tobecompleted, extraparameters) and having lots of separate lists is clumsy and inelegant
An error will be generated if you leave the old epiprefix line in.
Author: Rhodri Cusack
Improvements to first level statistical modelling module (aamod_firstlevel_model)
Automatic insertion of correct time bin
Uses reference slice (from aap.spmanalysis.refslice) and slice order (from aap.spmanalysis.sliceorder) to calculate correct value for time bin (SPM.xBF.T0) parameter, assuming that your stimulus timings are measured relative to the start of each volumes (e.g., onset value "0" in model corresponds to start of first volume).
Author: Rhodri Cusack with Rik Henson
Option to switch off masking
By default, data are truncated around the edge of the brain, where the EPI intensity is less than a fixed proportion of the mean. This can occasionally mask interesting effects near the surface of cortex. This is controlled by SPM.xM.TH and SPM.xM.I. Default is
aap.spmanalysis.firstlevelmasking=1;
but add to your user script...
aap.spmanalysis.firstlevelmasking=0;
...to switch masking off Author: Rhodri Cusack with Daniel Mitchell
Option to control whether movement parameters are added to your model
Default is
aap.spmanalysis.firstlevelmovementparameters=1;
Add to your user script...
aap.spmanalysis.firstlevelmovementparameters=1;
to not add movement parameters
Author: Rhodri Cusack
Optional extra parameter to specify output directory for model
I always find I need to run several models on each study. Previously, it was necessary to write a different user script for each one, as the singlesubj_stats and rfx_stats directories specifying the output names for the model directories could only have one value per aap structure (they were stored in aap.directory_conventions).
I have made a new system to more elegantly manage this. Here is how it works: (1) Choose a recipe >without< a model (e.g., aarecipe_general_v02) (2) Copy aamod_firstlevel_model and aamod_firstlevel_contrasts from the aa modules directory (find by typing which aamod_firstlevel_model at matlab prompt) to the same directory as your user script and modify them to reflect your particular experiment. Also, you might want to change their names to describe the particular model (3) Assuming you changed their names to aamod_firstlevel_model_1_basic and aamod_firstlevel_contrasts_1_basic, use this chunk of code before the aa_doprocessing command in your user script:
analysisname='1_basic'; clear myextraparams myextraparams.stats_suffix=analysisname; aap=aas_addtask(aap,['aamod_firstlevel_model_' analysisname],'swar',[],myextraparams); aap=aas_addtask(aap,['aamod_firstlevel_contrasts_' analysisname],[],[],myextraparams); aap=aas_addtask(aap,'aamod_secondlevel_model',[],[],myextraparams);
The optional fifth option in aas_addtask, here passed "myextraparams", provides extra details to the module. These may change if a module is called repeatedly with different input, for example. The three modules used here all accept a "stats_suffix" field, which will be added to the end of the directory name for the first or second level model.
Option to average across structurals when there is more than one
Put this in your user script
aap.options.autoidentifystructural_average=1;
Structurals will be coregistered to the first structural and then averaged.
Author: Rhodri Cusack with Elisabeth von dem Hagen
New recipe and example user scripts for dual echo
The new recipe aarecipe_dualecho_noslicetiming_ver01 (see AutomaticAnalysisRecipes) has been written for the dual echo sequence.
Morgan also kindly provided aa_user_dualecho_GE and aa_user_dualecho_SE, which are in the examples directory
Authors: Karen Taylor and Morgan Barense
Raw data prefix moved out of individual tasklists
Instead of the prefix for the raw data ('f' before) being incorporated into the prefix list part of the tasklist parameter set, it is now stored (together with 'CBU') in the directory_conventions parameter set
aap.directory_conventions.rawdataafterconversionprefix='fCBU';
This has two advantages (1) It is easy to change the 'f' into an 's' for use with the dual echo data - put in your user script:
aap.directory_conventions.rawdataafterconversionprefix='sCBU';
(2) The 'CBU' part can be modified easily by those from other sites.
Author: Rhodri Cusack
Added facility for specifying series by position in file listing rather than filtering by name
Data from our scanner typically is named something like "Series_001_..." and so on. The number has been used to filter the data.
The dual echo sequence puts the acquisition date & time instead of "001".
You may now specify
aap.directory_conventions.rawseries_usefileorder=1;
to ask for raw series to be referred to by their order in file listing instead of name. This applies both for the ouput of aamod_autoidentifyseries* and for your EPI series specifications for each session.
Author: Rhodri Cusack
Pick particular echoes
You may make the epi conversion routines and any subsequent stages of processing that use aas_getimages (all supplied modules) be specific to particular echoes. For our typical dual echo sequence, echo 1 is a gradient echo and echo 2 a spin echo.
Put
aap.directory_conventions.selectechonumbers=1;
and then
aap.acq_details.sessions_echonumbers=[1 2 1]; % for three sessions
where this example is for a study with 3 "sessions". The first will be a gradient echo, the second a spin echo, and the third a gradient echo. The first two would possibly refer to the same acquisition run, but pick out different echoes.
Note, you should be aware that it is theoretically possible that some stages of processing (motion correction?) will not take kindly to being supplied mixed images. If you are concerned about this, you should conduct completely separate GE & SE AA analyses (e.g., separate user scripts and output directories), one with all sessions_echonumbers as 1, the other all 2.
Author: Rhodri Cusack
DICOM conversion now operates in chunks of 128 dicom files
This stops it creashing with the obscene number of files generated by non-mosaic format EPI (10000+ files per time series)
Author: Rhodri Cusack
New in aa_ver12
Option to pick only last structural when there are multiple MPRAGEs
Put this in your user script
aap.options.autoidentifystructural_chooselast=1;
Additional parameters can be passed to realignment/slicetime correction
Description: You can now pass extra parameters to aamod_realign and aamod_slicetiming via the aap.spmanalysis fields:
|
|
aap.spmanalysis.reslicewhich |
% 0 = do not reslice any image (CBU default) |
|
% 1 = do not reslice first image (if realigned to first) |
|
% 2 = reslice all images (e.g, if want to perform slicetiming after realignment) |
aap.spmanalysis.writemean |
% 1 = write mean (default), 0 = do not |
aap.spmanalysis.refslice |
% reference slice for slicetiming correction (CBU default=1) |
Also, more of the standard SPM defaults apply to aamod_realign (rather than being hard-coded in aamod_realign).
Authors: Rik Henson, Doris Eckstein
Changed source of EPI file prefix
Previously, a single parameter allowed changing of the EPI file prefixes that were looked for, so that slice timing could be included or not. This was the aap.directory_conventions.forrealign_fileprefix, which as either 'f' for no slice timing or 'af' if slice timing was used. It was appended by realign and all subsequent modules.
This did not allow much flexibility for other stages to be included (e.g., realign & unwarp, which adds 'u') or for slice timing to be shifted to after realignment.
I have now moved the file prefixes to the 'tasklist' parameter list, which is where it really belongs. Instead of one long list, tasks are now added using the new aas_addtask command. For stages that take EPI input, the aas_addtask command can optionally include a third parameter that specifies the prefix of the EPIs for this stage. So, a section of a typical tasklist specification ends looks like this:
aap=aas_addtask(aap,'aamod_realignunwrap','f'); aap=aas_addtask(aap,'aamod_slicetiming','uf'); aap=aas_addtask(aap,'aamod_coreg_noss','auf'); aap=aas_addtask(aap,'aamod_norm_noss','auf'); aap=aas_addtask(aap,'aamod_norm_write','auf'); aap=aas_addtask(aap,'aamod_smooth','wauf');
Hopefully, this provides much more flexibility for stage reordering, or additional stages.
Author: Rhodri Cusack
Changed .mat file for normalisation
Description: Changed name of _sn.mat and _sn_inv.mat files produced by normalisation to ms* instead of s* to reflect their origin in second pass
Author: Doris Eckstein
New recipes
The default processing stream has changed in the new "general" recipes, with slice timing now AFTER realignment. This is thought to be better if slices have been acquired in a sequential rather than interleaved order. The files have also been tidied up. There is a full description of the recipes and of some issues in choosing an appropriate recipe on this new page AutomaticAnalysisRecipes.
Conversion of aribitrary special series
New aa mechanism for converting arbitrary series: - add fifth parameter to aas_addsubject command specifying series to be converted - use recipe
- aarecipe_notforfmri_ver00
They'll be converted and put in [subjectdir]/specialseries
See example in /imaging/local/spm/aa/aa_ver1_devel/examples/aa_user_notforfmri.m
Author: Rhodri Cusack
New in version 1.1
Thanks to Danny Mitchell, Rik Henson, Matt Davis & Adam Hampshire, who all contributed to this release.
You may download a PDF of a brief introduction given at the IIG on 5 June 2006 here: http://www.mrc-cbu.cam.ac.uk/~rhodri/aa/iig_may2006_aanewfeatures.pdf
tsdiffana added to pipeline
Description: This was removed in the SPM5 aa ver 1. It has been added back in. tsdiffana time series variance tool run by default, output saved to "diagnostic_aamod_tsdiffana.jpg" Components: aamod_tsdiffana Authors: DM
normalisation using segment
Description: In SPM5, the "segment" tool can be used to normalise, and has been reported to work better. However, we found it to be unstable on our structural images, due an inhomogeneity in brightness across them, a probably result of spatial variations in sensitivity in the 12 channel coil we are using. So, this version implements a two pass process: a first pass to correct the inhomogeneity, and a second pass to do the normalisation. Components: aamod_norm_noss, aamod_norm_write Authors: RH, DM, RC
support for sparse imaging
Description: Interpolation across time in slice timing makes no sense with sparse imaging, where scans are far apart. This recipe has this stage removed. Components: minor changes to modules, new recipes Authors: MD
aa_report
Description: Produces an HTML summary of various diagnostic images. This tool is still under development. Components:aa_report Authors: RC
second level statistics
Description: This module trawls through your first level analyses and generates second level analyses of a one sample t-test for each first level contrast found. The contrast names and order must the same for all subjects or an error will be given. Components: aamod_model_secondlevel Authors: RC, RH
first level statistics
Description: This sets up a model for the single subject, first level event modelling. You will need to make a copy of this module to your aa directory and modify it to specify the particular design you ran. See the aa website for instructions on how to modify it. Components: aamod_model_firstlevel Authors: AH, RC
first level contrasts
Description: Runs contrasts on each subject at the first level. You will need to make a copy of this module to your aa directory and modify it to specify the particular design you ran. See the aa website for instructions on how to modify it. Components: aamod_contrasts Authors: AH, RC
modified shell calls so that it works in desktop
Description: When the Matlab Desktop is used with Matlab 6+7, an error is generated at the top of all shell calls (see http://www.mathworks.com/support/solutions/data/1-18DNL.html?solution=1-18DNL ). I've replaced all "unix" calls in the Matlab code with a call to a new wrapper script, aas_shell. This traps the error, taking off all lines that start with tcsh: from the top of the response. I did it this way to avoid the complication of having people change their .cshrc file. Components: aas_shell Authors: RC
New in version 1.0
2006/2/14 [Siemens data/ SPM5/ Nifti-1 data format]
new recipes, in "examples" directory, including the following
aa_user_general_ver01 no skull stripping; uses segment not normalise [some problems have been reported with this route, if the structural fails to coregister properly with the template in the initial affine registration stage of segment. If you use it, make sure you check the final warped images are well registered with the MNI template] aa_user_general_ver00 automatic TR detection
Automatic identification and processing of realtime T maps by default
aas_addsubject command to make it easier to tie up subject name and session numbers by eye
wildcards now allowed when specifying subject names
NIFTI-1 neuroimaging data format used throughout
Conversion from Siemens DICOM data format by default; pvconv.pl, ana4dto3d no longer used
Recognises MPRAGE and GRE_FIELDMAPPING for anatomical and fieldmap data
Execution times stored by default. aa_benchmark command displays a summary.
No fieldmap undistortion at present
New in version 0.5
2006/2/14 [Bruker data/ SPM2/ Analyze data format]
benchmarking facility - after you've run an analysis type aa_benchmark or aa_benchmark('study path') to get a breakdown of execution times
if more than one structural is present in the central store matching the subject name, the first is now chosen
New in version beta 0.4
2004/12/3
I've released a new version of aa and made it the default at the CBU. See the note below about tsdiffana if you're going to re-run an old analysis user script with this new version.
The new diagnostic jpegs make it easy to follow through how your automatic SPM analysis has gone. I hope this is useful! Rhodri
***aa beta 0.4: NEW FEATURES * added automatic saving of parameters sets and version number * added automatic saving of automatically identified series so that re-running is faster * added system for modifying CBU SPM defaults from within your user script with lines like aap.spm.defaults.normalise.write.vox=[3 3 3]; * improved error trapping for problems with pvconv.pl: now spots "not reconstructed" error and quits with a warning at this stage * added copying of .mat file during skull stripping * fixed problem so that if one subject is forcefully re-run (by deleting "done" flag) only this subject and not all the others will be run on subsequent stages * added new generation of diagnostic JPEG files as listed below. * added tsdiffana to processing pipeline Note that due to the addition of tsdiffana early in the pipeline, if you run an old aa_user script with the new version, it will rerun all stages after tsdiffana (e.g., most of the analysis). If you don't want this, either use the old version of aa by launching it with >> aa_ver0.3_beta or add the following line to your aa_user script: % list of tasks to perform (no tsdiffana) aap.tasklist.stages={'aamod_study_init','aamod_newsubj_init','aamod_copyfieldmaps', ... 'aamod_pvconv', 'aamod_copystructural','aamod_ana4dto3d', ... 'aamod_slicetiming','aamod_realign','aamod_undist','aamod_coreg', ... 'aamod_norm','aamod_undist_reslice'}; Thanks to Andy Lee for help with some of these features.
***DIAGNOSTIC JPEGS 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 New in version beta 0.3
2004/11/9
PROBLEMS & FIXES (1) Problem in automatically identifying sessions in some datasets. This was due to an error message displayed by pvshow.pl. I've made the scripts handle these error messages more elegantly - you now get a warning but processing continues. If it can't find the sessions an error will still be generated. (2) The slice timing was set incorrectly in the default recipe, to 0.076 instead of 0.05. I'm sorry for this one - I've corrected it. This will effect rapid event-related designs in particular. Thanks to Andy Lee for spotting this.