-------------------------------------------
Standard tcl script: searchlightarea.tcl
-------------------------------------------

This script estimates local area differences by
resampling individual subject vertexwise area
data to fsaverage, and then running a
surface-based searchlight operation on the
resampled data using fsaverage sphere.

First, create a Cross-Subject Session (for
display subject, fsaverage) with:

  csurf -> File -> New SphereAvg 
  (pseudo-subject "XS" for "cross-session") 

Then, select subject "fsaverage" and the "sphere"
surface, the just-created empty session, and
click SURFACE.  After tksurfer starts, select
searchlightarea.tcl from the "tcl:" dropdown in
at the top left of the tksurfer interface.  This
generates a pop-up to select a subject and adjust
parameters.

Clicking "RUN SCRIPT" on the pop-up resamples the
area data, and then runs the searchlight
operation:

  4 -> sum of data in searchlight

The result is written out as a vertexwise
curvature-format file.  The multi-threaded
operation takes about 10 min/hemisphere on an
Intel i7.

The size, ${num,sqmm,mm}, of the approximately
geodesic surface searchlight circles can be
specified by vertex count (num), area (mm^2),
radius (mm), or by neighbor order (1=immediate
neighbors, 2=also include neighbors of neighbors,
etc):

  Searchlight size ($fillneartype):

    0 -> num vertices
    1 -> area (in mm^2)
    2 -> radius (in mm)
    3 -> neighbor order (1-6)

The first three searchlight size specifications
($fillneartype) use the C/tcl function,
searchlightop_val2stat (multi-threaded), while
the fourth specification uses the C/tcl function,
neighop_val2stat (similar result for similar
vertex count, goes up to 6th-order neighbors,
which is 127 vertices on fsaverage).

Adjustable parameters can be hard-coded in this
script (see commented-out example inside) in
order to run it non-interactively from the
command line as a tksurfer tcl script, for
example:

#! /bin/sh
sublist="marty sean jill sue"
hemlist="rh lh"
cd $SUBJECTS_DIR/fsaverage/scripts
cp $CSURF_DIR/lib/tcl/searchlightarea.tcl .
for sub in $sublist; do
  for hem in $hemlist; do
    export sampsubj=$sub    # tcl script reads env
    tksurfer fsaverage $hem sphere -tcl searchlightarea.tcl
  done
done

To kill a running script, kill tksurfer either
using its window kill buttons, or the purple
"QuitSURFA" button on csurf (the purple "RUNNING"
button on script window cannot kill the script).

