AA - MRC CBU Imaging Wiki

Revision 175 as of 2013-11-14 17:51:18

Clear message
location: AA

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:

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) - {X} 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 - {OK} 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

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

  • Levels:
    • Study (reporting second-level)
    • Subjects (each subjects separately)
    • Summaries:
      • Subjects
      • Registration
      • First-level thresholded maps
  • Usage
    • Based on aap structure

    • aa_report(fullfile(aas_getstudypath(aap),aap.directory_conventions.analysisid));
      
    • If you are in the analysis folder
    • aa_report;
      

Garbage collection

  • Tidy up unnecessary files - delete any inputs to a module that are not also specified as an output.
  • Usage:
    • Based on aap structure

    • aas_garbagecollection(aap,true);
      
    • If you are in the analysis folder
    • aas_garbagecollection(pwd,true);
      

Non-Standard Modules

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

  • FreeSurfer

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!

2013/09/06 New features!

Known issue (backward compatibility) SOLVED (see Recent Update on 2013/10/29):

If you want to customize DICOM sources, you need to put your own path to source not into rawdatadir directly (as used to), but into rawdatadir.paths (cell array) or rawdatadir.paths{1} (cellstring).

2013/08/08 Parallel computing is working

Known bugs:

Conventional SPM diagnostic will be missing for:

  • aamod_realignunwarp (only fieldmaps)
  • aamod_coreg_noss

However, FSL diagnostics are unaffected.

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

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:

Known bugs:

Parallel computing is still not working!

2013/03/03 Version 4 is available

New features in version 4