------------------------------------------
 SessionsTools -> View Functional Data views
 3D stats on high resolution 3D underlay
 (tkmedit) or cortical surface (tksurfer)
-------------------------------------------
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.  Select/verify hemisphere,
and surface or patch, and then click
SURFACE-STATS or VOLUME-STATS to start tksurfer
or tkmedit for surface or volume render using
current parameters.  See log for (verbose!)
command line arguments generated for tksurfer and
tkmedit.

Startup rendering parameters can be interactively
adjusted in tksurfer and tkmedit, but will not be
saved there.  Enter final choices in View
Functional Data panel and use "Save" or
"Save/Close" at bottom panel for correct new
startup.

Double-click between the bottom 3 buttons to
raise the main csurf panel (useful with multiple
csurf's).

Clicking the "fsavg" checkbutton at top right
before clicking SURFACE-STATS causes current
paintfile (and optionally statmask paintfile) to
be resampled onto the icosahedral fsaverage
surface (resampled paintfiles will have an
"fsavg-" prefix), and then displayed on one of
those surfaces.  This is a one-time operation
(checkbutton auto-unclicks when done).  To pick
an fsaverage display surface type not present in
dropdown for current subject (e.g., inflated_avg)
type into "surface:" (or "patch:") entry and hit
Return.  R-click help explains other options
(resample to other hemi, other subject).

The panel is described top to bottom.

Paintfile (amplitude or statmask)

This is the stem (minus real/imaginary infixes,
hemisphere, and .w suffix) for files that are
generated when you click the PAINT button on the
Fourier panel (after FOURIER) or the PAINT button
on the Import 3D Stats panel (after EXTRACT/
CONVERT), or the cross subject surface stats
generated when you click SPHEREAVG or SAMP2SUBJ
on the Cross Sess Spherical Average panel.  The
full files (for, rh, the right hemisphere) usu.
have one of the following forms:

Real-Valued  (csurf output, often stats from complex data)

 <stem>-rh.w		generic real data (no infix)
 <stem>_a-rh.w		amplitude of complex _r,_i vector 
 <stem>_b-rh.w		xsub t-stats for power, _a^2, vs. num
 <stem>_c-rh.w		stimfreq_amp/sqrt(sum(noisefreq_amps^2))
 <stem>_d-rh.w		vector dispersion index (0-1)
 <stem>_e-rh.w		xsub Rayleigh pos -log10(p)
 <stem>_f-rh.w		Hagler xsub cpx F-stats from _x, _y
 <stem>_f-rh.w		real or cplx F-stats for single subj
 <stem>_g-rh.w		Hagler xsub cpx F-stats from _r,_i
 <stem>_h-rh.w		xsub cluster-filtered F-stats (_x, _y)
 <stem>_h-rh.w		single subj cluster-filtered F-stats
 <stem>_j-rh.w		TODO: like _h but from _g (vs. _f)
 <stem>_k-rh.w		find_retin_borders vtxwise border cnt
 <stem>_p-rh.w		singsub cplx permutation test -log10(p)
 <stem>_q-rh.w		singsub cluster-filtered _p
 <stem>_t-rh.w		t-stats for ampl, _a, vs. num
 <stem>_%-rh.w 		raw FT amplitude conv. to percent resp
 <stem>.mgh             FSL/freesurfer file (N.B.: no hemi!)
 -----------------------------------------------------
 <stem>f-rh.w		DEFUNCT:signed 1sub F-stat exp(no _)

Real-Valued  (3dDeconvolve output, conv'd to vertex list)

   [vers1, old]
 <cnd>_@LC@_coef-thresh+orig				thresh'd HDR area
 <cnd>_F-stat-clust+orig				clustered F
 <cnd>_t-st-clust+orig				clustered t

   [vers2, current]
 <cnd>_GLT@0_Coef-clust+orig			clustmasked HDRarea
 <cnd>_GLT_Fstat-clust+orig				clustered F
 <cnd>_GLT@0_Tstat-clust+orig				clustered t

Complex-Valued  (csurf phase data)

 <stem>_r-rh.w		phase stats (real), amp=sqrtF
 <stem>_i-rh.w		phase stats (imag), amp=sqrtF
 <stem>_x-rh.w		raw Fourier (real) at stim freq
 <stem>_y-rh.w		raw Fourier (imag) at stim freq

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

When one of the stems with a complex-component
infix is selected (e.g., _r or _i), the infix is
stripped off because the polar, eccen and twocond
scripts use the infix-stripped stem to read two
files).

The {_i, _ r, _a}, {_x, _y}, and {_f, _h, _p, _c}
files may either be single subject data or cross
subject averages.  The other infixes (_t, _b, _g,
_d, _k) usually signify other cross subject,
second level statistics.

The file here can have one of three data formats
that are auto-detected by the tksurfer function,
read_binary_values:

 .w -- valfile fmt: vtxnum/floatval pairs, maybe vtx subset
 .w -- curvfile fmt: just floatvals, all vtxs, implicit nums
 .mgh -- pseudovol fmt: 1frame, 1D, float, all vtxs

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.

StatMask Paintfile

This is the stem (minus hemisphere, and .w
suffix) for files that are generated by one
of the following panels:

  SessionTools -> Calculate 3D Fourier Stats
  SessionTools -> Calculate 3D Rand Block Stats
  SessionTools -> Import 3D Stats
  CrossSessTools -> Cross Sess Sphere Avg

These files may thus contain real-valued
statistics for either single- or cross-subject
amplitude data (the data can be either real- or
complex-valued, see examples above).

These files will be used to mask real- or
complex-valued Paintfile data, but will not be
directly visible as such.  To display/view these
files directly, they can instead be read in as a
Paintfile (see above).

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.

ResetToDefault

These buttons ("eccen", "polar", "2cond",
"fstat", "real", "fs") reset all the color scale
variables on the panel below to sane defaults for
each experiment type.  These are the values that
intially appear when the panel is first created.

The last button on this line, "cp prev" copies
parameter values from the previously selected
scandir (left column) into the current scandir.
All parameter values below the "ResetToDefault"
line are copied.

Data Type

These five button choose one of five different
types of functions that set the color of each
surface vertex -- "phase", "real", "real+Fmsk",
"real+tmsk", and "fs+msk".

The first button (phase) displays the phase using
color and the significance by modulating the
color saturation.  This is the original
retinotopic color scale.  There are an additional
set of buttons (off/repl/mask/mult) further down
the panel for alternative statistical masks for
complex valued data (see below).  The original
default was to replace the vector amplitude with
the (sqrt F) significance.

The second and third button ("real+Fmsk",
"real+tmsk") perform a double-sigmoid masking of
the visible amplitude (color saturation) of the
data.  The first sigmoid squashes the displayed
amplitude (controlled by fslope/fmid/fthresh in
amplitude units).  The second sigmoid *also*
squashes the displayed amplitude, but now by
considering statfile (F or t) (controlled by
sfslope/sfmid/sfthresh in F or t stat units).  To
squash using only amplitude, set sfmid/sfthresh
to zero; to squash only using the statmask, set
fmid/fthresh to zero.

The last button, "fieldsign+mask", similarly
combines fieldsign (signed) and fsmask (a
geometric average of the eccen and polar
significances).

PhaseMask (SessionTools only - single subject)

When this panel is opened via SessionTools ->
View Functional Data (single subject data), there
will be a line of 3 buttons below "Data Type:"
that control the source of the mask (or if there
is one) for complex-valued single subject data --
"none:sig,amp=sqrtF", "sig+(clust)Fmask", and
"sig+coher".  N.B.: these buttons only affect
complex-valued data ("phase" Data Type).

The first button, "none:sig,amp=sqrtF", means no
mask -- i.e., just control color saturation with
the complex amplitude, which for Paintfiles _r,_i
is the sqrt F and for Paintfiles _x,_y, the raw
fourier amplitude at the stimulus frequency.

The second button, "sig+(clust)Fmask", displays
the Paintfile (subject to the first soft
threshold), but then also does a second soft
threshold by comparison to the surface-based
cluster-corrected F stat (the StatMask
Paintfile).

In this case, the first set (left column) of
entries (fthresh/fmid/fslope) are in signal
amplitude units for the Paintfile.  If the
Paintfiles are _r,_i Paintfile (i.e., complex
amplitude replaced by sqrtF), typical values are
~1-5.  If the Paintfiles are _x,_y (raw fourier
amplitude), typical complex amplitude values will
be 100-300.

The second column of entries immediately to right
of fthresh/fmid/fslope (sfthresh/sfmid/sfslope)
independently modulate the saturation of the
overlay color by making a comparison with the F
mask value at that vertex (e.g., 2-10).

Finally, to use the coherence (instead of F) as a
mask, select "sig+coher" (which will auto-set _c
as a mask).  Note that sfmid/sfthresh values
appropriate for coherence (0.20 to 0.25) are much
lower than for F (2.0 to 10.0)

Clicking back and forth between these three
buttons enables/disables the extra stat threshold
entries, toggles stat mask on/off, auto-sets the
appropriate StatMask Paintfile (if it's there),
puts up a popup to query whether to reset signal
and mask thresholds to sane values.  The last
popup also comes up if "FTamp" (use raw Fourier
amplitude, _x,_Y, instead of sqrtF, _r,_i) is
ticked/unticked.

XSubPhasePhaseMsk (CrossSessTools only)

When this panel is opened via CrossSessTools ->
View SphereAvg Data, there will be a line of 6
different buttons below Data Type that control
the source of the mask for complex valued cross
subject data -- "sig", "cxF-amp", "cxF-sig",
"cxR-ang", "t-sig", "t-pow".  These buttons only
affect complex-valued subject averages ("phase" Data
Type).

The average unmasked amplitude displayed is
either the average of single subject sqrt F if
Paintfiles are _r,_i (orig csurf) or the average
of the single subject raw Fourier amplitude at
the stimulus frequency if Paintfiles are (_x,
_y}.  The first button (sig) means no mask --
i.e., just show average amplitude.

N.B.: as above, the {_r, _i} amplitudes [sqrt F]
are typically in the range of 1-5 while the {_x,
_y} amplitudes are in the range of 100-300, so
fmid has to be adjusted accordingly.

The second (cxF-amp) and third (cxF-sig) buttons
use a complex-valued F mask (Hagler et al., 2007)
calculated either with the single subject raw
fourier amplitude (_f) or the single subject sqrt
F (_g).  The cross-subject statistical units
(second set of slope/mid/thresh entries) in both
cases are raw F's, not p-values.

The fourth (cxR-ang) uses the result of a
Rayleigh test on the phase angle at each vertex
across subjects (Rayleigh R) converted to a
p-value.  Thus, sfthresh/sfmid in this case is in
absolute value of power-of-10 units (e.g.,
sfthresh=2.0 means truncate vertices with p >
10^-2).

The fifth (t-sig) uses a one-sample t-statistic
made by comparing the sqrtF amplitude of a fixed
value (set at compute-time in the Cross Sess
Sphere Avg panel).

The sixth and final (t-pow) uses a t-statistic
made by comparing the F amplitude to a fixed
value (again set at computer-time in the Cross
Sess Sphere Avg panel).

On selecting these buttons (except the first,
sig), the CplxAmpMod is reset to mask, and the
appropriate StatMask Paintfile is looked for,
generating an error if it doesn't exist in the
current directory.

See Help -> New Spherical Average for more
details on how the cross-subject complex-valued
statistical masks (and other indices) are
calculated.

Color Scale ($colscale)

For each data type above, several different color
scales can be chosen.  Csurf saves seven
different colscales that work with the following
data types:

  phase+sig (complex)
    wheel	($colscale = 0)
    [none]	($colscale = 13) (cplx amp)
    lutw	($colscale = 14)
    heat	($colscale = 1)
    bi	($colscale = 4)

  real
    bl/redY	($colscale = 11)
    bl/redW	($colscale = 6)
    lut	($colscale = 12) (real)
    jet	($colscale = 15)

  fieldsign+mask
    fs	($colscale = 9)

Note that colors may be displayed, even if you
chose the wrong color scale.  For example, if you
display real, one-component data with a color
scale designed for complex-valued data, zeros or
junk in the imaginary data field will result
in non-meaningful colors.  Conversely, displaying
complex data with a real color scale will only
show the real component.

Some less common color scales can be found on the
large version of the surfer tools panel ([fn]-F3
in tksurfer interface window; [fn]-F2 to get
back).

Here are the main types of color scales:

  (1) w1: Color Wheel Complex (colscale=0)

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

  With integral angle_cycles (1,2,3), the scale
  is red(early)->blu(intermed)->grn(late)
  wrapping around (through orange) back to red.
  This can be used for eccentricity data,
  tonotopy, or somatotopy data or two-condition
  data.  With angle_cycles=1 each phase has a
  unique color.  To compensate for hemodynamic
  delay, angle_offset should be decreased (-0.1
  same as 0.9).  To convert angle_offset into
  seconds, multiply it by the time for one cycle.
  For a thin expanding ring stimulus starting
  from the center, the angle_offset should be set
  to 0.75 to color the central representation
  red.

  With angle_cycles 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
  as the phase enters the ipsilateral field.
  Each then fades to gray at mid-ipsilateral
  phases.  The fade ramp extent is set by fadef
  ("fad" in Surfer Tools).  Ipsilateral phases
  can be also be colored yellow (strongest yellow
  at mid ipsilateral) with ipsiyellowfact ("iy"
  in Surfer Tools).

  To completely remove a portion of the phases in
  the red->blu->grn, use truncphase.  The low and
  high truncation limits are adjustable for the
  RH and LH (default: 0.25 to 0.75; variables:
  truncphasemin and truncphasemax).  For
  non-integral angle_offset between 1 and 2,
  there is an additional 1/6 of a cycle offset
  not seen with angle_offset between 2 and 3 (the
  original design target).  Thus, these pairs
  will color phases (in the first cycle)
  equivalently:

             angle_cycles  angle_offset
  --------------------------------------
  integral       1.0             0.0
  non-int.     1.0001          0.1666
  
  integral       2.0             0.0
  non-int.     2.0001          0.0
  --------------------------------------

  With angle_cycles set below 2.0, this scale can
  be used for eccentricity, tonotopy, or
  somatotopy data as well.  The color scale will
  fade to gray at the wrap around point.

  To see relatively only moderately strongly
  activated regions with default sqrtF, set fmid
  to 1.5 (F=2.25), 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.

  The units of fthresh and fmid are the same;
  fthresh is a hard threshold and fmid is a soft
  threshold.  Setting fthresh equal to fmid will
  truncate the sigmoid tanh curv controlling
  color saturation to the background gray in the
  middle most-rapidly changing part of the tanh
  sigmoid.

  It is difficult to represent the full range of
  exact values of phase using color alone; a
  large number of colors are hard to parse, while
  fewer, easier-to-parse colors (as here) do not
  represent phase finely enough.  A fine-grained
  representation can be obtained by running the
  phasemovie.tcl script (in tksurfer "tcl:"
  dropdown).  This steps through each phase
  (total number of steps adjustable), drawing a
  white contour line for a small range of phases
  (width of phase range is 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.

  Mapping stimuli that start horizontal

  For a counter-clockwise rotating polar angle
  stimulus that starts at the right (zero deg),
  the default settings for Phase/Rev,Offset in
  the View Functional Data panel are (ignoring
  hemodynamic delays):

  Phase/Rev,Offset: [ ] "RH" 0.0   [x] "LH" 0.5

  Note that the offset for the right hemisphere
  is zero when the stimulus starts in the right
  hemifield, which is counterintuitive, but,
  unfortunately now conventional.

  These settings result in brain regions
  representing the contralateral upper field
  being colored red, brain regions representing
  the contralateral lower field colored green,
  and the brain regions representing the
  contralateral horizontal meridian colored blue,
  in *both* hemispheres.

  These settings need to be adjusted if the
  stimulus not counter-clockwise, start right.
  For example, for a *clockwise* rotating polar
  angle stimulus that also starts right, reverse
  the opposite hemisphere:

  Phase/Rev,Offset: [x] "RH" 0.0   [ ] "LH" 0.5

  For a counter-clockwise rotating stimulus that
  starts on the left, use RH offset=0.5 and LH
  offset=0.0, and so on.

  Mapping stimuli that start vertical

  For a clockwise rotating polar angle stimulus
  that starts at the *top* (e.g., a stimulus that
  first enters the top right hemifield or the top
  right side of the face), you have to add a
  quarter cycle to the values above.  Since one
  hemisphere is reversed, the quarter cycles make
  the angle offsets the same for both hemispheres
  (again assuming no hemodynamic delay).

  Phase/Rev,Offset: [x]"RH" 0.75  [ ]"LH" 0.75

  If a clockwise stimulus starts at the bottom,
  then the offsets should both be set to 0.25

  The included program "wheel" is an interactive,
  standalone program that renders a color disk or
  rectangle (which additionally shows the effect
  of fthresh and fmid on the y-axis) that can be
  controlled by the same parameters as the
  eccen/polar color wheel scale (fthresh, fmid,
  fslope, angle_cycles, angle_offset, offset,
  cvfact, fadef, ipsiyellowfact).  Start it like
  this:

    wheel <0-3> [opts]

  and adjust rendering parameters with F1-F12 or
  by adding command line options (for help, type
  "wheel" without arguments).  The same code is
  used to draw the color wheel/disk inset.

  Pseudocode for non-integral angle_cycles:
    find amplitude from real/imaginary trunc
    if stat{repl,mult}ampflag, replace,multiply
    if mask, if stat below fthresh, backgrnd col
    else     if amp below fthresh, backgrnd col
    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
    if truncphase => zero outside bounds
    subtract 0.5 from phase angle
    multiply phase angle by angle_cycles
    if less than -1/3 => red fade to gray
    if less than 0    => red to blue
    if less than 1/3  => blue to green
    greater than 1/3  => green fade to gray
    ipsi fade to gray control: fadef (def=0.7)
    low amps fade into two background grays

  (2) w2: GBRY Color Wheel Complex (colscale=8)

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

  Color smoothly changes across 360 deg from:
  green -> blue -> red -> yellow.

  (3) w4: Fred Tonotopy Color LUT (colscale=18)

  This color scale is designed for complex-valued
  phase-encoded tonotopy data.

  (4) lutw: Look-Up Table, Complex Phase (colscale=14)

  Read arbitrary phaseval->RGB color lookup
  table.  For automatic read, put file named
  "val2rgb.lut" in current scandir.  This scale
  requires that complexvalflag is set ("cpx").
  The format of the ASCII lookup table is:

    # comment
    phaseval1 red green blue
    phaseval2 red green blue
    ...

  where the phaseval's are in ascending order
  (not necessarily evenly spaced), and 0-255 for
  red/green/blue.  If interpolatelutflag is set
  ("intplut"), then the r,g,b's are linearly
  interpolated for intermediate phaseval's, else
  the colors stay the same to halfway to the next
  phaseval in the lookup table.

  This color scale expects the phasevals to be in
  the range of 0-1 and expects them to wrap
  around (interpolating around the wrap point if
  "intplut" ticked).  If rgb2val.lut doesn't
  exist, a default version (for real, eccen, or
  polar data (depending on current setting of
  "Reset To Default") will be created.

  (5) heat: Heatscale Complex (colscale=1)

  The heat color scale requires complex-valued
  fourier-analyzed data.  It 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 angle_offset
  controls the exact half that are truncated.
  The angle_offset for two condition expt with
  20s ON and 20s OFF should be something like 0.1
  (this is in units of one cycle: 0.1 * 40 sec =
  4 sec delay).

  (6) bi: Red/Green Complex (colscale=4)

  The red/green bipolar scale requires
  complex-valued Fourier-analyzed data as well.
  This scale is for displaying the results of a
  two-condition experiment.  It divides the
  phases into two halves, colored red and green,
  with the boundary between half red and half
  green settable with angle_offset ((0-Pi is red,
  Pi-2Pi is green).  At fslope=1.0, the color
  saturation of each phase is approximately the
  sine of the phase angle:

    y = tanh(fslope*(phaseangle -   0)) *
       -tanh(fslope*(phaseangle -  Pi)) *
       -tanh(fslope*(phaseangle - 2Pi))

  Thus, phases near the boundary between red and
  green will fade to gray, and full saturation
  will only be reached at a phase of Pi/2 and
  3Pi/2.  With fslope > 10, all the colors in
  each half of the phase wheel will be almost
  fully saturated.

  To use colors other than red and green for the
  two phase ranges, open the large version of the
  surfer tools panel ([fn]-F3; [fn]-F2 to get
  back) and set r,g,b values in the 6 entries
  just below the colscale buttons headed "col1"
  and "col2" (plus <Return>).

  (7) BRy: Blue/Red->yellow/cyan (colscale=11)

  This scale is designed for real-valued, signed
  (e.g., two-condition) amplitudes or statistics.
  This scale can be truncated with truncphase and
  reversed with invphase (surfer tools).

  Unlike any of the complex-valued color scales,
  (where the units of fthresh and fmid are the
  same) fthresh and fmid here control different
  parts of the range of colors.  There are two
  'knobs'. The first is fthresh, which controls
  the data value at which red fades into the
  background gray, and the negative of fthresh
  controls the negative data value where blue
  fades into the background.  The second is fmid,
  which controls data value above which red
  transitions to yellow, and the negative of
  fmid, where blue transitions to cyan.

  The scale bar color transition points are:

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

  (N.B.: if used with complex data, this scale
  will only display the real component.)

  (8) BRw: Blue/Red->white (colscale=6)

  This scale is designed for real-valued, signed
  (e.g., two condition) amplitudes or statistics.
  Positive data is red and negative is blue.
  Reversible with revphaseflag.  As the absolute
  value of the data increases, scale goes to
  white for both positive and negative
  correlations.  Not affected by angle_offset,
  angle_cycles, invphase. (N.B.: if used with
  complex data, this scale will only diplays the
  real component.)

  Unlike other color scales, the sense of fmid is
  reversed -- turning fmid up makes the
  representation of a given data value move *up*
  the color scale (toward white).

  (9) fs: Fieldsign (colscale=9)

  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.

  (10) lut: val->RGB look-up table (colscale=12)

  Read arbitrary val->RGB color lookup table,
  typically in current scandir (val2rgb.lut).
  This is designed to color a single real value.
  The format of the ASCII lookup table is:

    # comment
    val1 red green blue
    val2 red green blue
    ...

  where the val's are in ascending order (not
  necessarily evenly spaced, negative val's OK)
  and the red, green, and blue are 0-255.  If
  interpolatelutflag is set ("intplut"), then the
  r,g,b's are linearly interpolated for
  intermediate val's, else the colors stay the
  same to halfway to the next val in the lookup
  table.

  (11) jet: MATLAB Jet (colscale=15)

  The MATLAB Jet colscale: dark-blue -> blue ->
  cyan -> yellow -> red -> dark-red (flip with
  invphase).  For signed or unsigned real data,
  or complex amplitude.  Endpoints of scale
  (clamped) set using left and right entries
  under truncphase.

  Extreme values are dark, so best adapted to
  full rank data (near zero will be light
  yellowish-green).  Responds to fthresh/sfthresh
  (absolute-value of hard thresh to background
  curvature), fmid/sfmid (absolute-value of fade
  to background curv), and fslope/fslope, so for
  completely unthresholded with full color
  saturation, set fthresh and fmid to 0.0.

  If complex data has previously been read onto
  the surface, the complex amplitude will be
  displayed and the endpoints of the scale set to
  ($fthresh, $fmid*4).

  (12) vd: CARET Videen-Style (colscale=17)

  For real data (signed or unsigned) or complex
  amplitude.  Like the MATLAB Jet scale,
  endpoints of scale controlled by bottom and top
  values in unmarked entries under truncphase
  button.   Data values outside that range
  clamped to end colors.  Negative entries OK.
  Left entry should be smaller than right.

  Bottom of color scale can be truncated (allows
  BG gray(s) to show through) with fthresh.
  N.B.: set fthresh negative to avoid truncating
  signed data.  No effect of fmid and fslope.

  If the colorscale is interactively changed to
  this one interactively in tksurfer, the end
  ($truncphasemin, $truncphasemax) will be reset
  to 0-1, but can then be interactively adjusted.
  Once "vd" has selected in csurf, the saved
  'TrnPh' limits entered in the csurf panel
  will be respected on next tksurfer startup.

  If complex data has previously been read onto
  the surface, the complex amplitude will be
  displayed and the endpoints of the scale set to
  (0.0, $fmid*4).

Smoothing (of overlay data, stat mask): Surface-based

The first entry on the "Smooth: Surf(val,stat)"
line controls how many nearest-neighbor smoothing
steps are done on the val(,val2) data before
surface display of overlay data in tksurfer.  The
second entry controls smoothsteps on the stat
mask (if present). These smoothing operations 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'.  If the data is complex, both components
will automatically be smoothed.

The unlabeled tickbox immediately to the left of
the first smooth steps entry toggles the tcl
variable, $cpxangrealampflag, which switches
between two different smoothing functions.  If
unticked (default), the the standard vector
average of complex values of the center point and
its neighbors is used (C/tcl funct: smooth_val).
If ticked, an alternate function that ignores
vector dispersion is used instead (C/tcl funct:
smooth_complexang_realamp).  That function
ignores vector dispersion by averaging complex
angles, but real-valued amplitudes.  To
interactively use it, select smooth type "cr" on
large F3 panel (or middle click the "val" radio
button).

An empirically derived correspondence (Hagler et
al., 2006) between the number of smoothing steps
using the C/tcl function smooth_val (using
surfaces reconstructed from 1 mm^3 struct scans)
and the average full-width-at-half-max filter
result starting with a single non-zero vertex is:

  steps   FWHM (mm)
 --------------------
    5      2.22
   10      3.20
   20      4.49
   30      5.36
   50      6.99
   70      8.31
  100     10.15
  230     ~1.5 cm
  400     ~2 cm
  900     ~3 cm
 --------------------

A power function fit to this empirical map
(r^2 = 0.9987) is:

  fwhm = 0.9921 * steps^0.5018

Smoothing (of data/stat overlay): 3D Gaussian

The entries to the right of "3D(cells,fwhm)"
control the width of the 3D Gaussian smoothing of
3D overlay data in tkmedit (VOLUME-STATS).  This
type of smoothing does not interact in any way
with surface smoothing just described.

The first entry (must be an odd number) is the
number of cells in the Gaussian kernel, in
voxels.  The second floating-point entry, fwhm
(should be smaller than first number) is the full
with at half maximum of the smoothing kernel,
again in voxels.  For no 3D smoothing, Set the
second entry to 0.0.

The 3D smoothing specified here is implemented on
first display by VOLUME-STATS.  After startup,
the equivalent fields in tkmedit will be reset to
the default gentle smoothing (5 cells, 1.5mm
fwhm) regardless of the settings here.

Statistical Contrast ($fslope, $sfslope)

The "Contrast: DataAmpli.,StatMask" entries
control the steepness of the thresholding sigmoid
(or a double sigmoid in the case of two-ended
color scales).  Larger values make the color
scales ramp more rapidly for a given change in
data/stat amplitude.  At a steep slope of
fslope>10, the effect of fmid (the soft
threshold) is essentially the same as fthresh,
the hard threshold.

The second entry has a similar function except
that is is in statistical mask units.  It will be
grayed out for color scales that have no separate
statistical mask file.

Statistical Midpoint ($fmid, $sfmid)

The "Midpoint: DataAmplitude,StatMask" entries
set the location of the fastest rising part of
the sigmoid (or of a double sigmoid for two-ended
scales).  These are used to set an effective
threshold, but with a smooth fall-off into the
background color.

The second entry has a similar function except
that is is in statistical mask units (e.g.,
F-ratio).  It will be grayed out for color scales
that have no separate statistical mask file.

CpxAmpMod (only affects complex-valued data)

These buttons (off,repl,mask,mult) select whether
the amplitude of complex data is modulated by a
separate stat file -- a third vertex-wise value
read into the .stat field.  The stat file is
loaded automatically by this panel, but can also
be manually loaded using tksurfer tools panel as
follows:

  select stat wfile from "val:" dropdown
  R    (read: to .val field)
  [optionally SMOOTH]
  S/V    (swap .stat and .val)
  select real (or imag) wfile from "val:" dropdown
  R    (read: both real,imag given either)
  [optionally SMOOTH]

or by explicit commands in a tcl script:

  # stat (read to .stat field)
  set val <path-of-stat-wfile>
  read_binary_values
  smooth_val <smoothsteps>
  swap_stat_val
  # imaginary (read to .val2 field)
  set val <path-of-imaginary-wfile>
  read_binary_values
  smooth_val <smoothsteps>
  swap_val_val2
  # real (read to .val field)
  set val <path-of-real-wfile>
  read_binary_values
  smooth_val <smoothsteps>

If the "off" button is selected, no modulation is
done (e.g., for original freesurfer
complex-valued data that had amplitude replaced
by sqrt F).  If "repl" is selected, the data
amplitude is replaced by the vertex-wise values
from the stat file.  If "mask" is selected (the
most useful), the second set of entries (sfslope,
sfmid, sfthresh) apply a second sigmoid
modulation of the color saturation based on the
stat value (sfslope/sfmid/sfthresh units are stat
value units, whatever they may be -- e.g., F, t,
or power-of-ten-p-value).  Finally, if "mult" is
selected, the data amplitude is multipled by the
vertex-wise stat file value.  In each case, the
data *phase* is unaffected.

Hard Thresholds ($fthresh, $sfthresh)

The "(fthresh,sfthr.)" entries set the hard
cutoffs (to background surface color).  For
complex valued color scales the units for
$fthresh and $sfthresh the same as for $fmid and
$sfmid, respectively.

For some real-valued scales (e.g., BRy), $fthresh
sets the data value where the displayed color
rolls off to background gray, while $fmid sets
the red->yellow and blue->cyan transition points.

For real or complex-valued scales where a
statistical mask will be used (CplxAmpMod "mask"
selected), the second fthresh entry will be
enabled.  This performs a second hard threshold
if the *stat* value is below the setting in the
second entry.  The second threshold is typically
in units of raw F (or t).

TruncFS ($nonbinaryfsflag)

If "TruncFS" ($nonbinaryfsflag), is ticked,
near-zero *fieldsign* values are faded to
background gray, as controlled by $fsslope ("sl"
entry in surfer tools).  The nonbinaryfsflag is
the unlabeled checkbox to the left of the "sl"
entry in surfer tools.

Ipsi Fade, Ipsilateral Yellow ($fadef, $ipsiyellowfact)

The "fadef:" entry controls the speed at which
ipsilateral phases smoothly approach background
surface grays.  This only affects non-intergral
$angle_cycles color scales that are designed for
polar angle stimuli should mainly generate
activity for 50% of a stimulus cycle (there
should be less/no activity when the stimulus is
in the ipsilateral visual field).

The "ipsiyel:" entry changes the ipsilateral
phase 'fade' target from the default gray to
various amounts of yellow (maximum yellow will be
opposite maximum blue -- see effects in color
scale disk inset).

Angle Cycles ($angle_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 exactly one cycle through the color wheel
with phases off the ends clamped to the ending
color (see 'Colwheel' above).

Angle Offset ($revphaseflag, $angle_offset)

A $revphaseflag and an $angle_offset can be saved
independently for the two hemispheres.  These
affect which colors are displayed for which
phase.  Both of these are only relevant for
complex-valued color scales (colwheel=w1/w2/w4,
heat, bi).

The (unlabeled) $refphaseflag tickbox reverses
the color wheel -- e.g., to accomodate reversed
stimulus order such as clockwise vs.
counterclockwise polar angle rotation, or left
vs. right hemifield order).

The $angle_offset rotates the color wheel --
e.g., to account for hemodynamic delay.  The
$angle_offset value ranges from 0.0 to 1.0,
where 1.0 equals the time for one stimulus cycle
-- e.g., an angle_offset of 0.02 with a 64 sec
cycles corresponds to a time offset of 0.02 * 64
= 1.28 seconds.  The (uneditable) entry to the
far right of this line shows the $angleoffset
that is equal to 1 sec.

InvPh + TrnPh + Sft + 2 RH + 2 LH entries

The "InvPh" button ($invphaseflag) adds pi to the
time course: f(t) -> f(t+pi).  This contrasts
with the previously described Rev tickboxes
($revphaseflag), which reverses the time axis:
f(t) -> f(-t).

The "TrnPh" button ($truncphaseflag) uses limits
(possibly wrapped), set separately for left and
right hemispheres (4 entries to right).

The "Sft" ($softtruncphaseflag) has linear ramps
(which themselves may wrap) beyond the truncphase
limits, instead of a hard cutoff.  The width of
the ramp is set by the tcl var $softtruncwidth
(def=0.05 which is 5% of a cycle).

For the standard color wheel, the order of all
the operations mentioned is:

  f = sqrt(r*r + i*i);            /* get complex ampl */
  a = atan2(r,i)/(2*M_PI);  /* phase: -0.5 to 0.5 */
  if (revphaseflag) a = -a;
  if (invphaseflag) a += 0.5;
  a -= angle_offset;
  a = fmod(a,1.0);             /* -1 to 1 */
  if (a<0.0) a += 1.0;         /*  0 to 1 */
  if (truncphaseflag) {
    /* f=0.0 beyond limits, maybe wrapped */
  }
  if (softtruncphaseflag) {
    /* linear ramp to 0.0 (maybe wrapped) beyond limits */
  }

where f=0 allows the background color to show
through completely, and where r and i are the
real and imaginary components of the phase vector
(amplitude is e.g., sqrt F) read from wfiles
output by fourier.

Checkbuttons (cpx,FTamp,mm,scl,cv,intp,bot,sym)

 cpx	complex val data ($xomplexvalflag, usu. autoset)
 FTamp   disp raw Fourier transform amp vs. sqrtF
 mm	turn on millimeter scale ($scalebarflag)
 scl	turn on color scale inset ($colscalebarflag)
 cv	turn on background curvature grays ($surfcolor=1)
 intp	interpolate opt. color LUT ($interpolatelutflag)
 bot	LUT entries set col bott vs. cent ($botedgelutflag)
 sym	two-sided (pos/neg) thresh ($zerosymmfadeflag)

These can be controlled from tcl using the
variables listed above.

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.

To convert standard sqrt-F fmid to p in MATLAB:

  fmid = 0.0:0.1:5.0;
  plot(fmid, -log10(1-fcdf(fmid.^2,sdf,ndf))

where sdf and ndf are signal and noise degrees of
freedom.  Here is a fmid -> neg-exponent-of-p
table for sdf=2 and ndf=245:

sqrtF
fmid	F	neg exp p
-------------------------------
0.5	0.25	0.1085
0.6	0.36	0.1561
0.7	0.49	0.2124
0.8	0.64	0.2772
0.9	0.81	0.3506
1.0	1.00	0.4325
1.1	1.21	0.5229
1.2	1.44	0.6217
1.3	1.69	0.7289
1.4	1.69	0.8445
1.5	2.25	0.9683
1.6	2.56	1.1003
1.7	2.89	1.2405
 ============== 1.3000 => p=0.05
1.8	3.24	1.3888
1.9	3.61	1.5451
2.0	4.00	1.7094
2.1	4.41	1.8816
 ============== 2.0000 => p=0.01
2.2	4.84	2.0615
2.3	5.29	2.2492
2.4	5.76	2.4445
2.5	6.25	2.6474
2.6	6.76	2.8577
 ============== 3.0000 => p=0.001
2.7	7.29	3.0754
2.8	7.84	3.3003
2.9	8.41	3.5325
3.0	9.00	3.7717
3.1	9.61	4.0180
3.2	10.24	4.2711
3.3	10.89	4.5309
3.4	11.56	4.7975
3.5	12.25	5.0706
3.6	12.96	5.3502
3.7	13.69	5.6361
3.8	14.44	5.9283
3.9	15.21	6.2266
4.0	16.00	6.5309
4.1	16.81	6.8412
4.2	17.64	7.1572
4.3	18.49	7.4789
4.4	19.36	7.8062
4.5	20.25	8.1389
4.6	21.16	8.4770
4.7	22.09	8.8203
4.8	23.04	9.1687
4.9	24.01	9.5221
5.0	25.00	9.8804
-------------------------------

The noise degrees of freedom (245) are 256
frequencies (positive and negative) minus real
and imaginary at the stimulus frequency minus the
amplitudes of the nuisance frequencies, which are
defined by fourier.c as the 3 lowest frequencies
(assumed to be movement), one frequency above and
below the stimulus frequency, two higher
harmonics of the stimulus frequency, and one
frequency above and below each harmonic.

For 512 TRs instead of 256, the p-values are
slightly more significant for a given fmid.
Here are the increments in -log10(p):

  fmid=1.75: -log10(p): 1.3 => 1.31
  fmid=2.15: -log10(p): 2.0 => 2.02
  fmid=2.65: -log10(p): 3.0 => 3.04

Converting phase-encoded responses to percent

There are three ways in csurf to obtain percent
response measures from Fourier transformed
timecourses (described in more detail in
the relevant R-click helps):

(1) single vertex:

  First, load the 3D _x,_y Fourier transform data
  BRIKs.  To do this, click "val:" label to
  change it to "val3d:".  Then select _x (or _y)
  BRIK from dropdown and click "R" (will read
  both, given either).  Finally,
  ctrl-middle-click a vertex to see the
  timecourse and look in the csurf log for
  percent response.

(2) avg percent response across a label

  Find or make a label.  Then load the 3D _x,_y
  Fourier transform data BRIKs as above.
  Finally, shift-left-click "T" on "label:" line
  and find percent resp in log and on final
  popup.

(3) vertexwise percent 

  First load 3D rawdata time series
  (ctrl-middle-click on any surface vertex will
  auto-load the rawdata timecourse).  Then load
  2D _x,_y Fourier transform data wfiles by
  selecting the _x (or _y) wfile on the "val:"
  line dropdown and clicking "R" (will read both
  given either).  Finally, middle-click "W" on
  the "val:" line to get FOURIER TO PERCENT
  RESPONSE popup, and click:

    COMPUTE AVG t-SERIES EACH VTX

  to average the timecourse at each voxel, and
  then:

    COMPUTE PERCENT RESP
    
  to display vertexwise percent and also write
  out vertexwise percent a wfile with a _% infix.
  If no rawdata is available (e.g., cross subject
  phase average), enter the skip the first step
  and enter the average brightness and number of
  timepoints.

