ROI Toolbox Docs

Documentation: Timeseries Explorer (timeseries.m)
----------------------------
Jeff Cooper
1/29/03

1. Summary

The Timeseries Explorer application is a flexible, powerful
way of viewing timecourses of MR data from any point or region
of interest in the brain.  The user may examine raw MR signal
intensity across time as well as percent signal change across
time; most importantly, the user can also look at percent
signal change in peristimulus time for a given condition or 
conditions.  The script offers a variety of temporal preprocessing
options for the data, which can be applied on-the-fly to examine
their effects.  The user may then choose to output their data 
as text files, MATLAB files, or images.
	Users familiar with the roi_percent and/or the global
variate script will recognize much of this functionality; this
script uses those scripts as its core, but extends their 
functionality in many ways and brings them into a fully
interactive, graphical environment.



2. How To Use: An Example

This section provides a quick description of a typical user’s
interaction with the script, as an example of how it is used.
	The user first selects the “ROI Time Series Analyses” 
button from the Toolbox, and is asked to supply a background
image and an SPMcfg.mat file from the experiment she’d like
to examine.  The background image she chooses is an anatomical 
image from that individual subject, normalized with the same 
parameters she normalized her functional data with.
	The script then pops up two windows: the image window, 
which contains the familiar three-orthogonal-view navigation 
system, and the plot window, which displays the timecourse plots
of her data.  The user first clicks to an area of prefrontal
cortex she’s interested in; as she changes her location in the
brain, the plot window updates with the timecourses at her 
current location.  She looks at the intensity timecourse at that
point, then chooses two conditions to compare from the drop-down
conditions menus.  She examines the timecourses for those
conditions, then selects a high-pass and low-pass filter to 
apply to the data.  The conditions window updates her
timecourses automatically.
	The user then decides she wants to look at the timecourse
for a whole region, not just a single voxel, so in the image
window, she chooses to add an ROI to the analysis.  She
picks her ROI .img file, which is then added to the background
image, and clicks “Jump” to move instantly to the center of her
ROI in the brain.  She then clicks the “ROI mean” mode button
in the image window and waits briefly as the script extracts
her data from her functional images and averages all the voxels
in the ROI.  In a moment, the plot window updates with the
chosen timecourses, now averaged over her whole ROI instead
of from a single voxel.  
       The conditions window shows that 
her percent signal change in one condition in that ROI is 
noticeably different from her other chosen condition, with the
temporal preprocessing she’s chosen, so she decides to 
save her data.  She chooses an output directory to save her 
files to, then chooses filenames for her numerical files
and her image files.  She then chooses to save her condition
data from the drop-down menu, chooses the .txt file option, 
then hits ‘save;’ her condition-by-condition percent signal 
data from the ROI with the chosen preprocessing options
is now saved as a set of text files for further analysis.
She also chooses to save the plot window as a .jpg, to show
to a colleague, and hits ‘save;’ that .jpg saves into her
chosen directory.  Satisfied with a job well done, the
user then closes both the plot and image window, exits 
MATLAB, and logs out.




3. The Image Window

This section describes the controls in the image window of 
the Timeseries Analyses app in detail.

- Orthogonal views images (top of window)
	The three orthogonal views of the brain at the top of 
the window are the primary navigation system around the 
brain for the application; they work just the same as the
similar-looking displays in standard SPM’s “Display” utility.
The image they display is the chosen background anatomical
image.
	The user can click on any point in the three images and
the crosshairs will jump to that point; the other two images
not clicked in will update to provide new slices if the 
new location is in a different slice.
	One important consideration for choosing a background
image is the question of normalization.  If the chosen 
anatomical image has different voxel dimensions than the 
functional images used in the experiment, the script automatically
accounts for this and displays timecourses from the equivalent
spot in mm (not voxels) from the functional images.  However,
sometimes the difference in voxels sized isn’t just one of 
scale; the shape of the anatomical image may differ from that
of the functional.  This may happen, for examine, if the anatomy
has been normalized to the SPM T1 template, but the functionals
have not been.  In this situation, the user can run “off the 
edge” of the functional images; for example, if the anatomical
is longer in the anterior-posterior direction than the functionals,
the extreme edges of the anatomical image may not have an
equivalent point in the functionals.  Clicking on those extreme 
points in this situation will cause a script error.
	Even if the chosen location exists in both the functional
and anatomical, users should be aware that selecting the location
of a particular anatomical structure in an anatomical image with 
a different shape than the functionals may results in a non-
equivalent point being sampled for the timecourse.  In other words,
in both mm and voxel measurements, what’s hippocampus in a 
normalized anatomical might not be hippocampus in non-normalized 
functionals.  Users should be aware if their anatomical images 
differ in dimensions from their functionals and plan accordingly as
to how they will choose coordinates.

