Tutorial

The aa distribution includes a collection of example scripts that demonstrate data input, preprocessing, and modeling, as well as specialized coding such as branched and connected pipelines. However, as a result of its large feature set, Automatic Analysis has a rather steep learning curve. What is needed is an introduction sympathetic to the first-time user, one that explains basic scripting as well as warning of pitfalls and difficulties that may be encountered. That is what this tutorial aims to provide.

We introduce aa here by reproducing the auditory task analysis that appears in the SPM manual (chapter 30 as of this writing). This example was chosen as it demonstrates implementation of a simple yet complete fMRI processing pipeline. Additionally, the data required are rather modest (available from the SPM website -- see below), and the guided analysis provided in the SPM manual provides an independent resource for reference. Although it is not necessary to be familiar with SPM to use aa, working through the click-through analysis using the SPM interface provides a check on the results obtained using aa and will help you appreciate the considerable labor savings offered by scripting an analysis.

In addition to the tutorial analysis, this document covers aa installation and setup. Links to the aa FAQ and general documentation are provided for topics including data input, modeling, and specific aa quirks. This information should help you get started using aa for your own projects.

We begin by downloading required software and data, and creating an aa parameter file.

As a starting point, we assume you have Matlab installed. Automatic Analysis generally works best with a new-ish version of Matlab (> R2018b). Additionally, you will need to install SPM (available for download at https://www.fil.ion.ucl.ac.uk/spm/software/download). SPM version 7771 or later is required. Note that a number of third-party SPM toolboxes (e.g., FieldTrip or the Brain Wavelet Toolbox) as well as other analysis packages such as FSL and Freesurfer have been integrated into aa. Although you may eventually want to take advantage of functionality offered by these tools, only SPM is required to run the tutorial analysis.

Lastly, you need to install aa. Download or clone the aa repository from GitHub (https://github.com/automaticanalysis). This will create a directory named automaticanalysis containing a collection of Matlab mfiles as well as a few standalone utilities. Put this directory somewhere sensible on your machine and add that directory to your Matlab path using addpath (you need only add the top level aa directory; aa will add several necessary subdirectories to your Matlab path when it first runs).

Once you have aa installed and the Matlab path set, test your setup by typing the following at the Matlab command line:

>> aa_ver5

(">>" is used in this document to indicate the Matlab command window prompt -- it is not part of the command). You should see a message that aa is adding to your Matlab path, along with version information and a welcome message. If Matlab cannot find this command, check that you added the correct top level aa directory to your Matlab path.

It's helpful to briefly look through the aa distribution before beginning. You will find the following directories at the top level:

	aa_engine		— code related to aa internals
	aa_modules 		— a collection of analysis "modules" you select to implement a pipeline
	aa_parametersets	— example aa parameter sets
	aa_tools		— useful aa-related functions, including reporting and a BIDS converter
	developer		— tools and scripts primarily of interest to aa developers
	examples		— example scripts
	external		— third-party software used by aa
	extrafunctions		— standalone utilities used by aa

You will primarily interact with files in only three of these directories:

1. aa_modules - aa is organized as a collection of some 200 modules, each of which provides a specific processing function like realignment or smoothing. The modules live in the aa_modules directory. Note that a module is implemented as an mfile / XML header pair. For example, aamod_realign.m and aamod_realign.xml are the Matlab mfile and XML header aa uses to perform realignment. The mfile contains the code and the header defines inputs, outputs, and options for the module. The operation implemented is usually obvious from the module name, but sometimes it may be necessary to scan the header or mfile.

2. examples - A number of example aa analysis scripts are provided in the examples directory. Note each analysis requires two files: an mfile "userscript" and an XML "tasklist" (these are described in detail in later sections). Do not confuse these with the module mfile and xml header described in the preceding paragraph. The module mfile and header exist in the modules directory; a userscript and tasklist are files you create to implement a pipeline.

3. aa_parametersets - aa requires installation-specific customization in order to run (for example, aa needs to know where SPM is installed on your machine). This is implemented using a parameter file. Examples are provided in the aa_parametersets directory. Set-up of your parameter file is described in a later section.

You can have aa attempt to download the data required for the tutorial when you run the tutorial userscript. However, automatic data download occasionally fails due to network issues, server availability, etc. Because of this (and because you will eventually need to learn how to download or otherwise setup data for your own work), you may want to download the tutorial data manually for practice. As of this writing, the data is available at the following URL:

https://www.fil.ion.ucl.ac.uk/spm/download/data/MoAEpilot/MoAEpilot.bids.zip

Download and unzip this file. This will create a directory containing the data called MoAEpilot. Place this directory somewhere on your machine that you can access. You will need to tell the analysis script the location of this directory (described below).

Automatic Analysis features a large number of customizable parameters, used to specify everything from data formatting to the color of screen messages. These settings are read from an XML file specified in the analysis script (discussed in the next section). You will need to change a few settings to reflect the configuration of your machine. However, extensive customization is generally not required, either because most settings describe aa functionality you will not use (e.g., MEG settings if you work in MRI) or the default values are acceptable (the aa developers try to pick sensible defaults).

Although you may copy one of the example parameter files provided in the aa distribution (located in the subdirectory /aa_parametersets) and customize it for your installation, a much easier approach is to use the aa parameter setup utility. Type the following in the Matlab command window:

>> create_basic_parameterfile

The utility will prompt you for four entries:

Select parameter set that will be used as seed

The selection window will display a number of predefined parameter files to be used as a starting point for your custom version. Select aap_parameters_defaults.xml and click open (the button label "open" is somewhat misleading -- you are simply selecting the file; aa does not open it).

Location where intermediate and final analysis results will be stored

This is the top level directory where aa will write analysis results. You can change this location in the userscript, but a default location must be selected for the parameter file. Navigate to a directory where you have write permission, select it, and click open. This will be the top level directory for storing analysis results -- results for each analysis will appear in separate directories under this location.

Directory where raw input data can be found / will be stored

This is the directory where you will keep analysis data. You can change this location in the userscript, but a default location must be selected for the parameter file. Navigate to a directory where you have read permission, select it, and click open. This will be the top level directory for storing data -- data for each analysis will live in separate directories under this location.

Root directory of spm installation

This is the directory where spm is installed (e.g., /Applications/spm12). Navigate to the directory, select it, and click open.

Matlab should display a dialog box confirming that a file called aap_parameters_user.xml was created in $HOME/.aa (where $HOME is your home directory). No further parameter file set up is required for the tutorial analysis.

FYI: As your use of aa expands, you may need to set additional entries in the parameter file. See the reference section: Parameter File Setup for more information.

We now turn to writing the analysis script.

Two files are required to define an analysis in aa: 1) an XML list of modules that define the processing steps to be performed, and 2) a Matlab mfile that provides data and parameter customization. These files are called the tasklist and userscript, respectively. The relationship between the tasklist and userscript can sometimes be confusing, since content in one affects the other. Examples will be noted below.

