AutomaticAnalysisVersions - MRC CBU Imaging Wiki
location: AutomaticAnalysisVersions


Contents

Contents

  1. How to launch different versions
  2. New in development version aa_ver2_devel
  3. New in version aa version 2.1
  4. New in aa version 2.0
    1. Parallel processing
    2. Changed way task parameters are stored internally
    3. Improvements to first level statistical modelling module (aamod_firstlevel_model)
      1. Automatic insertion of correct time bin
      2. Option to switch off masking
      3. Option to control whether movement parameters are added to your model
      4. Optional extra parameter to specify output directory for model
    4. Option to average across structurals when there is more than one
    5. New recipe and example user scripts for dual echo
    6. Raw data prefix moved out of individual tasklists
    7. Added facility for specifying series by position in file listing rather than filtering by name
    8. Small changes to recipes
    9. Pick particular echoes
    10. DICOM conversion now operates in chunks of 128 dicom files
  5. New in aa version 1.2
    1. Option to pick only last structural when there are multiple MPRAGEs
    2. Additional parameters can be passed to realignment/slicetime correction
    3. Changed source of EPI file prefix
    4. Changed .mat file for normalisation
    5. New recipes
    6. Conversion of aribitrary special series
  6. New in version 1.1
    1. tsdiffana added to pipeline
    2. normalisation using segment
    3. support for sparse imaging
    4. aa_report
    5. second level statistics
    6. first level statistics
    7. first level contrasts
    8. modified shell calls so that it works in desktop
  7. New in version 1.0
    1. new recipes, in "examples" directory, including the following
    2. Automatic identification and processing of realtime T maps by default
    3. aas_addsubject command to make it easier to tie up subject name and session numbers by eye
    4. wildcards now allowed when specifying subject names
    5. NIFTI-1 neuroimaging data format used throughout
    6. Conversion from Siemens DICOM data format by default; pvconv.pl, ana4dto3d no longer used
    7. Recognises MPRAGE and GRE_FIELDMAPPING for anatomical and fieldmap data
    8. Execution times stored by default. aa_benchmark command displays a summary.
    9. No fieldmap undistortion at present
  8. New in version 0.5
    1. benchmarking facility - after you've run an analysis type aa_benchmark or aa_benchmark('study path') to get a breakdown of execution times
    2. if more than one structural is present in the central store matching the subject name, the first is now chosen
  9. New in version beta 0.4


How to launch different versions

Into the SPM/Matlab window, or in your scripts, add the following command. Development versions are where bug fixes and new features will first appear, but may occasionally be unstable.

Command

Launches

aa_ver2_devel

aa version 2 development version

aa_ver2

latest aa version 2.x (currently 2.1)

aa_ver21

aa version 2.1

aa_ver20

aa version 2.0

aa_ver1

latest aa version 1.x (always 1.2)

aa_ver12

aa version 1.2

aa_ver11

aa version 1.1

aa_ver10

aa version 1.0

aa_ver05

the last version for Bruker data

New in development version aa_ver2_devel

New in version aa version 2.1

Various bug fixes and changes to parallel engine.

Added a new recipe:

  • aarecipe_sparse_ver01

for sparse imaging - as aarecipe_general_ver02 except no slice timing [RC/AH]

  • Modified aamod_norm_write to also find normalisation parameter files (*_sn.mat) with 's' prefix

(for those not using 2-pass method). [JG]

New in aa version 2.0

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=0;

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

Small changes to recipes

All of the tasklists of the common recipes have been modified to provide dependency information in the "to be completed first" field. In addition, for the recipes that include slice timing after realignment, I have made coregistration work on the output of realignment rather than waiting for slice timing to finish. This relies upon slice timing have little effect on the mean, which as it is a form of temporal resampling, will be almost exact.

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 version 1.2

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.

aa is now used by http://www.cambridgeneuroimaging.com

CbuImaging: AutomaticAnalysisVersions (last edited 2013-03-07 21:23:00 by localhost)