------------------------------------------------
 The SessionsTools -> View Functional Data sets
 up to paint 3D statistics onto high resolution
 3D data sets (medit) or onto different views
 of the cortical surface (surfer)
------------------------------------------------
The basic layout of this panel (scan directories
to the left, common action button at the top,
pages of parameters to the right) is similar to
the other SessionTools panels.  For more details,
see Help -> Setup Align/Funct.

First select a scan directory at the left and
click "Render Stats Dir" at the top to get a new
page of parameters.  Each field in the page is
described from top to bottom.

Painted Vertex List Prefix (VtxList Pref)

This is the stem for files that are generated
when you hit the PAINT button on functional
analysis panels.  The full files (for the right
hemisphere) may have the following forms:

 <stem>-rh.w      real data (e.g., corr)
 <stem>f-rh.w     signed F-stats exponents
 <stem>_r-rh.w    real comp of Fourier
 <stem>_i-rh.w    imaginary comp Fourier

These files contain lists of vertex-number/value
pairs.  These values can be rendered onto any
transformation of a surface (folded, unfolded,
flattened patch, etc) that has the same number of
vertices.

When you select one of the stems that has an
infix (e.g., _r, _i, f), the infix is
automatically stripped off (the polar, eccen
and twocond scripts use this stem to read two
files).

The set of radiobuttons directly to the right 
of the Painted VtxList Pref selector allow the
the rendering of multiple extracted sub-briks
from a single scan directory.  The options are:

 one  -- render selected (single) vertex file
 last -- render all vertexfiles from last extract
 all  -- render all vertexfiles (except complex)

When the multiple-render options are clicked, 
the selected vertex file changes to "-multiple-".
The stems of the output rgb files in that case
are the same as the stems of the sub-briks.

Saved Images Prefix

This is the name of the stem of the bitmap(s)
that will be generated when SURFACE-STATS or
VOLUME-STATS is run.

Stat Color Scales

