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
 here’s 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.  Here’s 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 you’d 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 can’t be longer than your block
 length.  See note below for block users, also
* Fill out your desired confidence interval values – you won’t be able to change
 this later on.  It’s 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,
 you’ll get an additional output file that breaks each condition in each session
 out individually, and you’ll be able to view each session’s 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.  We’ll 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 you’ve supplied.  For each of these
 combinations, you’ll get some feedback:
* If you used an older version of the SPM99 program to omit scans, you may get a
 message telling you it’s detected a mismatch signifying those omitted scans,
 and will attempt to correct for them; you should probably come talk to me if
 this happens.
* It’ll tell you how big your ROI is, and how many images it’s extracting from.
* If it successfully creates and inverts your design (X) matrix, it’ll 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 you’ll probably want to try a shorter IRF length and run it again.
  Come find me if you have more questions about this.
* Then it’ll sit a while, and then tell you where it’s 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 you’ve selected several subjects, it’ll also produce those same files for
 your group – averaged across subjects.  NOTE: This feature is not yet running – 
it’s top priority next week.
* Once it’s gone through each of the subject x ROI combinations, it’ll 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 You’ll soon be able to display group average results/stats, and even add or
 remove subjects from your group on the fly, but that’s down the road a bit…
* The main axis displays a peristimulus timecourse for your conditions.  Users
 who’ve 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, we’ll 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, doesn’t it?  Actually, it sounds like a bit of a mess.  Which it
 is.  But the foundation is laid, the basic bits work, and it’s 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!

