= 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: [[AutomaticAnalysisIntroduction|Manual]] * Version 4: . [[AA|This page]] . [[https://github.com/rhodricusack/automaticanalysis|GitHub]] . [[https://github.com/rhodricusack/automaticanalysis/wiki|Wiki]] Any problems, report them to [[DannyMitchell|Danny Mitchell]] (version 2 and 3) or [[TiborAuer|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 [[https://github.com/rhodricusack/automaticanalysis|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... * {{{#!highlight matlab numbers=off 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 . [[attachment:aa_user_fmri.m|User Master Script (UMS) for fMRI|&do=get]] . <>[[attachment:aa_user_dartelvbm8.m|User Master Script (UMS) for DARTEL|&do=get]] . <>[[attachment:aa_user_FS.m|User Master Script (UMS) for FreeSurfer|&do=get]] Optionally, you can also specify your own parameter settings loaded by `aarecipe`. E.g.: <>[[attachment:aap_user_parameters.xml|User-specific parameter settings|&do=get]] (you may need to change the path pointing to the "parent" xml) . {{{#!highlight matlab numbers=off aap = aarecipe('aap_user_parameters.xml'); }}} == 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: . {{{#!highlight matlab numbers=off 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 [[#path|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.: .{{{#!highlight matlab numbers=off 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: . {{{#!highlight matlab numbers=off 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 .{{{#!highlight matlab numbers=off aa_report(fullfile(aas_getstudypath(aap),aap.directory_conventions.analysisid)); }}} * If you are in the analysis folder .{{{#!highlight matlab numbers=off 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 .{{{#!highlight matlab numbers=off aas_garbagecollection(aap,true); }}} * If you are in the analysis folder .{{{#!highlight matlab numbers=off aas_garbagecollection(pwd,true); }}} <> === "Inheritable" parameter settings === There is an option to have site-, user-, and/or study-specific parameter settings containing only the parameters to be overridden (see [[#XML_example|example]]). <> === Non-Standard Modules === * First-level thresholding * List of significant activation maps * Overlays on axial slices (T1 MNI) * Rendering results in 3D * [[FslInformation|FSL]] * [[FreesurferInformation|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: * [[attachment:Subject_List_Test.csv|a CSV file|&do=get]]: 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.: . {{{#!csv 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 with''ID'' (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): . {{{#!highlight matlab numbers=off 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/11/25 Fix! ==== . The most recent update fixes the correspondence of the `subjectname`, the name you use when adding subject in the User Master Script (USM), and the referring aap setting `aap.directory_conventions.subjectoutputformat`. It means that `subjectname` has to be provided according to the setting. . The default is `‘CBU%06d*’`, which means that you need to provide the number (as an integer, without CBU), e.g. 90952. . Many of you may use part or full name of the directory, which will result an error message most likely upon `aamod_evaulatesubjectnames`. You have two options: 1. Either, specify `subjectname` in UMS according to the setting (see above). 2. Or, change the setting: a. If you use partial name (e.g. `‘CBU090952’`), then add this line to the UMS: . {{{#!highlight matlab numbers=off aap.directory_conventions. Subjectoutputformat = ‘%s*’; }}} b. If you use full name (e.g. `‘CBU090952_MR09032/20090828_131456’`), then add this line to the UMS: . {{{#!highlight matlab numbers=off aap.directory_conventions. Subjectoutputformat = ‘%s’; }}} . ==== 2013/11/21 New features! ==== * [[#XML|"Inheritable" parameter setting]] * `aap.directory_conventions.spmtoolsdir`: option to specify path for SPM tools which will be taken over when running analysis on the computing cluster. More paths can be specified using the CSL concept similarly to [[#MULTIRAW|multiple DICOM sources]] . ==== 2013/10/29 New features! ==== * [[#FS|FreeSurfer]] has been tested * Solving backward-compatibility for [[#MULTIRAW|handling multiple DICOM sources]] (see Recent Update on 2013/09/06) . ==== 2013/09/06 New features! ==== * [[#DARTEL|DATREL]] has been tested * Improved monitoring of the [[#parallel|parallel computing]] * [[#MULTIRAW|Handling multiple DICOM sources]] (e.g. `/mridata/cbu` and `/mridata/camcan`) {{{#!wiki caution '''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 ==== * See [[#parallel|Parallel computing]] for more information! {{{#!wiki caution '''Known bugs:''' Conventional SPM diagnostic will be missing for: * aamod_realignunwarp (no report of 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.: [[#path|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 ==== * [[#NIFTI4D|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|input file]] as a list of subjects and sessions * [[#MODULES|Module]] for first-level thresholding * Multi-level interlinked [[#REPORT|reporting]]: {{{#!wiki caution '''Known bugs:''' Parallel computing is still not working! }}} ==== 2013/03/03 Version 4 is available ==== [[https://github.com/rhodricusack/automaticanalysis/wiki/New-features-in-version-4|New features in version 4]]