There are four color scales available from csurf,
some of which have more than one behavior.  Other
less common color scales are available from the
large version of the surfer tools panel.

  Colwheel (w1)

  This color scale was originally designed for
  phase-encoded data (e.g., retinotopic
  mapping).  The hue represents the phase and the
  saturation represents the strength of the
  response.

  With integral anglecycles (1,2,3), the scale is
  red(early)->blu(intermed)->grn(late) wrapping
  around at red.  This is used for eccentricity
  data or two-condition data.  With anglecycles=1
  each phase has a unique color.  To compensate
  for hemodynamic delay, angleoffset should be
  decreased (-0.1 same as 0.9).  To convert
  angleoffset into seconds, multiply it by the
  time for one cycle.

  With anglecycles set to a non-integral number,
  there is only one red->blu->grn cycle.  In this
  mode, phase values below red are clamped to red
  and phase values above green clamped to green,
  each fading to gray.  To completely remove half
  of the phases opposite to the red->blu->grn,
  use truncphase (oldcsurf only).  Truncphase has
  no effect with integral anglecycles.  For
  non-integral angleoffsets between 1 and 2,
  there is an additional 1/6 of a cycle offset
  not seen with angleoffsets between 2 and 3 (the
  normal usage).  Thus, these pairs will color
  phases (in the first cycle) equivalently:

                   anglecycles   angleoffset
                   -----------   -----------
    integral          1.0           0.0
    non-integral      1.0001        0.1666

    integral          2.0           0.0
    non-integral      2.0001        0.0

  To see only strongly activated regions, set
  fmid to 1.5, fslope to 1.5, and fthresh to
  0.3.  If the absolute threshold (fthresh) is
  kept low, fmid can be used to adjust the
  effective threshold without introducing
  artifactual edges.

  It is difficult to represent the full range of
  exact values of phase using color alone.  A
  more fine-grained representation can be
  obtained by running the phasemovie.tcl script
  from Surfer Tools.  This steps through each
  phase (total number of steps adjustable),
  drawing a white contour line for a small range
  of phases (width of range adjustable).  With
  invphase and revphase off, the white phase
  marker progresses from regions responding best
  to the beginning of each stimulus cycle toward
  regions responding to the end of the cycle.

  Pseudocode for non-integral anglecycles:
    find amplitude from real/imaginary
    trunc amplitude to zero below fthresh
    run non-trunc'd amplitude through sigmoid
    find phase from real/imag in -0.5 to 0.5
    if reverse => take negative of phase angle
    if inverse => add 0.5 to phase angle
    subtract angle_offset from phase angle
    fmod/add-1-to-neg => phase back in 0-1
    [truncphase currently broken -- don't use]
    if truncphase => zero outside 0.25 to 0.75
    subtract 0.5 from phase angle
    multiply phase angle by anglecycles
    if less than -1/3 => red
    if less than 0    => red to blue
    if less than 1/3  => blue to green
    greater than 1/3  => green
    fade ipsilateral colors (def: fadef=0.7)
    fade into two background grays

  Heatscale (ht)

  The heat color scale here represents the
  significance of the response and has two main
  behaviors.

  With fourier-analyzed (complex) data, the heat
  scale runs from dark brown to white and
  displays any brain region significantly
  activated in a periodic fashion (i.e., all
  phases).  Truncphase can be used to truncate
  half of the phases and angleoffset controls the
  exact half that are truncated.  The angleoffset
  for two condition expt with 30s ON and 30s OFF
  should be something like:

    1.0 - (hemodynamic_delay + 1/4cycle)
    1.0 - (0.15 + 0.25) = 0.6

  The heat color scale can also be used to
  display F-statistics.  The analysis performed
  by the Fourier panel generates a third file,
  <stem>f-$hemi.w.  This will be read in if (1)
  the Complex button is *un*-set, and (2) the
  twocond tcl scripts are used in place of the
  polar or eccen tcl scripts.  Unlike the first
  heat scale, this one is calculated for a single
  delay, settable when FOURIER is run in the
  Fourier panel (changing this delay does *not*
  affect the color wheel and complex heat scale
  statistics).  Foci activted by ON-first are
  red->yellow while foci activated by OFF-second
  are blue->lightblue.  This scale can be
  truncated with truncphase and reversed with
  invphase (surfer tools).  The values of fthresh
  and fmid represent negative powers of ten of
  p-values.  Foci visible with fmid set to 4.0
  are strongly significant.  The scale bar values
  are:

    threshold        = fthresh
    full red/blue    = fthresh + fmid
    full yellow/cyan = fthresh + fmid + 1/fslope

  Blue/Red->white (BRw)

  Two-condition statistic color scale for real,
  signed data.  Red positively correlated; blue
  negatively correlated (reversible with
  revphaseflag).  As significance increases,
  scale goes to white for both positive and
  negative correlations.  Not affected by
  angleoffset, anglecycles, invphase (N.B. this
  scale will give spurious results if it is used
  to display complex data).

  Fieldsign (fs)

  This binary color scale is designed for field
  sign data only.  Yellow is mirror-image field
  sign and blue is non-mirror-image fieldsign.
  Reversible with revphaseflag.

Smoothing Steps on Surface

Controls how many nearest-neighbor smoothing
steps are done before display.  These are
performed on the finer mesh of the surface, not
on the coarser mesh of the functional scan.  To
see the effects interactively, use the surfer
tools SMOOTH button with the radio button set to
'val' (operates on data currently on the top of
the value stack).

Statistical Threshold (fthesh)

This is a hard thresh.  The meaning of the
value depends on the current scale.

Statistical Contrast (fslope)

Controls the steepness of a sigmoid (or a double
sigmoid in the case of two-ended color scales).
Larger values make the color scale change more
rapidly for a given change in a statistic.

Statistical Midpoint (fmid)

Sets the location of the fastest changing part of
the sigmoid (or of a double sigmoid for two-ended
scales).  This is typically used to set the
effective threshold.

PhaseReverse (revphase), Offset (angleoffset)

The phase can be reversed, and an offset can be
added to it independently for the two
hemispheres.  The Offsets (angleoffset) are only
relevant for complex-valued color scales
(colwheel, heatscale w/complex on).

Color Wheel Cycles

Integral values for the color wheel cycles cause
the color wheel of phases to wrap around one or
more times while non-integral values cause there
to be one cycle through the color wheel with
phases off its ends clamped to the ending color
(see 'Colwheel' above).

Complex

Indicates that the statistical data is
complex-valued (use colwheel and heatscale).  To
see F-stats, select heatscale, *un*select
Complex, and select twocond scripts.

Truncphase

Truncate one half of the phases of the response
to zero.  Color-scale-dependent behavior (see
above).

MM Scale, Col Scale

Turn the millimeter and color scales on or off.

Views

These buttons select which views will have a
bitmap saved for them when SURFACE-STATS is
clicked.  The 'cust' view (custom) is a special
case.  Clicking it will expose an additional 12
fields than can be used to define a custom view
for each hemisphere.  If this is done for the
current scan dir, the next scan dir that is
defined as a "Render Stats Dir" will
automatically start with the current 'cust'
values. The transformations listed are applied
left to right.

3D and Flat Tcl Scripts

These tcl scripts control the startup of the
surfer tools.  These scripts are found in
FreeSurfer/lib/tcl/*.tcl.  For retinotopy, use
eccen, polar, and fs.  For phase analysis of two
condition, use eccen or twocond.  For real-valued
data read in from external programs (e.g.,
correlation coefficients), use real.
