Automatic analysis (aa)

Automatic analysis (aa) is a pipeline system for neuroimaging, written in Matlab. It supports SPM 5/8 and some functions from FSL.

For more information see:

• Version 2.2 and earlier: Manual

• Version 4:

  • This page

  • GitHub

  • Wiki

Any problems, report them to Danny Mitchell (version 2 and 3) or Tibor Auer (version 4).

Paths to aa

Different versions live in:

• legacy versions (0.1beta - 2.0) - unsupported

  • /imaging/local/spm/aa/aa-ver0.1_beta

  • /imaging/local/spm/aa/aa-ver0.2_beta

  • ...

• old versions (2.2 - 4.beta)

  • /imaging/local/spm/aa_svn_new/versions/release-2.2

  • /imaging/local/spm/aa_svn_new/versions/release-3.0

  • ...

• new version (4.0 - 4.1) (based on the latest devel-share branch from GitHub)

  • /imaging/local/software/AA/release-4.0

  • /imaging/local/software/AA/release-4.1 - recommended

Using aa

Configuration

Before running aa you need to add the corresponding path to MATLAB Path:

• File/Set Path...

• addpath('path_to_aa');
  aa_ver4_nocloud; % adds aa subfolders to the path
  savepath;
  

To avoid version conflicts make sure that it is added to the top of the Path. It is even more important that path_to_aa/extrafunctions/spm_mods is on the top (of SPM's paths), so modification to the spm may have effect.

Running

MATLAB: You need MATLAB newer than the default (r2009a). Most functions have been tested on MATLAB r2012b, so it must be safe to use.

Then, you need a

• User Master Script (UMS) for fMRI

• User Master Script (UMS) for DARTEL

• User Master Script (UMS) for FreeSurfer

Features

Parallel computing

• Usage
  • To enable parallel computing you have to be logged in an appropriate computing machine (login11-14) and add the following line to your UMS:

  • aap.options.wheretoprocess = 'qsub'; % parallel; typical localsingle
    

  • Because each thread will load the saved MATLAB path, it is very important that it is set and saved correctly before initiating parallel jobs. See Configuration for more information!

• Monitoring

Handling multiple DICOM sources

• Colon-separated-list (CSL) for rawdatadir:
  • The “old” script should work without any changes but the newer ones (based on Recent Update on 2013/09/06) should revert. When multiple sources are defined, use CSL. E.g.:

  • aap.directory_conventions.rawdatadir = ‘/mridata/cbu:/mridata/csl:/mridata/camcan’; 
    % default at the moment (see aap_parameters_defaults_CBSU.xml)
    

Support for NIFTI-4D images

• As a default, NIFTI-3D is set. To enable NIFTI-4D, you have to specify it in the UMS:

• aap.options.NIFTI4D = 1; % 4D support; typical value 0
  

Multi-level interlinked reporting

• Usage

• Based on aap structure

• aa_report(fullfile(aas_getstudypath(aap),aap.directory_conventions.analysisid));
  

• If you are in the analysis folder

• aa_report;
  

• Study (reporting second-level)
• Subjects (each subjects separately)
• Summaries:
  • Subjects
  • Registration
  • First-level thresholded maps

Non-Standard Modules

• FSL

• FreeSurfer

• First-level thresholding
  • List of significant activation maps
  • Overlays on axial slices (T1 MNI)
  • Rendering results in 3D

Advanced Features

Input file

It is possible to specify Subjects, Sessions and Events based on a text file. Required options in aap.acq_details.input (see also aap_parameters_defaults_CBSU.xml):

• list: text file:
  • Required format:

    • a CSV file: cells are separated with semicolon

    • subcells are separated with "_"
    • a header in the first line
  • Required columns (may contain more):
    • "ID": numbers for identifying subjects
    • "FMRI1": cells for the fMRI measurement; it must contain the same number of subcells as the coresponding column header
      • first subcell is the CBU volunteer number (without "CBU")
      • series numbers are defined in the consecutive subcells with the same order as their names in the coresponding column header
  • E.g.:

    • ID	Age	Sex	FMRI1_Loc_Con_LDeasy_LDhard
      02	29	f	90952_7_6_4_5

      As "pure" text:
    • ID;Age;Sex;FMRI1_Loc_Con_LDeasy_LDhard
    • 02;29;f;90952_7_6_4_5
• selected_sessions: subselection of a subset of series:

  • E.g. (based on the example above): [3 4] --> LDeasy and LDhard

• referencedirectory_tmpl: a template for path to the folder containing Event files (.mat files in SPM-format)
  • Required format:

    • must contain "*" which will be substituted withID (see above)

    • E.g.: '/imaging/ta02/ActionWords/Analysis/E-Prime/DAW*/ref'

  • The folder should contain the regressor(s) in SPM format (.mat file) with filename format: condition_vol_ID-Session Name.mat.

    • E.g. (based on the example above): condition_vol_2-LDeasy.mat
• Then you add these lines to your UMS (based on the example above):

• aap.acq_details.input.list='/imaging/ta02/ActionWords/Analysis/Subject_List_Test.csv';
  aap.acq_details.input.selected_sessions = [3 4];
  aap.acq_details.input.referencedirectory_tmpl = '/imaging/ta02/ActionWords/Analysis/E-Prime/DAW*/ref';
  aap = aas_processinput(aap);
  

Recent Updates

2013/10/29 New features!

• FreeSurfer has been tested

• Solving backward-compatibility for handling multiple DICOM sources (see Recent Update on 2013/09/06)

2013/09/06 New features!

• DATREL has been tested

• Improved monitoring of the parallel computing

• Handling multiple DICOM sources (e.g. /mridata/cbu and /mridata/camcan)

2013/08/08 Parallel computing is working

• See Parallel computing for more information!

2013/08/02 new version v4.1 (latest devel-share branch from GitHub)

• merge with GitHub completed

• release-4.1 is now the latest stable

• NIFTI-4D support is independent from SPM version. N.B.: Configuration!

2013/06/26 merge with the latest devel-rhodri branch from GitHub

• release-4.0 is now the latest stable

2013/06/06 new feature

• NIFTI-4D support added.

2013/05/13 new feature

• Garbage collection tested
• New report summary:
  • Head movement: outlier-detection with boxplot

2013/04/24 CBSU Patch/Extension for Version 4 is available

New features:

• Handling input file as a list of subjects and sessions

• Module for first-level thresholding

• Multi-level interlinked reporting:

2013/03/03 Version 4 is available

New features in version 4