README to INSTALL Artifact Repair Toolbox  v2.2

1. Summary
2. Requirements
3. Disclaimer
4. Installation

 *****************************************************************
 *   See ArtRepairInstructions.txt  for instructions to run it.  *
 *   See ArtRepairOverview.pdf  for examples of output.          *
 *****************************************************************

1. SUMMARY

This software is a package of tools to visually review fMRI data for artifacts, semi-automatically detect and repair volume and slice artifacts, and review the quality of estimates produced after the repairs are made.

Use ArtRepair2 for SPM2,  and ArtRepair5 for SPM5.

The software was developed by Paul Mazaika, Susan Whitfield-Gabrieli, and
Jeffrey C. Cooper in the Gabrieli Cognitive NeuroSciences Lab at Stanford. 
The Versions 2 and later upgrades were made by Paul Mazaika (Center for Interdisciplinary Brain Science Research at Stanford). Please send any bug reports or comments to  mazaika@stanford.edu.

The version 2.2 changes include:
   GUI is now compatible with Matlab 6.5
   Fixed bug in user mask option for art_global
   Global Quality is scaled into percent signal change using the 
        peak of the design regressor and the norm of contrast vector.
   Added option to repair all movements larger than 3 mm.
The version 2.1 changes include:
   Version for SPM5 now available.
   Added Repair and Compare function to reanalyze existing results after repairs
   Allows multiple sessions per subject
   Names of the text file outputs use the prefix art_ instead of out_, e.g. art_deweighted.txt.
   (For the experts) more sample batch scripts
The version 2 major changes include:
   Outliers are based on scan-to-scan motion as well as global intensity
   Repairs can be done by long interpolations to the nearest good volumes
   Output file is written of repaired volumes to deweight during SPM estimation.
   Margins are suggested, of additional volumes to deweight for best results.
   Batch script with deweighting works well with severe motion data,
      e.g. clinical data with 5 mm motion and many (>30%)  bad volumes.
   A summary program allows a user to review the quality of SPM estimates,
       to compare results before and after repairs.
Minor changes include:
   Mask image and movie scale results according to input image intensities
   Movie programs allows views of Hi-Res 128x128 fMRI images
   Zscore and Range functions have been replaced (so Matlab statistics toolbox is not req'd)
   Noise filtering keeps intensity scale at 1, so these filters can
       be used in pipelines combined with FSL, AFNI, etc. processing programs.


2. REQUIREMENTS

These programs assume MATLAB and SPM are installed on your computer. The ArtRepair programs read and write using SPM functions, hence AnalyzeFormat images for SPM2, and write in NifTi for SPM5.

Software Compatibility: We have used the programs in Matlab Versions 6.5 and 7.0, with SPM2 and SPM5, on Linux and Windows XP. It's fairly vanilla Matlab code, but it has not been tested on many different platforms.



3. DISCLAIMERS

BETA-SOFTWARE: This software is made available to promote better understanding and quality review of fMRI data. This software is supplied as is. No formal quality assurance checks were made on the software, and no formal support or maintenance is provided or implied.

BETA-SOFTWARE for SPM5: The code was tested in SPM5, but the SPM5 version has not been exercised as thoroughly as the SPM2 version, so it may be more fragile.

SITE SPECIFIC ALGORITHMS: The art_movie visualization program works on most data, however, the automatic detection and repair functions were tuned for use with data from the GE spiral scan used at Lucas Center of Stanford University. You may need to customize internal parameters for a specific site.  


4. INSTALLATION

Insert the ArtRepair2 folder in the SPM2 toolbox, or ArtRepair5 in the SPM5 toolbox. 

Start the ArtRepair program from the toolbox window in SPM,

or from the command line to bring up the GUI for Matlab 6.5 and later:
    >> spm_ArtRepair2 or spm_ArtRepair5

or from the command line to bring up the GUI for Matlab 7 and later:
    >> old_ArtRepair

The five programs in ArtRepair can also be started from the command line:
    >> art_movie      "Contrast Movie" button
                       Visualize the data
    >> art_slice      "Noise Filtering"
                      Repairs noise spikes and bad slices- use before preprocessing
    >> art_global     "Artifact Repair"
                      Repairs outlier volumes- use just before estimation
    >> art_summary    "Global Quality"
                      Displays the distribution of estimates over the head
    >> art_redo       "Repair and Compare"
                      Reanalyze an existing SPM result with repaired data

Type >>help [command] for more information.