ROI Toolbox Docs

Documentation: % signal change (roi_percent.m)
----------------------------
Jeff Cooper
10/14/02
Updated as of 12/12/02 

This documentation is fairly out of date; all of this still applies, but 
several new options for different baselines have been added.  Check 
the RoiPercent page on gablab.stanford.edu/docs for the most up-to-date
stuff, which may not be any more up-to-date than this.  – Jeff 6/03/04

1. Summary

roi_percent.m is a script written to calculate the percent signal change
from specified regions of interest or individual voxels over the 
timecourse of a completed experiment. It calculates this data directly 
from the image files, not from the compressed Y.mad file or any other 
intermediate representation.
     It requests ROI .tal files and an SPMcfg.mat file, and offers the user a 
selection of temporal preprocessing steps to be optionally applied to the data:
session-specific scaling, trimming of outliers, linear detrending,
as well as low- and high-pass filters.  It has three sets of output:
a) a vector printed to the console, which consists of the timecourse of
percent signal intensity change of the ROI or voxel from the mean ROI
signal across the whole timecourse; this vector is N x 1, where N is
the number of TRs / images in the experiment, b) a set of text files,
which contain that same vector as well as timecourse vectors for an 
"average" session and for each condition in the experiment, c) a set of
.mat files with the same contents as b).
     There is also an optional multisubject mode which allows the calculation
of % signal change from several subjects in one go.  See section 5 below for 
details.

2. Usage

roi_percent
[p,ROI,Cond,G] = roi_percent
[p,ROI,Cond,G] = roi_percent(ROIfiles)
[p,ROI,Cond,G] = roi_percent(ROIfiles, SPMcfg)

roi_percent can be run from the command line or with the ‘% signal change’
button in the ROI Toolbox.  If it is run from the Toolbox button, it runs
as a callback without inputs and with only the base output, p.
	If it is run from the command line, roi_percent can be used with inputs or
without; if it is run without, it will simply use spm_get to ask the user to
select ROI files and an SPMcfg file.  The ROI files must be coordinate-set text
files (.tal files).  The script does no testing on whether its input ROIs are
in Talairach atlas space or MNI-template space, but users are advised that
results in SPM come out in MNI space, and so input ROIs should be in MNI
space as well or they will be misplaced in the brain.
	If the user selects more than one ROI file, the program performs all of
its usual queries about preprocessing, averaging, etc. and then runs a 
grand loop, performing the same preprocessing, averaging, and output options
across all the selected ROIS.	
        The user will be asked if he or she wants to run only one subject
or multiple subjects at once; the default is one, but a multi-sub loop mode
is also allowed, in which case all ROIs will be run for all subjects, and 
all the same preprocessing, averaging and output options will be set for 
all subjects.  All subjects' files will end up in the same directory, and
they will be labeled with subjects' names; see section 5 below for details.
	The SPMcfg file is used for primarily to extract experiment structure
from, and most of that work is done by the kc_get_design function.  
See that code for details on its implementation.
	In the above strings, p is the basic timecourse vector, ROI is the ROI
struct used in the code which contains a good deal of information about the ROI,
Cond is the Condition vector used in the code, which contains a good deal of
information about the condition, and G, which is a vector of global intensities
for all the scans.

3. Temporal Preprocessing

The user of the script, after selecting input files, is queried as
to what sort of temporal preprocessing they would like.
	Currently five options are allowed; selecting "all" applies all of 
them, selecting "none" skips all of them, and selecting "some" asks
the user for each preprocessing step whether or not to apply it.

- Session-specific grand mean scaling
     This option scales the data the script will look at within each 
