ROI Toolbox Docs

Documentation: Global Variate (artdetect5.m)
--------------------------------------------
Jeff Cooper
11/25/02

This documentation refers to a slightly earlier version of the
script, artdetect4.m.  Since this was written, artdetect5.m has
been released, with much fancier options about figuring out 
the global timecourse.  Check out ArtifactDetection at
gablab.stanford.edu/docs.

1. Summary

artdetect4.m is a script designed to display and identify images
in a timecourse whose global intensity differs radically from the 
timecourse's mean - outliers in the timecourse.  It then offers
the option to "fix" the data by replacing or removing those outliers
with a variety of different methods.  


The user is queried for a set of data images and a set of text files 
specifying movement parameters for that timecourse, and then a panel 
pops up displaying a) the actual global image intensity timecourse, 
b) the timecourse of Z-scores of those image intensities, to 
highlight which are more than a threshold of standard deviations 
from the mean, c) two timecourses showing movement in the x, y, z 
directions (mm) and pitch, roll, yaw dimensions (radians).  The 
panel contains controls that can interactively raise or lower the 
outlier threshold.  The user can also select individual scans as 
outliers or non-outliers.  The user is then given an option of 
several methods of repairing the data - mean insertion, 
interpolation, or removal.

2. Usage

artdetect4

This script takes no inputs.  It then queries the user with spm_get
to select a series of data images, reads them in, then asks the user
for a movement parameter file, of the sort output by SPM99 in the 
"Realignment" phase (usually found in the same directory as the 
images that were realigned).
     The script can be used either on a session-by-session basis
or to examine multiple sessions (say, a whole subject's run) at once;
in that case, the user will select both the data images and movement
parameter files for each session before selecting those for the next
session.
     Before the script runs, the user is asked if they would like to
drop the first scan of each session; the first scan in a given
session will often have a severely depressed global intensity due
to the scanner warming up.  Users may include this in their artifact
detection and repair it, or they may drop it from this analysis and
deal with it later (say, by removing it from the model later on).  If
the user chooses to drop these scans, the files won't be changed, but 
their values aren't calculated and their movement parameters won't be
displayed; they're removed from further analysis.
     Once the input files have been specified, the
script displays a four-paneled figure.  The lowest two panels are
simple plots of the movement parameters; the upper of those two is
in mm and plots the x, y, and z movements across the timeseries, 
while the lowest panel is in radians and plots the pitch, roll, and
yaw movements across the timeseries.  Scales for these graphs are 
displayed at the left, although the radian scale often includes
an exponent which is difficult to read.
    Legends for the movement parameters are also displayed on top of
the graphs, usually in the most inconvenient place possible, but 
they can be easily picked up with the mouse and moved off of the axis.
The lower panel's legend also contains max and min values for that plot,
to make the scale of the graph more obvious, for comparison purposes
across subjects.
    The very first panel of the four plots the timecourse of global
mean image intensity - in other words, each data point is the 
average image intensity, across all voxels in the image, of that 
image file.  The second panel from the top plots the Z-scores of 
those image intensities as standard deviations from the mean.
	This second panel has a red horizontal line superimposed on 
it, which represents the default threshold of 2 standard deviations 
away from the mean.  Each scan whose Z-score falls above that 
threshold line is marked with a red vertical line for visibility.  
Each of these marked scans is considered an artifact or outlier. 
	The user can exit the script simply by closing this figure 
window.


3. The Control Panel

	The user can control the placement of this red threshold line 
with the “Up” and “Down” buttons on the control panel below.  The 
panel displays the range of the current data images and the current 
threshold level.  The “Up” and “Down” buttons are used to move the 
threshold level.  Each click on one of these adds or subtracts .1 to 
the outlier threshold, and the marker lines in the Z-score display 
axes will update to reflect this change – the horizontal threshold 
will move, and as scans come above or below this threshold, they 
will be marked or unmarked as appropriate.
	Below these buttons, there is also a text box in the control 
panel which lists the scan indices that are currently marked.  This 
text box is editable by the user to enter new scans or remove scans 
they don’t want repaired.  When the user edits this box, the 
appropriate scans will be marked or unmarked on the timecourse; 
however, as soon as the user hits the up or down button, it resets 
the text box and Z-score markers to be strictly defined by the 
threshold.  Because of this, user editing should probably be the 
last step before repairing data.


3. Repairing Data

Up to this point, no change to any data has been made, and the user 
may choose to exit the script now without making any changes.  If 
the user hits 'repair,' however, he or she will be offered several 
options to repair the data.  For each of these methods, the outlier 
scans are renamed as 'outlier_<previous filename>'.img/.hdr, and 
remain in the directory just in case.  The first two methods than 
replace that scan with a newly-created one.
	The first possible method is mean insertion, in which each 
outlier scan is replaced with a mean image.  The mean image is 
created from all of the images in the timecourse EXCEPT the outliers 
that are to be replaced - it is a trimmed mean.  This image is 
created by spm_mean by performing an unweighted mean of the 
intensities of all the non-outlier images for every voxel of the 
image.
	The second possible method is interpolation, in which each 
artifact image is replaced with a newly-created image that is the 
unweighted average of the image before the artifact and the image 
after it.  If the first or last scan is included among the outliers, 
the interpolation script makes an average of the two scans AFTER the 
first (or before the last) and uses that as its replacement image.
Note, however, that since this interpolation is simple and dumbly looks
only at an outlier scan's immediate neighbors, if the outlier is part of
a block of outliers, the interpolated replacement may be no better than
the original.  In general, interpolation works best with isolated
outliers.
	The third method, which is not strongly recommended, is simply 
to remove the outlier scans from the timecourse and not replace 
them.  As with the first two methods, the outlier scans still remain 
in the same directory, just with 'outlier_' appended to their name.  
This method simply doesn't replace them with anything.
    In general, the recommended repair method is to run artdetect4 twice:
on the first pass, use the text box to select only outliers that occur in
blocks (i.e., several outliers in a row), and repair them with mean
insertion, then on the second pass, use the text box to select only isolated
outliers and repair them with interpolation.
    Since every repairing of data compromises the integrity of the
scan session by eliminating true data scans, we suggest that care be taken
to repair the minimum number of scans possible, and that only outliers that
can be positively correlated with sudden movements be repaired.


4. Output

artdetect4 outputs nothing except progress feedback to the console, 
but if the user selects to fix his or her data, it renames the 
outlying scans as 'outlier_<previous filename>'.img/.hdr and creates 
new mean or interpolation scans in their place.


5. Last Bits

artdetect4.m was written as part of the Gabrieli Lab ROI Toolbox,
a package of utilities to examine ROI data in SPM.  It requires 
several helper functions (thresh_up.m, thresh_down.m, 
artdetect_edit.m, artdetect_repair.m) as well as several functions 
in SPM to be present in order to run.

This code is in a very fluid state of development, and any suggested
modifications are welcomed and invited.  Please contact Jeff Cooper
in the Stanford Psychology Department at jcooper@stanford.edu with 
any questions about usage, bug reports, or suggestions for further
revision.  Good luck...