- Coordinate text fields
	These will update automatically based on the current location
of the crosshairs in the orthogonal images above.  The user may
jump directly to a coordinate location by editing any one of 
these fields and hitting the return key.

- ROI Controls
	The panel of controls below the crosshair position controls
the use of regions of interest in timecourse analysis.  The ROIs
listbox maintains a list of ROIs currently available for analysis.
The user may add an ROI to this box with the ‘Add ROI’ button; 
pushing it opens a selection box from which the user may choose any
ROI .img file  Only .img files can be used (not .tal files), and 
they are expected to be standard binary ROI masks, where all voxels
in the ROI have intensity 1 and all voxels outside it have
intensity 0.  (Users with only .tal files can use the txt2img
utility in the ROI Toolbox to convert them to .imgs.  Users are 
also cautioned to make sure their ROIs are in the same coordinate
space as their functional and anatomical images – i.e., MNI or
Talairach.)  The added ROI’s name appears in the listbox, and the 
location of the ROI also comes up in the orthogonal views as a 
colored blob.
	The ‘Jump’ button below the ROI listbox is for easy navigation
between ROIs; pressing it will instantly move the crosshairs to
the center of the ROI currently highlighted in the listbox.  The 
listbox highlight does not update with location changes, so the 
crosshairs may be in one ROI while another is highlighted.
	If the user wishes to examine a new set of ROIs; the ‘Clear 
ROIs’ button removes all ROIs from the listbox and the images, and
returns the user to single-voxel analysis mode.

- File/dimensions
	These text displays show the user which background image is
currently being displayed and what its dimensions are.

- Analysis mode
	This button toggles the user between single-voxel and ROI-mean
mode analyses.  In single-voxel mode, the default, the plot window
displays timecourses only for the voxel at which the crosshairs are 
currently positioned in the image window (rounding off fractional
voxel locations).  In ROI-mean mode, when the crosshairs are within
an ROI that has been added to the listbox (see above ROI controls), 
the plot window displays the mean timecourse for all voxels within
that region of interest.  The user may toggle between the two modes
freely.  
       Users should note that when ROI-mean mode turns on for the
first time, or when a new ROI is entered for the first time in ROI
mean mode, the program may pause for a few minutes, particularly
in large ROIs, as the script extracts a large number of voxels from
a large number of images.  Progress updates will be posted to the
MATLAB console window during this pause.
	When the user is in ROI-mean mode, placing the crosshairs
anywhere in an ROI results in the same timecourse being displayed.
In that mode, if the crosshairs aren’t in an ROI, no timeseries are
displayed at all.

- Currently displaying
	This text display simply tells the user what’s being 
displayed in the plot window currently; it’s useful for seeing
at a glance the state of the application.





4. The Plot Window

This sections describes the controls and displays of the plot window
in detail.

- Intensity plot (top of three)
	The intensity axes, by default, display a timecourse of the 
raw MR signal intensity at the currently selected voxel or region
over the whole of the experiment.  For all plots in this window,
the x axis represents time in scans or TRs over the whole
experiment.
	There are four checkboxes below this axis, any of which can
be turned on or off at any time.  The color of each plot is marked
in a thin line just above the checkbox controlling it.

       The “selection intensity” button turns the plot of raw
intensity at the selected voxel or region on or off.  This is the 
default plot when the application starts up.  The Y-axis for this
plot is raw MR signal intensity.
	The “global intensity” button turns on the plot of average 
MR signal intensity across all voxels in the brain vs. time.  This
plot does not change as the user navigates around the brain, as it
represents a single number for each TR of the experiment.  The
Y-axis for this plot is also MR signal intensity, but keep in 
mind that this plot is not at a single voxel or region but rather
across the whole brain.  This plot is useful for seeing if there
are global changes in activity at certain points of the experiment.
	The “z-score” button turns on the plot of intensity z-score.  
This represents the signal intensity of the selected voxel or 
region as an absolute z-score, or number of standard deviations 
away from the mean of that selected voxel or region over the whole
experiment.  This is useful for seeing how the signal intensity
at the user’s selected point changes relative to the mean
intensity at that point.  The Y-axis for this plot is Z-statistics.
	The “global z-score” button turns on the plot of global
intensity z-score; it does the same z-score operation as the
“z-score” button, but on the global intensity plot.  This represents
the average signal intensity across the whole brain at each point
as a number of standard deviations from the mean intensity of 
the brain in the whole experiment.  The Y-axis for this plot is
Z-statistics.  This plot and the “z-score” plot allow the user
to directly compare sudden jumps in raw intensity on the same scale;
this can be difficult with just intensity plots, since global 
intensity and intensity at a given point can often vary by a factor
of two to three or more.
	Note that because the scale of the axis adjusts to fit the 
