-------------------------------------------
SessionsTools -> Calc Visual Field Sign, Borders
-------------------------------------------
This panel uses eccen/polar pairs of Fourier
analyzed surface data sets to calculate the
visual field sign (mirror vs.  non-mirror image
representation), and/or retinotopic borders as
defined by region-growing to find where RF
positions repeat.

Input Files

The same set of eight Fourier-analyzed input
files are used for both of these operations.
These will have already have been painted onto
the left and right hemisphere surfaces from the
Fourier, Combine 3D Phase, or Combine Surface
Stats panels:

Right hemisphere
 $FUNCTIONALS_DIR/sess1/image/eccdir/ecc_r-rh.w
 $FUNCTIONALS_DIR/sess1/image/eccdir/ecc_i-rh.w
 $FUNCTIONALS_DIR/sess1/image/poldir/pol_r-rh.w
 $FUNCTIONALS_DIR/sess1/image/poldir/pol_i-rh.w

Left hemisphere
 $FUNCTIONALS_DIR/sess1/image/eccdir/ecc_r-lh.w
 $FUNCTIONALS_DIR/sess1/image/eccdir/ecc_i-lh.w
 $FUNCTIONALS_DIR/sess1/image/poldir/pol_r-lh.w
 $FUNCTIONALS_DIR/sess1/image/poldir/pol_i-lh.w

Eccentricity Scan and Polar Angle Scan comboboxes

Select an eccentricity functional scandir in the
"Scan Directory" combo box.  A *.w file must
appear in the "Vertex List Prefix" combo box
immediately to the right.  Do the same for a
polar angle functional scan.  Make sure it is
the correct one.

In both cases, the complex infixes, (_r, _i or
_x, _y) as well as the hemisphere infix (-lh or
-rh) will have been stripped from complex-valued
pairs.

=========================
Borders by Visual Field Sign
=========================

The first two parameters below the file selection
dropdowns control the field sign calculation.

This panel calculates the visual field sign using
two Fourier-analyzed data sets--one for in which
eccentricity was mapping and the other in which
polar angle was mapped.

The gradients in retinal eccentricity and polar
angle with respect to cortical x and y are
computed.  These two gradients are vector
quantities whose norms have units deg/mm (the
reciprocal of magnification factor).  They are
computed by fitting a plane to the r (or theta)
values of the current vertex and its immediate
neighbors using least squares.

In the original presentation (Sereno et al.,
1994), the clockwise angle between them (the
fieldsign angle) was measured to determine
whether the local representation of the visual
field at that vertex was non-mirror-image (angle
near Pi/2) or mirror-image (angle near -Pi/2).

Here, a cross product between the gradients is
calculated.  In the original version of tksurfer
compute_fieldsign, the signed magnitude of the
cross product was clamped to {-1,0,1} before
saving.  The current version saves the unclamped
value.  Its distribution peaks at 0 and falls off
approximately exponentially.  Truncating the
signed magnitude data to between -0.05 and 0.05
captures 99% of it (stdev of truncated data =
0.0070).  Note that this measure is sensitive to
both mapping signal gradient magnitude as well as
the fieldsign angle.

Finally, the intensity of the field sign coloring
is adjusted using the average significance from
the eccentricity and polar angle data sets.

By setting nonbinaryfsflag=1, an additional
modulation of the yellow/blue fieldsign color
toward gray is added to fieldsign values near
zero (ambiguous), in addition to the main
modulation by fsmask.  The width of the near-zero
valley is controlled by fsslope ("sl" entry to
left of main fieldsign file entry) -- higher
fsslope's give a narrower valley (back to binary
around fsslope=10000).

Smoothing Steps

Since the fieldsign calculation involves
gradients (derivatives), standard 3mm^3 data
needs to be heavily smoothed to reduce noise
(default: 50 steps).  Reduce this for higher
resolution data.

Flat Surface for Fieldsign Calc

The gradients are calculated on a flattened
surface.  In general, the smaller the surface
patch, the less distorted it will be.

Action Button--FIELDSIGN

This generates four files in the current
fieldsign scandir, two for each hemisphere.  The
fieldsign itself is stored in {rh,lh}.fs while
the fieldsign significance mask is in {rh,lh}.fm.

 $FUNCTIONALS_DIR/sess1/image/fs/rh.fs
 $FUNCTIONALS_DIR/sess1/image/fs/rh.fm

 $FUNCTIONALS_DIR/sess1/image/fs/lh.fs
 $FUNCTIONALS_DIR/sess1/image/fs/lh.fm

=================================
Borders by Retinotopic Region Growing
=================================

The next 6 parameters control the border
definition by region growing calculation.

The algorithm works by placing a seed at a
vertex, adding vertices in order of distance from
the seed to see if they have RF's different from
any in the current list, and then marking a
vertex if an RF is close to any RF in the current
list.  This operation is performed across
vertices in label, resulting in a "detected
border count" at each vertex.

Surf Smoothsteps Before Calc

The eccentricity and polar angle data is first
smoothed.  Less smoothing is required than for
the field sign calculation (default: 30 steps)

Label for Retin Seeds

Because the searchlight procedure is
computationally intensive, a label defining
(restricting) the search region is required for
each hemisphere in the standard directory:

  $SUBJECTS_DIR/$subject/label

The label name format should be the UCSD/UCL
label format, with a dash, not a period, after
the $hemi.  Here are the default label names:

  rh-retinseeds.label
  lh-retinseeds.label

Since this algorithm will generate noise when run
on retinotopic noise, you can create a suitable
signal containing label by using the tksurfer ROI
button.

Search Distance Each Seed Vtx (mm)

The search (searchight) is truncated at this
distance/radius (default: 5 mm) from each seed.
Increasing this parameter increases search time
quadratically.

RF Dist Below This Marks Repeat

This defines the criterion for when a border has
been detected because an RF position has
overlapped one already in the list.  The units
are distances between receptive field centers on
a circle of radius 2Pi radians.

Frac Label Vtxs to Seed (0-1)

This is a second method for reducing computation
time.  This parameter controls the randomly
selected fraction of the total number of vertices
in the search label to seed for searches.  The
default is all of the vertices (1.0).  The
computation time is about a minute per 15K
vertices (full hemisphere: ~150K vertices).

Output files

Two real-valued output wfiles are written, one in
the eccentricity directory used for the
calculation and the other in the polar angle
directory used.  The name format in both cases
is:

  <eccenstem>+<polarstem>_k-$hemi.w

The file in the eccentricity directory is simply
the count of border detections at each vertex.
For an exhaustive search of seeds in a 15K vertex
label, this count will be in the range of 2000
for a retinotopic border.

The file in the polar angle directory has the
same count multipled by fraction of the number of
seeds divided by the total number of vertices
tested.  This number will be near 1.0 for
detected borders.

These files are best displayed with the BRy color
scale, using fmid to adjust the exact position of
the yellow borders.

The tksurfer C/tcl border-finding function,
find_retin_borders, is set up and called from
csurf using the standard tcl library script,
borders.tcl, which is similar to the fieldsign
library script, fs-make.tcl