The userscript and tasklist for the tutorial are included in the examples/tutorials directory as SPM_CH30.m (the "userscript") and SPM_CH30.xml (the "tasklist"). Make copies of these files and place the copies somewhere in your Matlab path. You will need to make (minor) changes to your copies in order to run the tutorial analysis.

The Tasklist

The aa tasklist is written using Extensible Markup Language (XML). The main features include:

1) the entire tasklist is enclosed by an <aap><tasklist> tag pair
2) the tasklist is divided into initialization and main sections
3a) each module in the pipeline is identified with a <module><name> tag, followed by the module name
3b) a module entry may include optional parameters
3c) the module definition must be terminated with a </name></module> closing tag pair

Standard XML syntax rules apply. Any opening tag must be matched by a corresponding closing tag. The first line of the file must specify the XML version and character encoding. Comments may be included between tokens. Due to a quirk in the aa XML parser, there must not be any blank lines at the end of the file. Typos cause errors that can be difficult to track down.

Here is the tasklist we will use for the tutorial analysis (SPM_CH30.xml):

<?xml version="1.0" encoding="utf-8"?>
<aap>
<tasklist>
    
    <initialisation>	
        <module><name>aamod_study_init</name></module>
    </initialisation>
	
    <main>
                
    <!-- preprocessing -->

    <module><name>aamod_structuralfromnifti</name></module>
    <module><name>aamod_reorienttomiddle_structural</name></module>

    <module><name>aamod_epifromnifti</name></module>
    <module><name>aamod_reorienttomiddle_epi</name></module>

    <module><name>aamod_realign</name></module>  
    <module><name>aamod_coreg_extended</name></module>

    <module><name>aamod_segment_structural</name></module>

    <module><name>aamod_norm_write_epi</name></module>

    <module><name>aamod_smooth</name>
        <extraparameters>
            <aap><tasklist><currenttask><settings>
                <FWHM>6</FWHM>
            </settings></currenttask></tasklist></aap>
        </extraparameters>
    </module>

    <!-- modeling -->

    <module><name>aamod_firstlevel_model</name></module>            
    <module><name>aamod_firstlevel_contrasts</name></module> 
    <module><name>aamod_firstlevel_threshold</name></module>
        
    </main>

</tasklist>
</aap>

The pipeline is divided into initialization and main sections, the latter containing data input, preprocessing, and modeling modules.

The initialization section shown here suffices for most needs. It performs rudimentary setup of the study and subject data structures. Some analyses require more sophisticated initialization -- for example, defining how subject identifiers are formatted. See the examples directory in the distribution for examples.

The tasklist proper is a collection of aa analysis modules appearing in the main block. The modules will be executed, in order, for each subject defined in the study and for each session defined for a given subject.

The first task is data input. In a BIDS dataset, structural and functional files are provided in NifTi format. As such, the modules aamod_structuralfromnifti and aamod_epifromnifti instruct aa to input these files. Input is immediately followed by reorientation to ensure the brain is located at the middle of the image. This step is not strictly necessary but it is good practice. Excessive eccentricity can sometimes cause errors in later processing.