session of the experiment.  If this option is selected, the script determines
the trimmed mean intensity for the whole brain (NOT just the ROI) across all the
scans on a session-by-session basis (i.e., the grand mean intensity of the brain 
in that session after the most extreme 10% of scans in a session have been 
removed from consideration).  The script then scales every all the intensity 
values to this session-specific grand mean.  So if this option is selected, the 
Y intensities the script looks at and reports won't be raw intensities from the 
scan, but will be proportions of the global trimmed mean intensity of the whole 
brain across the whole session.  
     This allows comparison of percent signal change between sessions,
which otherwise would not be possible because global intensities can vary 
highly between sessions in the same experiment.  This scale is optional,
but users are advised that if they don't select it, they should
not compare percent signal change of the ROI in one session to that
in another, since the comparison won't be valid.

- Trimming
  This option is applied to the raw intensity values, before converting
to percent signal change.  If selected, the script finds all scans 
in which the mean ROI intensity (i.e., the average signal intensity of
all voxels in the specified ROI) for that scan was more than two
standard deviations away from the mean ROI intensity across all the
scans in that session, and removes them from further calculations;
they are replaced in the data vector with the trimmed mean ROI intensity
for the session.

- Detrending
  Uses a MATLAB-standard function, detrend, to remove any linear trend
from the percent signal change data.  This is applied on a session-
by-session basis, and is intended to account for scanner drift within
a session.

- Low-pass filter
  Uses SPM's filtering to remove any effects in the data that take place
with a temporal frequency higher than a certain threshold.  This filter
removes high-frequency data and leaves low-frequency data, and so removes
oscillations that take place a rate so fast as to make them not of interest.
Two different types of filters are provided: a canonical hrf filter, which 
removes frequencies below that of the canonical 32-second hrf, and a Gaussian
filter, which removes frequencies below a user-specified period of
interest.  (See spm_filter.m for details).  This filter is applied on a session-
by-session basis, but each sessoin's filter will be identical.

- High-pass filter
  Uses SPM's filtering to remove any effects in the data that take place with
a temporal frequency lower than a certain threshold.  This filter removes
low-frequency data and leaves high-frequency data, and so removes oscillations
that take place with such a slow period as not to be of interest.  The user 
specifies the period of interest in seconds; effects which take place over a 
longer timescale than the period of interest are removed.  The default value 
here is taken from the SPMcfg.mat file.  Only one cutoff may be chosen; it is 
applied to all sessions for all ROIs individually.


4. Output

The output of roi_percent varies on how it is called.  With no output
arguments (as it is normally called from the ROI Toolbox, for example),
roi_percent returns one vector to the screen and creates
three .txt files and two .mat files.  Up to four output arguments can
be created in the workspace, if so desired, when the script is run from
the command line.  For the text and mat files,
the names are mostly based on the name of the ROI file, but the user
is queried for a string to prepend to that filename as an identifier,
as well as an output directory for those text and mat files.

The output is as follows:

- Workspace / output arguments
   p: This is the vector that is returned without any output arguments,
   as well as if the script is called with only one output arg.  This
   is an N x 1 vector, where N is the number of scans / TRs.  Each entry
   of p is the percent amount that the mean intensity across the whole
   ROI has changed at that scan from the mean intensity of the ROI across
   the whole timecourse - the percent signal change from the mean at
   that timepoint.  So p is the timecourse of percent signal change
   across the whole experiment.

   ROI: The second output argument, if requested, is the ROI structure,
   which contains quite a lot of information about the ROI, from its
   filename to the coordinates it represents to the timecourse of a lot
   of statistics about the ROI.  Check the roi_percent code for details.

   Cond: The third output argument, if requested, is the vector of
   condition structures, each of which contains a lot of information about
   that condition, including indices for it in the design matrix, 
   onset times, and the % signal change timecourse for that condition.
   See the roi_percent code for details.

   G: The fourth output argument, if requested, is an N x 1 vector (where
   N is the number of images), where each entry is the average voxel
   intensity across the whole brain in that scan.