currently displayed data, putting intensity data and z-score data on
at the same time will likely result in inability to make out what’s
happening with either of them.  Generally, one should compare
intensity only with intensity and z-score only with z-score.


- Percent signal change plot (middle of the three)
	This axis contains a plot of percent signal change vs. time
across the whole experiment.  The x-axis is time measured in
scans/TRs; the y-axis is the percent by which the signal intensity 
of the selected voxel or region differs from the mean signal
intensity of that selection across the whole experiment.  In other
words, the y-axis measures percent signal change from the average
intensity at the selected point or region.
	This axis updates dynamically as the user navigates around
the brain.  The user may also change this plot with the 
preprocessing buttons, which apply a series of temporal filters
to this percent signal change data.  See below for an in-depth
description of each preprocessing option.

- Peristimulus plot (bottom of the three)
	This axis contains a plot of percent signal change vs. 
time following the beginning of a given condition.  The plot is
intended to allow users to examine how the MR signal (reported
here as percent signal change) changes, ON AVERAGE, during 
a given condition at the selected voxel or region.  In this
plot, the x-axis represents peristimulus time, or time after
the condition onset, as measured in scans/TRs.  The y-axis
represents percent signal change, as described above, as the
percent difference from the mean intensity across the whole
experiment.
	The particular conditions that are plotted are controlled
by the drop-down conditions menus, below this plot and the
preprocessing controls.  Up to five conditions can be plotted
simultaneously; the color of the plot is displayed above the menu
where the condition is chosen.
	When the user selects a condition, the script calculates 
the average percent signal change across all occurrences of that
condition in the whole experiment at each TR following the 
onset of the condition.  That timeseries is then plotted on this
axis.  The script arbitrarily plots the timeseries for 32 seconds
worth of TRs; the user should keep in mind that if their 
selected condition does not last for 32 seconds, some of this plot
may be uninterpretable.
	Several conditions may be displayed at once on this plot,
which allows the user to directly compare how the intensity at 
the selected voxel or region changes in one condition versus how
it changes during another condition.
	This axis is blank until at least one condition is selected;
so long as at least one condition is selected, this axis updates
dynamically as the user navigates around the brain and around
various ROIs.
	This axis IS affected by the preprocessing controls,
just as the percent signal change axis is.  So the user may apply
different temporal preprocessing options and dynamically see their
effects on the peristimulus timecourse of different conditions.


- Preprocessing controls
	This control panel allows the user to interactively apply
four different temporal preprocessing options to the percent signal
change and peristimulus plots: detrending, trimming, high-pass
filtering, and low-pass filtering.  Users of the roi_percent script
should recognize these options, which are applied essentially
unchanged here.
	Before any of these are applied, the percent signal change
data already goes through one preprocessing step, which is a scaling
of the intensity data to the global mean intensity across the whole
brain across the whole experiment.  This allows the calculation
of percent signal change across a multi-session experiment.  Since
without this scaling, the peristimulus plot cannot be calculated
correctly, this option cannot be turned off.
	The four preprocessing options each can be turned on or 
off at any time, and automatically update the percent signal change
and peristimulus axes.  If the user chooses to save her numerical
output, the output that is saved has the currently selected
preprocessing options applied.
	The four options are:
	Linear detrending.  This option removes any linear trend
in the data on a session-by-session basis.  It is intended to account
for a linear scanner drift within each session, which is fairly 
common.
	Trimming.  This option finds any timepoint in the intensity
data whose z-score is more then 2.5 standard deviations away from
the mean intensity across each session of the selected voxel
or region and identifies them as outliers; those outliers are then
replaced in the data with the trimmed mean intensity (the average 
intensity of the most average 90% of the data in each session).  
This is intended to remove isolated outliers in the data to prevent
them from significantly affecting the data; peristimulus 
timecourses in particular can be sensitive to large outliers if 
they fall in a particular condition.  
	High-pass filter.  This option removes oscillations in the
data that have a long period, i.e., they take place over a time-
scale longer than that of interest.  The textbox next to the 
check box can be used to specify the period of interest in 
seconds; the user enters a number there and presses return.
The filter then removes oscillations in the data that have a
longer period than the specified number of seconds.  So if the user
specifies a 60 sec. period of interest, any periodic effects in 
the data that repeat with a period of greater than 60 sec. are 
filtered out.  If the user used a high-pass
filter when specifying her model, the period of interest is by
default set to that pre-specified period of interest, but the
user may change this at will.  See roi_percent_readme.txt for
information on how to determine the appropriate period of
interest.  This option is used to remove slow changes in global
brain activity of no interest, as well as to account for nonlinear
scanner drift.  This filter is applied on a session-by-session
basis.
	Low-pass filter. 	This option removes oscillations in the