The analysis continues with the standard preprocessing operations of realignment, coregistration, normalization, and spatial smoothing of the functional data. Finally, a first-level GLM is performed, consisting of fitting a model, evaluating contrasts, and generating thresholded parametric maps. (The model specification is given in the userscript, described below.)

Specifying Module Parameters

Most modules have customizable parameters. The default values for these parameters can be specified in the tasklist using an extraparameters tag. In the tutorial, a kernel width (FWHM) of 6 mm (isotropic) is specified for smoothing. This is specified in the tasklist as an option for the module aamod_smooth:

<module><name>aamod_smooth</name>
	<extraparameters>
		<aap><tasklist><currenttask><settings>
			<FWHM>6</FWHM>
		</settings></currenttask></tasklist></aap>
	</extraparameters>
</module>

This overrides the module default FWHM setting of 10 mm. Note the tag "extraparameters" used here is rather misleading; we are not specifying an "extra" parameter for the module but rather overriding a default value.

It’s possible to specify all module parameters in the tasklist. However, because the XML syntax can become unwieldy, analysis settings are often instead specified in the userscript (see next section).

FYI: There are strong opinions in the aa user community as to whether parameters should be customized in the tasklist or in the userscript. One school of thought is that the tasklist should implement a generic processing pipeline which is then tailored for a specific application in the userscript. This philosophy is reflected in many of the example scripts, in which parameter customization appears only in the userscript.

The tasklist requires no further customization to run the tutorial analysis. However, it remains to identify the data and results directories, specify the model, and actually run the analysis. This is done in the userscript.

The Userscript

The second file needed to define an analysis is the userscript. This is a standard Matlab script, albeit customized to interact with data structures defined by aa. Any valid Matlab code can be included, but a few aa-specific features are required.

The userscript for the tutorial is shown below (this is file SPM_CH30.m in the examples/tutorials directory):

% -------------------------------------------------------------------------
% 0) aa initialization
% -------------------------------------------------------------------------

aa_ver5;

% -------------------------------------------------------------------------
% 1) initializing the aap structure
% -------------------------------------------------------------------------

aap = aarecipe('SPM_CH30.xml');

% ------------------------------------------------------------------------
% 2) specify the data directory
% -------------------------------------------------------------------------

DATA_PATH = '/volumes/bigdisk/DATA/MoAEpilot';
aap.directory_conventions.rawdatadir = DATA_PATH;

autodownloadflag = false;

if (autodownloadflag == true)
    aa_downloaddemo(aap, 'MoAEpilot');
end

% ------------------------------------------------------------------------
% 3) specify the results directory
% -------------------------------------------------------------------------

ROOT_PATH = '/volumes/bigdisk/imaging';
RESULTS_DIR = 'MoAEpilot_RESULTS';

aap.acq_details.root = ROOT_PATH;
aap.directory_conventions.analysisid = RESULTS_DIR;

% -------------------------------------------------------------------------
% 4) specify analysis options
% -------------------------------------------------------------------------

aap.options.nifti4D = 1;

aap.acq_details.numdummies = 0;
aap.acq_details.input.correctEVfordummies = 0;

aap.tasksettings.aamod_firstlevel_model.xBF.UNITS = 'secs';

aap.directory_conventions.reportname='report.htm';

% -------------------------------------------------------------------------
% 5) process BIDS input
% -------------------------------------------------------------------------

aap = aas_processBIDS(aap);

% -------------------------------------------------------------------------
% 6) modeling - contrast specification
% -------------------------------------------------------------------------

aap = aas_addcontrast(aap,'aamod_firstlevel_contrasts','*','sameforallsessions',1,'L_G_R','T');

% -------------------------------------------------------------------------
% 7) run and report
% -------------------------------------------------------------------------

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

Any UPPERCASE variable names here are placeholders that must be replaced with proper definitions before running the script. These are described below.

FYI: Many comments appearing in SPM_CH30.m have been omitted in the above listing for brevity. These comments reiterate points covered below.

The tutorial userscript is organized into the following sections:

0) aa initialization
1) aap initialization
2) specify data directory
3) specify results directory
4) specify analysis options
5) process BIDS input
6) modeling - contrast specification
7) run and report

We now examine each section in more detail.

aa Initialization

A userscript typically begins with the line:

aa_ver5;

This simply initializes aa (we assume you are using version 5 in this document). If necessary, the command will modify your Matlab path to include subdirectories in the aa distribution and perform other set-up. If you have already run this command in the current Matlab session (as we did here prior to setting up your parameter file) running it a second time is unnecessary but doing so is harmless.

FYI: Some users prefer to include a clear all command as the first line of the userscript, which will reinitialize the Matlab workspace prior to execution. Although some Matlab documentation will advise against this (clearing the workspace increases runtime somewhat), it is generally a good idea when using aa.

