ROI Toolbox Docs

Documentation: Percent Signal Change 2.0 (roi_percent.m)
----------------------------
Jeff Cooper
9/19/03

This documentation is quite rough, but will be filled in as time goes on,
 hopefully within the next week or so [Ed note: Ha!  That happened.  Not.].  But
 heres a quick step-by-step walk-through on how to use the new percent signal
 change program...

Starting up:

roi_percent is available as development code in SPM2-devel.  There are three
 steps to using it: the interface step, in which you enter in your ROIs,
 subjects, and various preprocessing and output choices; the processing step,
 where you pretty much sit around and wait for a while as it whirs through your
 data; and the viewing step, where you use the roi_percent_viewer to look
 through various timecourse from your conditions.  Heres what you do:

Starting Out
* Start Matlab with the spm2-devel command.
* Type roi_percent at the Matlab command prompt.
* The roi_percent interface window will pop up.

Interface Step
* Generally, you start on the left side of the interface and proceed rightwards,
 filling things out until you hit the process button.
* Select your ROI files with the Add button in the ROI field.
* Select your subject home directories with the Add button in the subject
 field.
* Choose a results directory in one of your subjects directories.  It can be as
 many levels down as you wish.
* Hit Load to load results from that directory and enable the rest of the
 interface.
* Fill out your baseline information  these is just like the old roi_percent
 questions.
o If you choose user-specified negative mask for your baseline region, the
 template image is the mask of voxels to include, and the mask image is the set
 of voxels to exclude from that template.
* Fill out your preprocessing information  this is also just like the old
 roi_percent questions.
o Low-pass filtering is not available right now... but we may bring it back
 soon, if you want it.
* Fill out the length of the IRF youd like to estimate.  The canonical HRF is
 32 secs, which is the default, but if you have problems with colinearity (see
 below), you may be able to compensate by making this number smaller.  
o Generally, for simple block designs, this cant be longer than your block
 length.  See note below for block users, also
* Fill out your desired confidence interval values  you wont be able to change
 this later on.  Its the confidence with which you want intervals to be
 calculated and displayed in the viewer. 
* Contrasts are not yet available, but will be soon.
* Help is also not yet available, but will be soon.
* Fill out any desired omitted scans (say, the first of each session), in the
 same way as you would in SPM  one number or range for each session, separated
 by spaces.
o NOTE: If you already omitted scans in estimating your model, you should NOT do
 it again here.
* The default is not to produce session-specific output; if you click yes,
 youll get an additional output file that breaks each condition in each session
 out individually, and youll be able to view each sessions conditions 
separately in the viewer.  HOWEVER, this is NOT recommended unless you have a 
small number of conditions and sessions.  Session-by-session output greatly 
increases your computation time, significantly decreases your confidence and 
increases your error at each timepoint, and may make your design matrix 
incalculable if you try to estimate a long IRF with many sessions and/or many
 conditions.  Well be working on this in the near future to improve it
* Add a string, if desired, to be prepended to all of your output files from
 this analysis.
* Choose an output directory with the choose button.
* Hit Process

Processing
* The program will produce output files for each subject x ROI combination it
 can make for the subject and ROI list youve supplied.  For each of these
 combinations, youll get some feedback:
* If you used an older version of the SPM99 program to omit scans, you may get a
 message telling you its detected a mismatch signifying those omitted scans,
 and will attempt to correct for them; you should probably come talk to me if
 this happens.
* Itll tell you how big your ROI is, and how many images its extracting from.
* If it successfully creates and inverts your design (X) matrix, itll tell you.
o If, at this point, you get a bunch of warning about matrices being singular or
 badly scaled, you probably have problems with colinearity.  The program may
 run, but youll probably want to try a shorter IRF length and run it again.
  Come find me if you have more questions about this.
* Then itll sit a while, and then tell you where its put the output files.
* You get four output files for each person x ROI combination: one .mat file
 containing the analysis variables for that combination, and three text files.
  The _percent_signal.txt contains the actual percent signal change timecourse
 from the region for the whole study.  The _percent_signal_condition.txt file
 contains, for each condition in your experiment, the impulse response function,
 and a co-indexed timecourse of indicators like the confidence interval, the t-
statistic (compared against zero), and the standard error.  The
 percent_signal_stats.txt file contains information about your full model fit,
 as well as your design matrix for reference.
* If youve selected several subjects, itll also produce those same files for
 your group  averaged across subjects.  NOTE: This feature is not yet running  
its top priority next week.
* Once its gone through each of the subject x ROI combinations, itll pop up
 the viewer for your subject or group

Viewer
* The viewer will automatically pick your first ROI and subject to load up.
  Your current ROI and subject are displayed in the appropriate fields on the
 left.  To change ROIs or subjects, click the Load New File button.
o Youll soon be able to display group average results/stats, and even add or
 remove subjects from your group on the fly, but thats down the road a bit
* The main axis displays a peristimulus timecourse for your conditions.  Users
 whove played with the Timeseries Analysis function will recognize this
 interface.  Time is on the x-axis  the zero point is the onset of a condition.
  Percent signal change is on the y-axis.
* NOTE FOR EPOCH-RELATED STUDIES: Right now, all conditions are being modeled by
 this program as events.  This means your condition timecourse is the percent
 signal change in response to the ONSET of your epoch  not a true FIR
 estimation of your IRF from the epoch as a whole.  For short epochs this may be
 okay; for longer epochs, well want to model these as real epochs.  This is
 coming soon.
* Each of the color bars below this axis has a drop-down menu of conditions.
  Selecting a condition will plot its peristimulus timecourse in that selected
 color.
* The show confidence intervals button displays confidence intervals at each
 timepoint.
* The show significant differences button enables the Compare checkboxes
 below each condition.  A condition must be checked to actually display its
 significant difference!  The buttons to the right control whether the measured
 significance is from zero or from another condition.
o Right now, only significance from zero is available  significance between
 conditions is coming soon...
* The allow session-by-session display button only works if you checked the
 session-by-session output button in the interface step.  If checked, it puts
 conditions in individual sessions into the drop-down menu as viewable.
* The saving controls in the right-hand corner allow you to save the figure as a
 picture.  These are a little jacked up right now.


Sounds great, doesnt it?  Actually, it sounds like a bit of a mess.  Which it
 is.  But the foundation is laid, the basic bits work, and its only going to
 get slicker as the weeks go on.  Drop me a line, as always, at
 jcooper@stanford.edu, when questions arise.  Good luck!