- Text files
  [prepend string]_[ROI filename]_percent_signal.txt: This file contains
  the vector p - the timecourse of percent signal change across the
  whole experiment.  It is designed to be read in by MATLAB with load.

  [prepend string]_[ROI filename]_percent_signal_collapsed.txt: This 
  file contains an M x 1 vector, where M is the number of scans per
  session.  If the number of scans per session is unequal, this file
  will be empty.  If they are the same, this vector is the average
  timecourse of percent signal change - it is the vector p averaged
  across sessions.  So each scan in a session is averaged with the 
  co-indexed scan in each other session, and the combined timecourse
  is recorded in this file.  This file is designed to be read in with
  load.

  [prepend string]_[ROI_filename]_percent_signal_condition.txt: This
  file contains two short vectors for each condition, listed under each
  condition's name.  These vectors are, respectively, the
  percent signal change and image intensity timecourse within the ROI,
  averaged across every instance of that condition in the experiment (all
  sessions).  The timecourse for each vector begins at what the
  design matrix reports as the onset of the condition, and continues
  for 32 seconds' worth of scans; this number was arbitrarily chosen 
  to be about the length of an HRF.  Each timecourse represents
  the average across every running of that conditions, but be aware that
  the condition onsets used here are raw - they are exactly the 
  onsets given to the design matrix in setting up the experiment.  In
  other words, they are not time-shifted or convolved with anything,
  even if your design matrix later convolved your onsets.  As well,
  each condition's timecourse may be longer or shorter than the actual
  length of the condition.
	 This is a reporting element in flux; it's set up right now
  better for an event-related than a long block design.  More options
  for reporting will certainly be offered soon.  This file cannot
  be read with the MATLAB load command.

-.mat files
  Two .mat files are saved out in the same directory, with the same
  pre-extension filenames as the first two text files above (i.e., 
  *percent_signal and *percent_signal_collapsed); they have exactly
  the same contents as those text files but are binary files
  containing them in MATLAB variable form.  Provided merely for 
  convenience.

5. Multi-Subject Mode

   This is clearly a bit of a hack, but a multi-subject mode has been 
added for efficiency's sake.  This mode is only available if roi_percent
is run without inputs (i.e., only one cfg.mat file can be supplied at the
command line).  The user will be asked up front if multi-subject mode
is desired; if it is, the user will be allowed to select as many SPMcfg.mat
files as he or she wants.
      The crucial change in multi-subject mode is one of output file labeling;
since all the output files will be placed in the same directory, the user
is not given the option of prepending the same string to all of them.
Rather, the user is asked to supply directories from which subject "names"
will be taken and the appropriate output files labeled.  In multi-subject
mode, after preprocessing choices are made, at the same point where in single-
subject mode the user would be asked for a string to prepend, the multi-subject
user is instead asked to choose a list of "subject home directories" from 
which the labels of the output files will be taken.  The uppermost directory
for each subject should be taken; only the trailing/last element in the chosen
pathnames will be extracted and used as an output file label.
      As an example, if I am running two subjects in roi_percent, and I choose
as their "subject home directories" /gablab/jcooper/disk1/exp/joe_smith and 
/gablab/jcooper/disk1/exp/jane_doe, the output files will be labeled with
 "joe_smith" and "jane_doe" as appropriate.  If, instead, I accidentally 
select /gablab/jcooper/disk1/exp/joe_smith/results and 
/gablab/jcooper/disk1/exp/jane_doe/results as my subject directories, both 
sets of output files will be labeled with "results" - meaning the second set
will be overwritten, which is no good.  Keep in mind that if subject directory
names contain periods, only the element before the period will be selected.
      Once these directories are chosen, the program will proceed as usual,
and every subjects' output files will end up in the same output directory,
with filenames along the lines of "<subjectname>_percent_signal_condition.txt"
and so on.



6. Last bits

roi_percent.m was written as part of the Gabrieli Lab ROI Toolbox,
a package of utilities to examine ROI data in SPM.  It requires 
several functions in both of those packages to be 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...