Initializing the aap structure

The next executable code in the tutorial userscript is a call to aarecipe:

aap = aarecipe('SPM_CH30.xml');

The function takes the tasklist to be run as an input. This file must live somewhere on your Matlab path or you must pass a full pathname to it. An error will occur if the file does not exist.

In this usage of aarecipe, aa will attempt to use the default the parameter file

$HOME/.aa/aap_parameters_user.xml. 

where $HOME indicates your home directory. This is the default parameter file created by the parameter file utility (see above). An error will occur if this file does not exist.

The function aarecipe initializes internal aa data structures and analyzes dependencies present in the tasklist. This information is returned in a Matlab struct variable (called aap by convention). The aap structure contains a large amount of information, which we might describe as general and analysis-specific. The general information is read from the parameter file which you typically set once and then use for each analysis. The remainder of the userscript is used to customize the aap struct with information specific to the analysis, such as the location of the results and data directories, details of the model, and other processing options. Use of a parameter file for information common to all (or most) of your analyses minimizes the amount of code in the userscript.

FYI: An alternative calling convention exists for aarecipe in which the parameter file is passed explicitly:

aap = aarecipe(parameterfile,tasklist);

You may see this calling convention in some of the example analysis scripts included in the aa distribution.

Specify data directory

Recall that a default data directory was specified as part of parameter file setup. However, we will set this explicitly in the userscript in order to describe the parameter in more detail.

The SPM chapter 30 data is provided in BIDS format. As such, we only need to set aap.directory_conventions.rawdatadir to the full pathname of the top level BIDS directory:

FULLDATAPATH = '/full/path/to/toplevelBIDS';
aap.directory_conventions.rawdatadir = FULLDATAPATH;

For the tutorial data, FULLDATAPATH should have the form /full/path/to/MoAEpilot (assuming you did not change the name after downloading the data from the SPM website). The data is organized as follows:

aap.directory_conventions.rawdatadir
|
 CHANGES
 dataset_description.json
 README
 task-auditory_bold.json	
 sub-01

	| anat
		| sub-01_T1w.nii

	| func
		| sub-01_task-auditory_bold.nii
		| sub-01_task-auditory_events.tsv

Note there is only one subject in the auditory tutorial.

FYI: Use of BIDS data is not required. Automatic Analysis can input NifTi and DICOM files directly, although working with these formats is more cumbersome than BIDS. See the aa documentation for details.

FYI: As mentioned above, you can have aa attempt to automatically download the data when the tutorial script runs. To do so, change autodownloadflag in this section to true.

Specify results directory

Recall that a default results directory was specified as part of parameter file setup. However, we will set this explicitly in the userscript in order to describe the parameter in more detail.

The location where aa will write analysis results is defined by two aap entries. The first is aap.acq_details.root, which defines a root directory. The second is aap.directory_conventions_analysisid, which specifies a directory that will be created under aap.acq_details.root. These are indicated by the placeholder variables ROOT_PATH and RESULTS_DIR in the tutorial userscript.

The relationship between the two variables is shown below:

aap.acq_details.root (aka ROOT_PATH)
	|										
	aap.directory_conventions.analysisid (aka RESULTS_DIR)
		|	
		< aa will create analysis results here >

You must provide an existing directory for ROOT_PATH. However, RESULTS_DIR will be created at the start of the analysis if necessary. aa will populate the results directory as the analysis runs. The files created here will be described in a later section.

FYI: The results directory can be any location on your machine where you have write permission. (Similarly, the data directory can be any location you have read permission). However, users have reported difficulties when attempting to use removable media (such as a USB drive) as either the results or data location. The most reliable choice is an internal hard drive.

Specify analysis options

A userscript typically includes at least some customization of analysis options and module settings. Although parameters may be specified in the tasklist (see previous section), it is often more convenient to do so in the userscript. The code is generally more compact, and, in some cases, Matlab syntax offers customization that would be difficult or impossible to accomplish using XML. However, the choice is ultimately an issue of user preference.

The parameters you need to customize will be specific to your analysis. The auditory example includes the following:

aap.options.nifti4D = 1;
aap.acq_details.numdummies = 0;
aap.acq_details.input.correctEVfordummies = 0;
aap.tasksettings.aamod_firstlevel_model.xBF.UNITS = 'secs';
aap.directory_conventions.reportname='report.htm';

These examples demonstrate the general approach to setting analysis options in aa, which are defined by setting a field in the aap struct. Be careful of typos when entering field names, which can result in hard-to-track runtime errors.

The first three settings here may be familiar if you have worked with fMRI data previously. They inform aa to use a 4D NifTi file structure for functional data (instead of a collection of individual 3D volumes, which was often used in older data) and sets the number of initial functional scans to be discarded (e.g., due to T1 effects) equal to zero. Although the first 12 frames are discarded in the click-through analysis described in the SPM manual, the discarded frames are not included in the BIDS data and so none need be discarded here. If frames were discarded, we would instruct aa to correct the event timing provided in the BIDS tsv files to account for the removed frames. However, this is unnecessary, so we set the input.correctEVfordummies option to 0 (false).

