-------------------------------------------
entry variable: $fmid -- statistical sigmoid threshold
-------------------------------------------
default: 1.1
keyboard shortcuts:
  Cmd-i,I  =>  fmid 0.1 up/down [e.g., sqrtF]
  Cmd-u,U  =>  fmid 10.0 up/down [e.g., raw fourieramp]

The "fmid:" entry is the primary way to set an
activation threshold.  It adjusts the position in
amplitude units (e.g., sqrt F-ratio) where the
overlay color contrast display color reaches 50%
saturation.  See "fslope:" to adjust contrast
(slope of the sigmoid).

Fmid effectively sets a soft threshold.  To set a
hard threshold, use $fthresh.  Setting $fthresh
equal to $fmid truncates lower half of the
sigmoid (for all color scales *except* BRy).

Typical Settings for Complex-valued Data

For Fourier-analyzed complex-valued data, the
{_r,_i} files will have amplitude replaced by
sqrt(F), so an fmid around 2.5 is a good starting
point.  The {_x,_y} files contain the raw fourier
amplitude, so an fmid around 350.0 is a good
starting point (both for unsmoothed data).

PerVertex ColorScale Pipeline Outline

  1)  get background sulc/gyrus color (to fade into)
  2a) if real data: get amplitude, f
  2b) if complex data: get complex amplitude, f
  2c) if stat mask: get optional real stat
  3)  hard threshold f to zero if f below $fthresh
  4)  if mask, hard thresh f to zero if *stat* below $sfthresh
  5)  sigmoid (tanh) transform f into 0-1 ($fmid,$fslope)
  6)  opt 2nd sigmoid transform f to 0-1 ($sfmid,$sfslope)
  7a) if real, translate f to color
  7b) if complex, trans. phase ang to col, f to col saturation
  8)  as f goes to 0, color fades to 1 of 2 background grays

In double-ended scales, there are two sigmoids
both controlled by fmid/fslope at equal distances
either side of zero.

How The Sigmoid Squashing Functions Work

The bare function y = tanh(x) is a sigmoid.  The
output, y, is about -1 for x less than -2.  The
output passes through 0 at x equals 0, and is
about 1 for x greater than 2.

The tanh function is used as follows.  The
fslope/sfslope variables control the steepness of
the transitions.  A small fslope (0.01) is
approximately linear while a large fslope (10) is
basically a step from background color to fully
saturated color at the point where input
amplitude equals fmid.  The fmid/sfmid variables
control where the transition occurs.  Here is
the outline C code:

first amplitude squash:

    f = (1 + tanh(fslope*(f - fmid)))/2;

second stat squash:

    f = f * (1 + tanh(sfslope*(fabs(stat) - sfmid)))/2;

N.B.: the appropriate fslope for the squashing
function depends on the range of the data.  In
general, fslope (steepness of sigmoid ramp)
should be inversely related to fmid (data value
at middle of ramp) and the data range, in order
to get a similar visual effect.

The discussion above assumed display of an
F-ratio or a z-score (0-10).  For data with a
larger range such as the raw fourier amplitude
(0-1000), a visually similar effect requires a
much smaller fslope (e.g., 0.01), since the
transition from noise to signal is spread out
over a larger range of values.

Relation Between (s)fmid and (s)fthresh

The (s)fthresh variables do a sharp cutoff using
the value entered.  This can generate visually
distracting sharp edges to activations.  The
(s)fmid variables set the 50% saturation point
using the value entered.  With a medium fslope
(e.g., 1.5 with F data in the range of 1-10),
colors will fade rapidly into the background
below the value entered, but without distracting
edges.  Set (s)fmid to the same as (s)fthresh to
truncate the 'fade'.

To see these effects in the color scale bar,
click on "RECT" at the upper right to get an x-y
scale bar (phase left-right, significance
up-down) and play around with the values of
fthresh and fmid.
