Documentation: studyplot
----------------------------
Jeff Cooper
12/4/03


1. Summary

   The studyplot utility was written by Tor Wager while he
was at Michigan as a visualization tool for meta-analyses.
It enables the user to supply a database of activation
points, with coordinates and other information like
coordinate system, color, various information about the
study itself, etc., and then have those points plotted and
labeled on a variety of different brain displays: brain
surfaces, glassbrains, or slices.  

   The script displays and plot its brains and points as
3-D Matlab figures, which canthen be rotated and zoomed
freely, as well as exported to a variety of popular
graphics formats.  The user may plot all points in a
database or select subsets of them based on any criterion
desired.  Points are always superimposed on the single
subject T1 template from SPM.


2. Usage

studyplot(<method>, 'coord_file.txt', <optional arguments>)

   studyplot is called from the command line, and can be
called from Matlab after starting either spm99-6-devel or
spm2-devel.  It always takes at least two arguments: the
first is the display method, and the second is the
filename of the database.  There are other optional
arguments that may be supplied, detailed below.

   The method argument must be one of the following strings:
      - 'glass' : a 3-D see-through brain display
      - 'glassvert' : a 3-D see-through brain display;
      points are plotted within the brain AND lines are
      projected from there onto the three cardinal planes.
      - 'surface' : an opaque 3-D brain display
      - 'surface2' : a 'brain-within-a-brain' display, in
      which there is a glassbrain and then the inner
      surface of an opaque brain, which can help highlight
      the depth of your points.
      - 'surface3' : a shiny, white, opaque 3-D brain
      display.
      - 'slices, slices2' : two different ways of plotting
      points on slices of your brain - slices always plots
      the whole brain, and slices2 allows you to focus
      your slices to display particular regions (specified
      through an optional argument)
      - 'medial' : displays rendered medial views (both
      right and left), split along the hemispheres.

   The filename argument can be any file on the path, or in
the local directory, or it can be a full-path filename.

   A basic way of calling studyplot would be:
   studyplot('surface', 'data.txt')

   Optional arguments will be described below, but first,
here's how to format your database.


3. Database Format 

   The database is a tab-delimited text file, in which
each row is a single activation point, and each column is
a different piece of information about that point; those
columns are referred to as 'fields.'  Certain fields are
required in your database; some are optional but are
interpreted in a particular way by the program.  Users may
also add their own fields for purposes of selecting
different subsets of points.

   The first two rows of the database are special rows
that contain formatting information:
   - The first row MUST be a single number - the number of
   columns/fields in the database.
   - The second row MUST be the names of the different
   fields - a header row, essentially, naming each of the
   different columns something unique.
Each row following these two contains information for one
particular activation point.  All columns must be filled
in for all rows.

   The following fields are required in the database.
There must be columns with the following names in your
data file, or the program will crash.
   - x, y and z : three columns, containing the x, y and z
   coordinates for each activation point.  These can be in
   either Talairach or MNI-space coordinates - they'll be
   converted automatically to MNI space during the progam,
   so there's no need to preprocess them.
  - CoordSys : This must be either "MNI" or "T88", to
  specify the x, y and z coordinates in this row are in
  MNI space or Talairanch space, respectively.
  - colors : This specifies the color with which this
  point is to be plotted.  It must be a single character
  specifying one of the built-in Matlab colors, which are:
      b, g, r, c, m, y, k
      standing for
      blue, green, red, cyan, magenta, yellow, black
      (respectively)
      Type 'help plot' at at Matlab window to print these
      codes out.
  - markers : This specifies what type of marker will be
  used to plot this point.  It must be a single character
  specifying one of the built-in Matlab markers, which
  are:
      ., o, x, +, *, s, d, v, ^, <, >, p, h
      standing for
      point, circle, x-mark, plus, asterisk, square,
      diamond, down triangle, up triangle, left triangle,
      right triangle, pentagram, hexagram (respectively)
      Type 'help plot' at at Matlab window to print these
      codes out.

   The following fields are optional in the database, but
if they are present, they will be specially interpreted by
the program and used:
   - markersize : This specifies what size this point's
   marker will be plotted.  If this field isn't present, a
   default size of 6 is used (arbitrary Matlab units).
   - study : This is a postive integer number that
   identifies which study this point came from - each
   study in your database gets a number, although it may
   have many points.  If the 'numbers' argument is used
   (see below), this field must be present, and if it is,
   the program will plot the study number at the given
   coordinates instead of a generic marker.
   - string : This is some text string.  If the 'text'
   argument is present (see below), this field must be
   present, and if it is, the program will plot this
   string at the given coordinates instead of a given
   marker. The text will be color as the 'color' field
   specifies.
   - fontsize : If the 'text' argument is used, this field
   specifies what size this point's text should be plotted
   at.  If this field isn't present and the 'text'
   argument is used, a default font size of 14 is used.

   The user may also specify any number of other fields,
