-------------------------------------------
 The File -> New Functional menu creates a new
 blank functional session directory and its
 standard subdirectories
-------------------------------------------
This is the first step in making a new session.
A new functional session directory and a standard
set of subdirectories in it is created.  The
default location for the new session is the
current setting of the environment variable,
FUNCTIONALS_DIR, but a functional session can be
made anywhere.

Finding sessions by date or initials is much
easier with the csurf interface if multiple
sessions are stored in the same FUNCTIONALS_DIR.

The standard functional session directory
structure is:

 FUNCTIONALS_DIR (root of a sessions database)
    sessionname		usu. year+month+day+initials
       name                ASCII file (SUBJECTS_DIR directory)
       image		   directory of scans
          scripts		      configs, NOTES file
          rgb		      saved tiff or SGI-rgb bitmaps
          mpg		      saved mpeg movies
          alignscan		      T1-weighted alignment scan
          functscan1		      functional scan1
          functscan2		      functional scan2
          . . .

When the functional session is made, it prompts
you to find a subject somewhere that contains the
surface for this functional.  The subject must
already exist somewhere.  This linkage is saved
in a file, "name", inside the session directory
containing only the SUBJECTS_DIR directory name
of the subject (e.g., martys).

Once the functional session has been made, a
subdirectory for each functional scan should be
made in the image subdirectory.  Then, the
individual scans for that session should be
copied into the separate subdirectories.  The
tools in the SessionTools menu provide a
graphical interface to do this.

You can give the scan subdirectories any name
besides the names of the standard subdirectories
but it is extremely helpful to number them so
they sort in the order in which were acquired.
Also, it helps to add an informative suffix to
each name (e.g., the name of the stimulus
program), since the directory names are what are
used to select scans in the interface.  For
example:

  $FUNCTIONALS_DIR/somesession/image/1-smfaces/*
  $FUNCTIONALS_DIR/somesession/image/2-bigfaces/*
  $FUNCTIONALS_DIR/somesession/image/3-words/*
  ...

The alignment scan (in directory "alignscan"
above, but can be any name) is a T1-weighted scan
taken in the same orientation and with the same
slice block center as the functional scans.
Typically, it has thinner slices, smaller
in-plane pixels, and more coverage than the
functional scan.

The alignment scan is used as an initializer step
in aligning the functional data with the scans in
the subjects database that were used to make the
surfaces for this subject.  This initial easier
registration can then be copied to the functional
scan directories and refined.  This end result of
this procedure is a transformation matrix that
allows 3D statistical measures calculated from
the functional scans to be 'painted' onto the
cortical surface (possibly after first moving
along the local surface normal).

When functional data covers the entire brain,
this step can be skipped, and functional scans
can be directly registered to the T1-weighted
scans used to make the surface.  However, when
functional scans only cover a portion of the
brain, this step is quite helpful to initialize
the rotation.

FUNCTIONALS_DIR and SUBJECTS_DIR

It is possible to keep subject directories and
functional directories together in the same
directory -- that is, to set FUNCTIONALS_DIR and
SUBJECTS_DIR to the same directory.

It is also possible to embed a functional session
inside of the subject it refers to.  This is done
by first making the subject (File -> New Subject,
or MGHTools -> Run recon-all) and then
subsequently making the session (File ->
Functional), but choosing the already existing
subjectdir as the functional session.  This works
because the functional data and all the panel
configurations will all be inside the "image"
subdirectory.

HOWTO view/render bare vertexlist files (wfiles) with csurf

Here is how to make a set of bare wfiles (assumed
to be for subject "marty", and assumed to be
currently sitting in /tmp/wfiles/*), conveniently
csurf-accessible for rendering and saving
rendering parameters in a new session named
110601MS, inside of a scandir named "polar".

Note that in order for a wfile to appear in the
SessionTools -> View Functional Data "Paintfile:"
dropdown, it must end in either "-rh.w" or
"-lh.w":

  cd $FUNCTIONAL_DIR
  mkdir 110601MS
  cd 110601MS
  mkdir image
  echo marty > name
  cd image
  mkdir scripts rgb mpg polar
  cp /tmp/wfile/*-?h.w ./polar

Then, using csurf:

  csurf (or File -> Update Subjects & Functs)
  File -> Open Functional  => pick 110601MS
  SessionTools -> Setup Align/Funct Scans
    click "FunctScan Dir" for "polar"
    [leave all parms blank]
    Save/Close
  SessionTools -> View Functional Data

This can be useful for saving/documenting
detailed rendering parameters in the csurf
SessionTools -> View Functional Data panel.