data that have a short period, i.e., they take place over a
timescale shorter than that of interest.  The textbox next to 
the checkbox can be used to specify a period of interest in
two ways: the user can either specify a period of interest in
seconds, or can type ‘hrf’ in this box, in which case the filter
applied is the canonical SPM hemodynamic response function.
(These choices correspond to what’s available in SPM’s model
estimation.)  If the user types ‘3’, for example, any periodic
effects in the data that repeat with a period of less than
3 seconds are filtered out.  The ‘hrf’ filter works 
approximately like a 4.5-to-5 second filter, approximating
the time to peak response in the canonical SPM HRF.  If the
user has a low-pass filter pre-specified in their model
estimation, this is set by default to that filter; if they do
not, it is by default left blank.  This filter, which is 
applied on a session-by-session basis, is used to remove
nuisance effects like slight head movement or signal jitter.


- Conditions menu
	These five drop-downs all work identically, and all control
a plot on the peristimulus axes.  Each drop-down contains a list
of all of the conditions in the experiment, with names drawn from
the SPMcfg.mat file.  Selecting a name from one of these creates
a plot in the peristimulus window (whose color is identical to the
thin line above the drop-down menu that selected it), which
represents the average percent signal change timecourse following
the beginning of that condition, averaged over all instantiations
of that condition in the experiment.  All five of these menus may
be turned on at once, or any combination of them.  Choosing ‘<None>’
from these menus turns that plot off entirely.
	These menus are useful for comparing the average response 
in the selected voxel or region to two or more different conditions.
The plots in the peristimulus axes are affected by the preprocessing
controls, so users may interactively examine the effects of 
different temporal preprocessing steps.
	Note that the peristimulus plot extends for 32 seconds of 
TRs, no matter what the length of the condition; this means that
users whose conditions don’t last exactly 32 seconds should be aware
that some of the peristimulus plot may be uninterpretable.  As
well, the plot data is not convolved with an hrf function, and so
activation at the very onset of the condition may not reflect 
a physiological response to that condition; there may be a
hemodynamic lag in the response to that condition, or the activation
at the beginning may reflect the reponse to the condition that
ended just before the condition in question.





5. Output

When the user finds a region or voxel whose timeseries she would
like to preserve or analyze further, the script provides several
options both for saving the numerical timecourses it displays
and the figures themselves.  The output controls are located
in the panel at the bottom of the plot window.
	Before saving anything, the user should make sure that
she is happy with the current output directory, which is listed
on the left side of the output control panel.  If a different
output directory is desired, the change output directory button
will allow the user to select a different location.  All the 
files the script outputs are saved to the output directory 
currently shown in the figure.
	In order to save the numerical timecourses – the actual
numbers that are plotted, for further analysis or plotting – 
the user has the option of saving to a text or to a .mat file 
(a binary MATLAB variable file, readable only by MATLAB).  The
user should select their choice from the checkboxes at the bottom
of the ‘Save timecourse’ panel.  The user should then enter 
an identifying name for the timecourse.  The filename that
is saved will be based on this name, with a suffix added on that
identifies which type of timecourse it is.  The user can choose
which timecourse she’d like to save: the intensity, the full
percent signal change, or the peristimulus timecourse.  If 
the user chooses the peristimulus timecourse, the script
will save one timecourse file for each condition in the
experiment.
	Once the user has chosen a type of timecourse, a name, 
and a file extension, she clicks on ‘save’ to save the files
into the given output directory.  The script gives a brief
‘file saved!’ feedback message with the filename that was saved
(or one of the filenames, if peristimulus is chosen).
	Note that the timecourse saved is the one that is currently
displayed in the figure – from the currently selected voxel or
location.  If the timecourse saved is the percent signal or
peristimulus timecourse, they are saved with the currently selected
preprocessing options applied.
	The user may also save the figure itself – not the individual
plots, but the whole figure and its current plots.  To do so,
the user first chooses a graphics format to save as from the drop-down
menu (.jpg (a popular, interplatform standard), .tiff (an Apple
image format also usable on many PCs), .eps (a PostScript format
viewable through GhostView or other PostScript readers), or 
.png (a generic replacement for .gif, a small Web graphics
format)).  The user then chooses a filename for the saved image – 
the name listed will be the full filename.  If no name is given, 
accidentally, the script will save the image as ‘default.<extension>’
when the save button is hit.
	Once the user has chosen an image format and filename, she
clicks ‘save’, to save the image file into the currently chosen
output directory.  The script gives a brief ‘file saved!’ feedback
message with the filename that was saved.


6. Last bits

The user may close the script at any time simply by closing the image
and plot windows.

timeseries.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, as well
as the helper functions timeseries_image and timeseries_plotcontrol.

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...

