Independent Component Analysis of fMRI Data
User Guide


The Independent Component Analysis Project Code

The Independent Component Analysis (ICA) project code can be used to find and separate regions of brain activity, which are due to independent sources.  Details of the Independent Component Analysis technique, and of the code developed specifically for this project, are included in the “Independent Component Analysis of fMRI Data” document.

The ICA project code takes as input an Afni functional dataset.  From this dataset, the ICA project code determines the independent components which comprise the recorded brain activity, and compares the time course of each of these components to the expected time course for the experiment.  Data is saved for all components which have a correlation value above the specified threshold.  These data files can then be input to the final routine of the ICA project code, to create Afni activation maps and functional time series maps for each of the components.


Software Versions

Code for this project was developed and tested with the following versions of software:
●    MATLAB:  Version 7.0.1.24704, Release 14, Service Pack 1
●    Afni Matlab functions:  Dated August 29, 2001.  (Available from http://afni.nimh.nih.gov/afni/matlab/ )
●    FastICA package for Matlab: Version 2.3, dated July 27,2004.  (Available from http://www.cis.hut.fi/projects/ica/fastica/ )

NOTE: A second version of the project code was also created to work with Matlab Version 6.0.0.88, Release 12 (as installed on io.usask.ca).  See notes below for details.


Location of Code and Documentation

All code developed for this project, the shareware functions used by this code, and documentation for the project work, have been moved to the
/home/miller/ICAproject directory on io.usask.ca.

●    /home/miller/ICAproject/source/ICAwork – Contains Matlab code developed for this project.
●    /home/miller/ICAproject/source/afni_matlab/matlab – Contains Afni Matlab functions used by the project code.  
●    /home/miller/ICAproject/source/FastICA_23 – Contains the FastICA Matlab functions called by the project code.

●    /home/miller/ICAproject/docs – Contains the “Independent Component Analysis of fMRI Data” document, which provides an overview of Independent Component Analysis, information on its use to analyze fMRI data, and a detailed description of the code developed for this project. This directory also contains a copy of this User Guide.

●    /home/miller/ICAproject/results – Contains Afni activation maps of components found by running the project code on the synaethesia dataset.  Detailed descriptions of the files within this directory are provided in Readme.txt files in each of the results subdirectories.

In order for the ICA project code to run in Matlab Version 6.0, modifications were required to a number of routines within the custom developed ICA code, and the Afni Matlab routines.  This modified code is located in the following directories on io.usask.ca:
●    /home/miller/ICAproject/source/MLv6/ICAwork
●    /home/miller/ICAproject/source/MLv6/afni_matlab/matlab
●    /home/miller/ICAproject/source/MLv6/FastICA_23


Setup

●    All code used for this project was written using Matlab.  Functions can be run by entering the appropriate commands at the prompt within the Matlab Command Window.  (Alternately, a command line only version of Matlab can be started using the “matlab –nojvm” command.  ICA project code functions can then be run by entering the commands at the Matlab command prompt.)  
●    The directories containing the project code, Afni Matlab functions, and FastICA functions must be added to the Matlab path.  For example, when using Matlab version 7.0, and with the functions located in the directories specified above, enter the following commands in the Matlab command window to add these directories to the Matlab path :
addpath /home/miller/ICAproject/source/afni_matlab/matlab  -END;
addpath /home/miller/ICAproject/source/FastICA_23  -END;
addpath /home/miller/ICAproject/source/ICAwork  -END;
To run the code using Matlab version 6.0, enter the following commands in the Matlab command window:

addpath /home/miller/ICAproject/source/MLv6/afni_matlab/matlab  -END;
addpath /home/miller/ICAproject/source/MLv6/FastICA_23  -END;
addpath /home/miller/ICAproject/source/MLv6/ICAwork  -END;
Alternately, these directories can be added to the path by using the “Set Path...” option from Matlab's “File” menu.

●    When running the ICA project code on fMRI data, it is recommended that a separate directory is used for each subject and each experiment.  Component files created by the ICA project code will not have unique names across multiple runs.  Component files created by the project's separteSignals.m routine are named sigXX.mat and sigXXfunc.mat, where XX is the component number.  Also one SignalReport .txt file is created per run.  If the ICA project is run on multiple Afni datasets within the same directory, existing files with the same names from previous runs will be overwritten.


Performing Independent Component Analysis of fMRI Data

Step 1:  Find the Components
a.  Set the working directory
The ICA project code will create a number of output files, all of which will be written to Matlab's current working directory.  Before running the ICA routines, set Matlab's working directory to point to the desired location for the output files.   

b.  Ensure the Afni functional data is available
Both the Afni .HEAD and .BRIK functional dataset files must be located in a directory which is included in Matlab's path, or in Matlab's current working directory.   

c.  Create a comparison function
You must provide a comparison function which indicates the expected time course for the experiment.  The time courses for each of the components will be compared to this  comparison function in order to determine which components represent task-related brain activity.  (This is similar to the way Afni uses a comparison function to create its fico maps).  The comparison function must be stored in a file that is located either in Matlab's current working directory, or somewhere on Matlab's path.  The comparison function file must have the same format as comparison functions created for use in Afni.  Specifically, this file must:
•    Be in ASCII format, with one number per line
•    Have the same number of lines as there are timepoints in the data.  (For the synaethesia dataset, for example, this file must have 143 lines)
•    Use values greater than 33333 to indicate time points at the beginning of the experiment which fall within the stabilization period, and which should not be used in the comparison.   

d.  Run the runICA routine
This first step will find the independent components, compare the time courses for each component with the expected time course provided in the comparison function, and save data files for all components which have time courses that are significantly correlated with the expected time course for the experiment.  Three separate routines are required for this step:  convertAfni.m (part of the project code), fastica.m (part of the FastICA package), separateSignals.m (part of the project code).  All three can be executed by running runICA.m.  runICA.m takes the following input parameters:

 Infile Name of AFNI functional data file, without the .HEAD, .BRIK extension. Filename must be enclosed in single quotes eg. ('arithN+orig', ...). Both infile.HEAD and infile.BRIK must be found somewhere in the current Matlab path.
 x,y,z x,y,z dimensions of the original AFNI data.
 compfunc File containing the comparison function describing the expected time course for the experiment. File must be located in a directory on the MatLab path. Filename must be enclosed in single quotes.
 cutoff Correlation value which is considered significant. All component time courses with correlation coefficient greater than or equal to this value will be processed; corresponding components will be written to files for later analysis. Absolute value of correlation coefficient is used.
 endian Specifies whether the machine on which this routine is being run uses big endian or little endian format. Allowed values are 'big, 'little'.
NOTE: Intel processors       = little endian
            Sun SPARC, Mac (Motorola) processors = big endian
 savets Indicates whether or not functional time series data files should be saved. Due to the large size of these files, it is recommended that they not be saved when it is only the activation intensity maps which are of interest. Valid values are 'yes' and 'no'.

Example
The following command could be entered at the Matlab command prompt to run the runICA routine:

    runICA('arithD+orig', 128,128,10, 'squarewave.1D', 0.2, 'little', 'no');

Output  
runICA.m will create the following output files:
SignalReport.txt Lists the correlation coefficient for each of the components. Indicates the correlation cutoff value used, and which components were saved to datafiles.
sigXX.mat Component file (where “XX” is the component number). One such file will be created for each component which has a correlation coefficient greater than or equal to the specified cutoff. Data in these files is in Matlab format. These files can be used as input to the convertToAfni.m routine, in order to create an Afni activation map for each component.
 sigXXfunc.mat Functional time series data for the component (where “XX” is the component number). These files are only created if parameter “savets” is set to “yes”. One such file will be created for each component which has a correlation coefficient greater than or equal to the specified cutoff. Data in these files is in Matlab format. These files can be used as input to the convertFuncToAfni.m routine, in order to create an Afni functional time series image for each component.


Step 2:  Create the Afni Activation and Functional Time Series Maps
a. Create Afni Activation Maps
An Afni Activation map can be created from each of the sigXX.mat component files created in the previous step.  The activation maps are intensity maps only (Afni fim format).  To create these maps, run the convertToAfni.m routine.  convertToAfni.m takes the following input parameters:  
sigfile File containing the component voxel values to be converted (i.e. an output file from runICA.m or separateSignals.m). File must be located somewhere within MatLab's current path. Filename must be enclosed in single quotes.
 x,y,z x,y,z dimensions for the AFNI map. These dimensions should be those of the original AFNI functional data read into MatLab for computation of the components. (Note: The voxel values stored in sigfile must be a matrix with dimensions 1 X (x*y*z) )
 inHeadfile Name of .HEAD file of the original AFNI dataset from which the components were determined (without the '.HEAD' extension). The .HEAD file of the output data will be created using most of the information from the original .HEAD file. Changes will be made only where required. inHeadfile.HEAD must be located somewhere on MatLab's current path. Filename must be enclosed in single quotes.
 outfile Name of the output file, without extension. outfile.HEAD, outfile.BRIK and outfile@1.HEAD, outfile@1.BRIK will be created in Matlab's current working directory. Filename must be enclosed in single quotes.
 zlimit Z-score (number of standard deviations from mean) which should be considered significant. Voxels with z-scores greater than or equal to this value will be included in the activation map. (Note: In McKeown's paper, a z-score limit of 2 is used; Kiviniemi et al. use 6. A z-score limit of 4 seemed appropriate for the synaethesia data. See details in the “Independent Component Analysis of fMRI Data” document).
 endian Specifies whether the machine on which this routine is being run uses big endian or little endian format. Allowed values are 'big', 'little'. Required so that Afni will know whether or not byte swapping is required when maps created by this routine are to be displayed on a different machine.
Example
The following command could be entered at the Matlab command prompt to run the convertToAfni routine:

    convertToAfni('sig39.mat', 128,128,10, 'arithD+orig', 'outsig39', 4, 'little');

Output  
convertToAfni.m will create the following output files:
outfile@1.HEAD, outfile@1.BRIK Afni activation maps. Only voxels which make a significant contribution to the component are included in these maps. These voxels have a value which is at least the “zlimit” number of standard deviations greater than the mean voxel value in the component. In these maps, the “significant” voxels will have values set to their z-score; all other voxels will have value of 0. Activation maps are intensity maps (Afni fim format). These maps can be used as an Overlay in Afni, to indicate regions of brain activity which are part of this component.
outfile.HEAD, outfile.BRIK Also Afni intensity maps. These maps include the raw voxels values for the component. These maps are of questionable value, and probably should not be created.

b.  Create Afni Functional Time Series Images (if required)
An Afni Functional Time Series image can be created from each of the sigXXfunc.mat component files created in the previous step.  (Note:  These files will only have been created if the “savets” parameter was set to “yes” when runICA.m was run.)  The functional time series images are anatomical time series images, the same format as the original Afni data used to calculate the components.  These images can be used as Afni Underlays, with the Activation maps as the Overlay.  This will allow the user to view the time series associated with each component voxel.  

To create these images, run the convertFuncToAfni.m routine.  convertFuncToAfni.m takes the following input parameters:
funcfile File containing the component functional time series values to be converted (i.e. an output file from runICA.m or separateSignals.m, when “savets” was set to “yes”). File must be located somewhere within MatLab's current path. Filename must be enclosed in single quotes.
 x,y,z x,y,z dimensions for the Afni data. These dimensions should be those of the original AFNI functional data read into MatLab for computation of the components.
 t Number of time points. This value corresponds to the number of sub-bricks in the original Afni data. Afni functional time series images created by this routine will have this same number of sub-bricks.

(Note: The voxel values stored in funcfile must be a matrix with dimensions t X (x*y*z) )
 inHeadfile Name of .HEAD file of the original AFNI dataset from which the components were determined (without the '.HEAD' extension). The .HEAD file of the output data will be created using most of the information from the original .HEAD file. Changes will be made only where required. inHeadfile.HEAD must be located somewhere on MatLab's current path. Filename must be enclosed in single quotes.
 outfuncfile Name of the output file, without extension. outfuncfile.HEAD and outfuncfile.BRIK will be created in Matlab's current working directory. Filename must be enclosed in single quotes.
 endian Specifies whether the machine on which this routine is being run uses big endian or little endian format. Allowed values are 'big', 'little'. Required so that Afni will know whether or not byte swapping is required when images created by this routine are to be displayed on a different machine.
Example
The following command could be entered at the Matlab command prompt to run the convertFuncToAfni routine:

    convertFuncToAfni('sig39func.mat', 128,128,10,143, 'arithD+orig', 'outfunc39',  'little');

Output  
convertFuncToAfni.m will create the following output files:
outfuncfile.HEAD, outfuncfile.BRIK Afni functional time series image files. These files allow the user to view the time course associated with voxels which are part of the component. Use the associated outfile@1.HEAD file (created in the previous step) as an Overlay in order to see which pixels are part of the component.

Step 3:  Optional - Combine and Compare Activation Maps  
 
It may be helpful to compare the active regions of the brain as identified by the ICA project code with those regions identified as active by either the BOLDfold technique or by creation of an Afni fico map.  To do so, a combined map can be created which merges the active brain regions identified by several individual components into a single map.  This combined map can then be merged with a map created by BOLDfold, for example, to show which brain regions were identified as active by both techniques, and regions which were identified as active by only one of the techniques.  The steps below describe the creation of such a combined comparison map.  All steps use Afni functions.  Refer to Afni documentation for details.

1. Combine the output from several components
The following command will combine the activation maps for several components, assigning the maximum value for each voxel from the input maps to that voxel in the output map.  Use the outfile@1 output files from convertToAfni.m as input.

            3dmerge –gmax –prefix mergedoutfileNm  infile1@1 infile2@1 infile3@1 …    

2.  Create an intensity map from fico or BOLDfold map
The following command will convert the threshold maps created by the Afni fico routine or by BOLDfold into an intensity map which can then be merged with the combined component map.  Indicate the threshold value which should be used as a cutoff.  Only voxels with a threshold value above this cutoff will be included in the output map.

            3dmerge  -1thtoin  -1noneg  -1thresh 0.5  -prefix throutfileNm  infileNm

3.  Create a comparison map
The following command will combine the output maps from the previous two steps, assigning unique voxel values to voxels which were identified as active by both techniques, voxels identified as active only by the ICA code, and voxels identified as active by the BOLDfold or fico technique.  Using the command as shown, with the mergedoutfileNm specified twice, the resulting values will be:
•    Voxels identified as active by both techniques              = 3
•    Voxels identified as active only by BOLDfold or fico      = 1
•    Voxels identified as active only by ICA project code     = 2

            3dmerge  –gcount  –prefix comboutfileNm  mergedoutfileNm  throutfileNm  mergedoutfileNm      


Usage Notes

Big endian, little endian issue
When converting MRI data files to Afni format, Afni’s to3d conversion routine allows the user to specify whether the input files were created on a machine with a different endian format than the machine on which the maps will be analyzed.  While the to3d “-2swap” may successfully byte swap the data for the target machine (this needs to be confirmed), the Afni .HEAD attribute BYTEORDER_STRING will still indicate the endian format of the original machine.  For example, for input files created on Solaris, even if the -2swap option is used, BYTEORDER_STRING will still be set to “MSB_FIRST” (big endian format).  This causes problems when reading the Afni files using the Afni Matlab functions, which are used by the ICA project code.    

Matlab version
The ICA project code was originally created to run in Matlab Version 7.0.  The Afni Matlab functions downloaded from http://afni.nimh.nih.gov/afni/matlab/ will not run as is in earlier versions of Matlab.  In order to create a version of the project code which could run in Matlab Version 6.0 (as installed on io.usask.ca and triceratops.usask.ca), it was necessary to make some minor modifications to some of the Afni Matlab routines.  The modified set of Afni Matlab routines are located in /home/miller/ICAproject/source/MLv6/afni_matlab/matlab.  For any routine which was modified, the original source is saved in this directory with suffix ".morig".  Modifications were also required to the code developed for this project, in order for it to run in Matlab Version 6.0.  The modified version of the ICA project code is located in /home/miller/ICAproject/source/MLv6/ICAWork.  In order to use the ICA project with Matlab Version 6.0, the directories containing the modified version of the code must be correctly added to Matlab's path.  Refer to the "Setup" section for details.