Next, we specify event data for the task modeling are specified in units of seconds (secs) rather than scans. Although the SPM click-through tutorial described in the manual uses 'scans', event information in a BIDS datasets is always provided in seconds (according to the BIDS standard).

Finally, we choose a name for the analysis report which will be created by aa (here simply called "report"). The report is described in a later section.

The "tasksettings" Field

Recall that we can specify module options in the tasklist using the extraparameters tag. We used this feature to specify a FWHM of 6 mm for aamod_smooth. However, we may also set module options in the userscript. This is done using the aap.tasksettings field. For example, we could include the line:

aap.tasksettings.aamod_smooth.FWHM = 6;

to set the smoothing kernel in the tasklist. However, because we elected to set the option in the tasklist, this code is commented in the userscript. If you assign conflicting parameter values in both the tasklist and in the userscript, the value in the tasklist takes precedence.

FYI: A separate smoothing parameter exists in aap.spm.defaults.smooth.fwhm. This value is ignored by aamod_smooth. There are, unfortunately, cases in which parameter specification in aa is somewhat confusing.

FYI: You can modify settings in the userscript only for modules that appear in the tasklist. For example, suppose you temporarily remove or comment the modeling modules in the tasklist, say, to allow you to focus on preprocessing. Attempting to then define parameters in the userscript for aamod_firstlevelmodel will cause a runtime error. This is an example of how the userscript and tasklist interact, which can sometimes create unexpected behavior.

Process BIDS input

Once directory information and other options are set, we select subjects and sessions for the analysis. Data in the auditory tutorial is BIDS formatted, which simplifies this operation. All that is required is a call to aas_processBIDS:

aap = aas_processBIDS(aap);

This use of aas_processBIDS will add all tasks, subjects, and sessions which appear in the data. You may select a subset of these by passing additional parameters (this is not necessary in the tutorial analysis, as the data contains only one subject, one session, and one task). For more information, see FAQ: What processing options are available for BIDS input?

FYI: The aa BIDS implementation is a work in progress (in particular, the processing of field maps is rather incomplete). Also, public BIDS datasets are notorious for including content that violates the BIDS standard. If possible, you should run a BIDS validator on any dataset before using a given dataset and carefully review any warnings or errors.

Modeling - contrast specification

Model definition in aa requires events and contrasts. In general, you need to specify both. However, when using BIDS data, events are automatically defined by aas_processBIDS using information in the tsv files included with the data. As such, we need only define a model contrast for the tutorial analysis.

Contrasts are defined in aa using the utility function aas_addcontrast. The general syntax is as follows:

aap = aas_addcontrast(aap, module, subjectID, sessionID, contrast_def, contrastID, T_or_F_flag);

The function takes the aap struct, the name of the tasklist module for which the contrast is being defined, the subject and session identifiers, the contrast definition, an identifier for the contrast, and finally a flag indicating whether this is a t-contrast or an F-contrast. The function returns a modified aap struct to which the contrast definition has been added. The function is called once for each contrast you want to define.

The tutorial uses a single omnibus contrast, defined as follows:

aap = aas_addcontrast(aap, 'aamod_firstlevel_contrasts','*', 'sameforallsessions', 1,'L_G_R','T');

The module used to process first level model contrasts in aa is aamod_firstlevel_contrasts, so this is passed as the second parameter. A wildcard (*) is entered for the subject ID, indicating this contrast definition should be applied to all subjects in the data (this is generally useful, albeit less-so here because there is only one subject in the tutorial dataset). The session selector indicates this contrast definition should be applied to all sessions in the data (there is only one session in the tutorial dataset).

The next parameter is the contrast vector. There is one event defined in the model ('listening' -- see the file sub01_task-auditory_events.tsv in the data), which we test using the simple omnibus contrast [1]. We pass a single digit 1, which Matlab will recognize as shorthand for the vector [1] (we could pass [1], but Matlab would warn the vector syntax is unnecessary). We then provide a name for the contrast ('L_G_R' meaning "listening greater than rest") and indicate the contrast is a t-contrast by passing 'T' as the contrast type flag.

FYI: We used 'L_G_R' rather than (the more obvious) 'L>G' because special characters (here, '>') should be avoided in identifiers. See FAQ: What are some good aa programming and data practices?

FYI: Contrast definition is one of the more error-prone operations in a userscript. As such, aas_addcontrast implements sophisticated parameter parsing that can simplify contrast definition. See the wiki reference page _Statistical Modeling _for an expanded discussion.

Run and report

Once the data and analysis options are specified, the analysis is run by calling aa_doprocessing:

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

As shown here, processing is followed by report generation (described in the next section).