each with some unique name.  The value of the information
in those user-specified columns can be text or numbers.
These columns can be used to specify details about the
study - say, what gender the participants were, or whether
it was an encoding or retrieval study.  That information
can then be used to pick out a subset of points to plot,
with the 'select' argument (see below).

   A sample database can be found in the studyplot
directory (type 'which studyplot' to find out where that
is) - sample_studyplot_data.txt.  Check that out for a
look at a properly formatted database.


4. Optional Arguments

   There are several optional arguments that can the user
can specify to studyplot following the display method and
the database file.  They will change the displayed
points in various ways.  These arguments can be supplied
in any order following the coordinate file, but some of
them require additional arguments to follow them
immediately.  Some examples are down below.

   These arguments can be supplied without any additional
arguments, in any order following the database file:
   - 'text' : This argument will cause the program to
   plot each point as a text string, instead of as a
   marker point.  Using this argument requires that the
   'string' field be present in the database, to specify
   which string goes with which point.  If this argument
   is used, the 'fontsize' field may optionally be present
   in the database, to specify what fontsize is used for
   each point's text.
   - 'numbers' : This argument will cause the program to
   plot each point as a number, instead of as a marker
   point.  Using this argument requires that the 'study'
   field be present in the database, to specify which
   number goes with which point.  If this argument is
   used, the 'fontsize' field may optionally be present in
   the database, to specify what fontsize is used for each
   point's text.  Note that 'numbers' and 'text' can't be
   used together - if they are, the program will issue a
   warning and ignore the 'numbers' argument.
   - 'contour' : If 'slices' or 'slices2' is the display
   method, supplying this argument will cause the program
   to additionally display a contour map of the slices
   shown and plot the points on top of that as well.  If
   any other display method is used, this argument is
   ignored.
   - 'dist' : This argument will cause the program to
   output a cell array as its first output; that cell will
   have a 2-D array inside containing between-point
   distances for each pair of points in the database.
   - 'cblm', 'bg', 'amy' : If the display method is
   'slices2', the user may supply one and only one of
   these arguments, which will cause the program to only
   display a subset of slices in the brain.  Each subset
   is intended to highlight a different anatomical
   structure - 'cblm' the <not sure>, 'bg' the basal
   ganglia, 'amy' the amygdala.  If any other display
   method is used, these arguments are ignored.

   These arguments each require an additional argument to
be supplied immediately after itself:
   - 'handles' : This argument must be followed by a row
   vector of existing axis handles at least as long as
   will be needed by the particular display method (i.e.,
   glassbrain needs at least 3, surface3 and medial need
   2, surface needs 1, etc.).  This argument will cause
   the program to draw its output surfaces and plots in
   pre-existing axes, rather than creating new figures for
   each one.  It can be useful, for example, for forcing
   the program to make all 3 glassbrain windows come out
   in a single figure (by giving it subplot handles).
   - 'cdef' : This argument must be followed by a string
   which names one of the fields in the database file.  If
   it is used, the program will ignore the 'colors' field
   in your database file and instead ask you to assign each
   level of the named field to a different color.  This is
   useful, for example if you want to quickly separate
   studies with two different valence levels (assuming
   valence was a field in your database), and don't want to
   re-code the whole database.  You could use 'cdef'
   followed by 'valence' and assign each valence level a
   new color.
   - 'select' : This is a powerful argument which will
   cause the program to only plot a subset of points,
   rather than all the points in the database file.  This
   argument must be followed by a string that specifies an
   operation to be performed on some field or combination
   of fields and results in a 1 or 0 for every row of the
   database.  For example, if I wanted to only plot points
   above z = 0, I could use 'select' followed by 'z >=
   30'.  Or if I only wanted to plot studies I'd colored
   blue, I could use 'select' followed by 'strcmp(color,
   'b').  I can combine these with logical operators if I
   like - so 'select' followed by '(z >= 30) &
   (strcmp(color, 'b'))' is OK.  Note that the selection
   string must be specified as a string - i.e., with
   single quotes around it.  This argument is useful for
   quickly picking out a subset of points to visualize
   from a large database, and is more useful the more
   information about each point you include in the
   database.


5. Sample Usage

   All of these following uses of studyplot are properly
formatted...

  studyplot('glass', 'data_file.txt')
      - this is a basic usage
  studyplot('surface', 'data_file.txt', 'handles', h,'numbers')
      - If h was a vector of at least one axis handle,
      this would work and make the program plot points
      into the axis whose handle was h, plotting points by
      numbers specifed in the 'study' field.
  studyplot('slices', 'data_file.txt', 'text', 'cdef',
  'valence', 'select', '~strcmp(valence, 'pos')')
      - This would plot slices, and plot text strings at
      each point.  It will only plot points whose valence
      is not 'pos,' and it will ask the user to supply
      colors for all the other levels of valence, and use
      those colors instead of the ones in the database.