The analysis begins with an evaluation of data dependencies, ensuring that all inputs required by the modules appearing in the tasklist are defined (see FAQ: What is a stream? for more information). As the analysis proceeds, aa populates the results directory with output created by the modules appearing in the tasklist. Additionally, informational messages are written to the command window, including elapsed time and a summary of any output files created. Some modules will open figure windows that display analysis results or various diagnostic graphics. These windows will be automatically closed after the graphics are saved (most will be included in the report).

FYI: Interposed with updates on the analysis progress are occasional aa warning messages. These are useful when implementing more complex pipelines but can be confusing to new users. Warnings you might encounter when running the tutorial analysis include: 1) Renaming output epi of aamod_firstlevel_model_00001 to . followed by a message about breaking dependencies, 2) a message spmClass's folders (and subfolders) will be removed from the MATLAB path, and 3) a warning Setting is not specified! when aamod_norm_write_epi runs. These can be ignored. Additionally, some warnings are generated by SPM or Matlab and can be considered purely informational. For example, you may see a message JavaFrame property will be obsoleted in a future release, or utc_time is not found, or that an image was resized to fit the screen. These have no effect on the analysis.

The tutorial code should run without errors. However, a typo or mistake introduced when customizing placeholders in the script may cause a crash. If an incorrect data location is entered (i.e., the variable DATA_PATH), it will cause analysis to halt with the following message:

**** automatic analysis failed - see reason and line numbers below
no subjects found in directory /bad/path/to/data

where "/bad/path/to/data" will be replaced by the name entered in DATA_PATH. Matlab will also print a stack trace indicating the error message was generated by aas_processBIDS.

If the root path of the results directory does not exist (ROOT_PATH), the analysis will halt with the following error:

**** automatic analysis failed - see reason and line numbers below
ERROR: Problem making directory /bad/path/to/somewhere

where "/bad/path/to/somewhere" will be replaced by the name entered in RESULTS_PATH. Matlab will also indicate the error message was generated by aamod_study_init.

If either of these errors are encountered, check the variable names in the userscript and correct them. You may then simply re-run the userscript to continue. Automatic Analysis will examine any partial results present in the results directory and continue the analysis from that point, skipping any steps that completed before the crash occurred.

FYI: A typo in RESULTS_DIR should not cause an error, although the results directory name will reflect the actual name entered.

FYI: Crashes can be caused by poor programming practices such as including spaces or special characters in contrast names. See FAQ: What are some good aa programming and data practices?

FYI: For more information on how aa tracks analysis progress, see FAQ: How does aa know which modules in a tasklist have finished processing?

When the tutorial analysis completes, the message Taskqueue is closed! appears in the Matlab command window. The results directory should have been updated as follows:

aap.acq_details.root (<= the name entered in ROOT_PATH)
	|										
	aap.directory_conventions.analysisid (<= the name entered in RESULTS_DIR)
		|	
		aamod_structuralfromnifti_00001
		aamod_epifromnifti_00001
		aamod_reorienttomiddle_structural_00001
		aamod_reorienttomiddle_epi_00001
		aamod_realign_00001
		aamod_coreg_extended_00001
		aamod_segment_structural_00001
		aamod_norm_write_epi_00001
		aamod_smooth_00001
		aamod_firstlevel_model_00001
		aamod_firstlevel_contrasts_00001
		aamod_firstlevel_threshold_00001
		aap_cmap.txt
		aap_parameters.mat
		aap_prov.dot

Each entry that begins with aamod_* is a directory containing output generated by the corresponding module. If you list the contents of the results directory, the directories will be shown in alphabetical order. For convenience, we have sorted the contents here to follow the organization of the tasklist, followed by other files that may be of interest (some files used internally by aa are omitted in this listing). aa adds a numerical suffix to the module name that uniquely identify the module in order of appearance in the tasklist. For example, if two instances of aamod_firstlevel_model were included, aa would create directories aamod_firstlevel_model_00001 and aamod_firstlevel_model_00002.

FYI: The five digit module suffix suggests at as many as 99999 instances of a module may appear in a tasklist; in practice, there is typically only one and rarely more than a few.

The top level results directory also contains three other files of note: 1) the aap struct is saved to aap_parameters.mat, 2) aap_cmap.txt is a plaintext file listing data dependencies of the tasklist, 3) aap_prov.dot is a graphical "provenance" map of the pipeline summarizing data flow. Viewing the map requires third-party software that can read "dot" format (e.g., GraphViz).

FYI: You may examine the fields of the aap structure to check settings. You may also load the aap structure from the file aap_parameters.mat in the top-level results directory to check a previously-run analysis.

Automatic Analysis generates a large amount of graphical output in the module directories (saved as jpegs). This includes images used for diagnostic and QA purposes in addition to more direct results such as thresholded parametric maps. A full list is beyond the scope of this introduction. However, here are some files of interest found in the tutorial analysis:

aamod_realign -- head motion (individual sessions and concatenated)
aamod_coreg -- post-coregistration epi/structural alignment
aamod_segment_structural -- native & normed segmentation; gm/wm/csf voxel distributions
aamod_norm_write_epi -- representative normed sections with tissue boundaries
aamod_firstlevel_model -- design matrix, event shared variance summary
aamod_firstlevel_contrast -- contrast summary diagram, voxel histograms
aamod_firstlevel_threshold -- thresholded parametric maps (see next section)

Depending on your version of aa, some of these files may not be generated unless you run a report.

Data (e.g., NifTi files) for a module are organized into a number of subdirectories. The naming is module-specific, although a "structural" directory is typically used for structural data and "stats" for statistical data. Functional data is typically organized by session name.

FYI: The NifTi files appearing in a module directory are a mixture of input (i.e., a copy of a file previously created by a module appearing earlier in the tasklist) and output (a file created by the module itself). To save disk space, links are typically used for the input files rather than making literal file copies, although this can vary by installation.

Parametric Maps

The main analysis results of interest are of course the thresholded parametric maps. These can be found in aamod_firstlevel_threshold_00001. aa saves the NifTi files, several sagittal, axial, and coronal section views, and a 3D rendered image. Graphical output is organized as a collection of files named:

diagnostic_aamod_firstlevel_threshold_CXX_SESSION_VIEW.jpg

where CXX is the contrast index* (C01, C02, etc), SESSION is the session name, and VIEW is overlay_1 (sagittal views), overlay_2 (coronal), overlay_3 (axial), or render (six-view surface renderings). Because the naming convention is somewhat cumbersome, you may wish to review these images in the report rather than searching the module directory (see next section).

• In general, the contrast index can be determined from the contrast summary plot saved in the firstlevel contrasts module. However, only one contrast is defined in the tutorial analysis.

The model data are saved to a stats directory in the firstlevel_* module directories. The contents are slightly different for the three modules:

aamod_firstlevel_model_00001/stats

beta_XXXX.nii -- beta estimates (one for each model regressor of interest)
mask.nii -- mask defining in-brain voxels
ResMS.nii -- residual per voxel
RPV.nii -- resels per voxel
SPM.mat -- SPM structure

aamod_firstlevel_contrasts_00001/stats

contents of aamod_firstlevel_model_00001/stats plus:

con_XXXX.nii -- beta map (one for each defined contrast)
spmT_XXXX.nii -- unthresholded t-map for each defined contrast
SPM.mat -- SPM structure (updated)

aamod_firstlevel_threshold_00001/stats

spmT_XXX.nii -- unthresholded t-map copied (or linked) from aamod_firstlevel_contrasts
thrT_XXXX.nii -- thresholded t-maps
SPM.mat -- SPM structure (updated)

SPM users may recognize these filenames. The organization follows (roughly) use of the Specify 1st-level, Estimate, and Results buttons in the SPM interface.

FYI: The tutorial does not include a second-level model (because the data contains only one subject). For an overview of second-level modeling, see the wiki reference section Statistical Modelling.

It is cumbersome to examine analysis results by surfing the module directories. As such, aa provides a utility aa_report that collects results into a single HTML document for review. The function takes the root path and results directory name as parameters:

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

Reporting creates multiple files at the top level of the analysis results directory:

report.html		-- main page
report_moco.html	-- motion correction only
report_reg.html		-- coregistration only
report_scon.html	-- contrast results only
report_subjects.html	-- subject level results only

By default, aa_report automatically opens the Matlab HTML browser to view the report. This does not necessarily provide the best viewing experience. You may want to close this window and open report.html using a web browser such as Chrome or Safari.

The report is organized by subject and task, and includes the parametric maps, critical diagnostic graphics, and summary analysis results. The specific contents depend on which modules are included in the tasklist -- not every module generates content that appears in the report.

The main tabs displayed in the report for the tutorial analysis are Main, Subject list, Motion correction summary, Registration summary, and First-level results. The main page (may) display a provenance map -- a graphical summary of the pipeline showing data flow between the modules appearing in the tasklist. The map is parsed from the contents of the file aap_prov.dot that is created in the top-level results directory and requires an app such as GraphViz (https://graphviz.org/) for display. If aa can't locate an application on your machine that can process a "dot" file, the Workflow title page will be empty.

FYI: GraphViz is available under Linux, Windows, and OS-X. However, support under OS-X is a bit lacking. You may have difficulty viewing the provenance map if you are running aa under this operating system.

FYI: Graphics in the report use hardcoded html image tags. As such, the browser will longer be able to find the contents if you move or copy the report. A workaround is to convert the report to pdf. The free utility wkhtmltopdf can be used for this, although the formatting can be somewhat wonky and the generated pdf tends to be rather large.

Results from the tutorial analysis can be compared with those obtained from the click-through analysis presented in the SPM manual. Note any figure numbers cited here may change if/when the SPM manual is updated.

Because the analysis included only one subject, all results of interest appear under the Subject list tab in the aa report. Selecting sub-01 from this tab brings up a scrollable display for this subject organized by module. Notable results include a motion summary created during realignment, registration verification, section views of the implicit mask used for modeling, and a graphical display of the design matrix and plots of the parametric maps.

Realigment includes a motion summary in which head motion in the six directions (x, y, z, roll, pitch, and yaw) are plotted for each frame in the functional data. This is the same information shown in Fig. 30.2 in the SPM manual (albeit the vertical scale differs). Normalization generates overlays of functional and structural data so that coregistration can be checked (additional views can be found in the directory aamod_coreg_extended_00001/diagnostics). This is followed by plots of the implicit mask used for modeling. The mask should be checked for distortion or gaps that may indicate errors in coregistration or normalization.

The next result of interest is a graphical display of the design matrix. The matrix includes (one) regressor of interest as well as nuisance regressors (this display is not included in the SPM manual). The first column (listening) is the regressor of interest; the *bf(1) suffix on the column label indicates the regressor was convolved with the HRF. The next six columns are the motion parameters (x, y, z, roll, pitch, yaw) estimated during realignment. The final column in the design matrix is a constant. An estimation of regressor orthogonality is displayed beneath the design matrix.

The design matrix should be reviewed carefully to verify the model information is correct. Specifically, the first column should show seven repetitions of the task (as described in the SPM manual). Incorrect display suggests the event information is incorrect. A common source of such an error is the use of the wrong timing units in the xBF field (recall we set this to 'secs' in the userscript. A useful exercise is to set this field to (the incorrect) '"scans" and rerun the analysis, examining effects on the design matrix and parametric maps.

Finally, the report includes axial sections and rendered surface images, along with a display of the SPM statistical table (a series of coronal, sagittal, and axial sections is saved in aamod_firstlevel_threshold_00001/sub-01). The parametric maps and table should be compared with Figs 30.15, 30.18, and 30.20. As can be expected, there is significant bilateral activation of auditory regions as well as isolated activation of prefrontal cortex. The SPM table results generated by aa (scroll to the right margin of the report) should be similar to those obtained in the click-through (see Fig 30.15).

FYI: As noted above, aa saves the SPM.mat file in the model, contrast, and threshold module directories. You may load any of these files into SPM and perform additional post-processing described in the Chapter 30 click-through.

This tutorial was intended to provide a smooth first experience with aa. Obviously, the goal of using aa is to implement pipelines specific to your research interests. A good next step is to review other scripts provided in the examples directory. These demonstrate a variety of applications, including DTI, Dartel, and extraction of 3D anatomy using Freesurfer. Additionally, there are example pipelines for MEG analysis. You may find one of these scripts works as a template for your needs. Note the examples were contributed by a number of different aa users and so demonstrate a range of aa coding styles.

Sooner or later, however, you will want to take advantage of broader functionality offered by aa. It is impossible to describe every scenario, but the primary challenges faced by new aa users fall into two categories: module selection and error handling.

Which Modules do I Use?

The main difficulty of designing a tasklist in aa is identifying which modules to include. There are over 200 available in the current distribution (see the aa_modules directory). Some guidance is provided by examining the modules themselves. The module XML header often provides information as to the function and usage of the module. There should be a brief description of the functionality and a list of custom parameters (including default values). Particularly helpful are the inputstreams and outputstreams specified in the header.

Taken as a whole, your tasklist should define a chain of streams in which the input of each module is listed as the output of another module appearing earlier in the tasklist. For example, aamod_realign takes an epi stream as input. Therefore, some module appearing earlier in the tasklist must generate an epi stream as an output (in the tutorial, this is provided by aamod_convert_epi). In turn, the output streams created by aamod_realign are used by modules appearing later the tasklist, and so on. When aa first launches, it prints a summary of input/output dependencies in the Matlab command window. Execution will halt if a necessary stream is missing.

Interpreting Error Messages

As you begin to use aa in your own work, you will eventually encounter runtime errors. Unfortunately, Matlab error messages are often not particularly helpful. As a rule, the source of an error is an incorrect setting in the aap structure, which may not be revealed until many hours later when a module that uses the information attempts to run. This is a challenging problem to address. As such, it can be helpful to implement a pipeline incrementally. Start with one subject, not all of them. Don't include modeling until the preprocessing is working. Test preprocessing one or a few stages at a time. After each step forward save a copy of your working tasklist and userscript. That way, if you run into a problem you can retreat to a saved working analysis then move forward again.

FYI: Modules often change the Matlab working directory during processing. If a runtime error occurs, the module may have not reset it. This can create unexpected behavior when attempting to restart the analysis (you may receive an Unable to access current folder error). Your first instinct after a runtime error should be to check the current working directory and reset it if necessary. (You might even add cd('/path/where/userscript/lives') as the first line in your userscript.)

Facility with aa will only come with experience. Two areas particularly prone to programming mistakes are data input, and model specification. These topics are covered in the FAQ and general aa documentation in more detail. As always, you should follow good programming and data practices, listed at the end of the FAQ.

If you have questions, or if you find bugs or have suggestions for new functionality, feel free to open an Issue on the aa GitHub site.