#### read label data, read vtxcols, read+cut ####
-------------------------------------------
funct: "Read Label -> Val (left-click-R)"
  set label <infile>
  read_label_to_val <cutlabelflag=0>
-------------------------------------------
funct: "Read VtxCol Paint (middle-click-R)"
  set vclabel <infile>
  read_vtxcol_label
-------------------------------------------
funct: "Read/Recut Label->Val (shift-mid-clk-R)"
  set label <infile>
  read_label_to_val <cutlabelflag=1>
-------------------------------------------
funct: "Read Uniqsamp Vtxs (ctrl-left-click-R)"
  setfile label */$scandir/$hemi-UniqSampVtxs.label
  read_uniqsamp_vertices
-------------------------------------------


Detailed Description of Label "R" Button Actions

-------------------------------------------
funct: "Read Label -> Val (left-click-R)"
  set label <infile>
  read_label_to_val <cutlabelflag=0>
-------------------------------------------

Read data (real or complex) for labeled vertices
from ASCII label file whose name is current value
of $label (entry at left) into the .val field
(and also .val2 field if complex).

If "cpx" is unticked ($complexvalflag equals 0),
then this expects a real-valued file with 5
numbers on each line after the 2-line header
(vtxnum x y z val).

If "cpx" is ticked ($complexvalflag equals 1),
then this expects a complex-valued file with 6
numbers on each line after the 2-line header
(vtxnum x y z r i).

See the R-click help for the label entry for more
details on file formats.

Vertices not in label file are not modified
(e.g., when masking or merging activations).  To
first clear the data from all vertices (.val and
.val2 fields) use CLR button two rows below to
right of "val:".

The data in the label file is rendered using the
current settings (colscale, fmid, etc.), which
can be adjusted to taste after reading the label.

The label is not re-cut (see shift-middle-click
below to read a label *and* recut it).

If the label filename has a pattern such as:

 ~/prf/rh_pRF_sf_pol_r.label
 ~/prf/rh_pRF_sf_pol_r.label

(or with 'rh' prefix, or 'ecc' infix) indicating
it is a complex-valued pair, reading either
member will auto-read the other, and also reset
the color scale parameters to appropriate values.

You can also directly call the (verbosely-named)
tcl wrapper function that correctly handles the
different cases:

  read_realcomplex_or_samcomplex_label_to_val

This requires a single valid label file in entry.

-------------------------------------------
funct: "Read VtxCol Paint (middle-click-R)"
  set vclabel <infile>
  read_vtxcol_label
-------------------------------------------

If the "R" button is middle-clicked (instead of
default left-clicked), an alternate read label
function is called: read_vtxcol_label.  This
function reads a previously-written "vertex-color
label".  This will have been previously created
from a label using middle-click-W (see
right-click help for the "W" button).

The filename of the vertex-color label ($vclabel)
is parallel to the label from which it was
created.  You can enter the name of the *.cols
file directly *or* the name of the corresponding
regular label file:

  ~/label/rh-V1.cols => label in entry
  ~/label/rh-V1.cols => vertex-color label that is read

or

  ~/label/rh-V1.label => label in entry
  ~/label/rh-V1.cols => vertex-color label that is read

A vertex-color label (suffix: .cols) contains the
actual colors of each rendered vertex in a label
given all the tksurfer panel settings at the time
the vertex-color label was created (e.g.,
colscale, fmid, anglecycles, etc).  Note that
these colors are *before* lighting calculations
have been applied, so the same *.cols file can be
correctly displayed on differently shaped
surfaces.

This differs from a regular label, which contains
a set of statistical values that don't themselves
change as the color scale display settings are
changed.

This function can be used to assemble the results
of multiple experiments on one brain surface in
cases where the separate experiments require
different color scales (since the current color
scale is otherwise applied to every vertex).  A
vertex-color label will opaquely occlude
activations already displayed on the surface in
the location of the label; and subsequently read
vertex-color labels occlude previously read
vertex-color labels.

A middle-click on the unlabeled checkbutton as
the far left of the "label;" lines toggles the
visibility of any vertex-color labels.

See R-click help for the "label:"  "W" button for
format of ASCII vertex-color label file.

-------------------------------------------
funct: "Read/Recut Label->Val (shift-mid-clk-R)"
  set label <infile>
  read_label_to_val <cutlabelflag=1>
-------------------------------------------

[was "RC", read-then-cut, button]

Exactly the same as default left click -- read
real or complex data from ASCII label file whose
name is current value of $label (entry at left)
into the .val field (and .val2 field if complex)
-- except that label is also re-cut.

This can be used to edit/trim an existing label,
or to incorporate different overlay data before
re-saving the label (usu. with a different
name!).

Note that the re-cutting operation will restore
to visibility any vertices in the label that are
currently invisible.  For find label overlap, use
the "C" button instead (recuts a label without
restoring invisible vertices or reading values).

-------------------------------------------
funct: "Read Uniqsamp Vtxs (ctrl-left-click-R)"
  setfile label */$scandir/$hemi-UniqSampVtxs.label
  read_uniqsamp_vertices
-------------------------------------------

Read label to mark uniqsamp vertices (output of
PAINT if Setup Functional "UniqVtx" ticked).
Currently, only accepts label with this name:

  ?h-UniqSampVtxs.label

(the "setfile" above is a csurf-specific globbing
"set").  This reads previously computed single
vertices that were closest to the average location
of each set of vertices that sampled one voxel
during the paint operation.  The value at each
vertex in the file is the number of vertices
intersected by this unique vertex, which is saved
in the .uniqvoxcnt field.  The .uniqvoxnum field
is set to a sequential numbering of the unique
vertices.  These fields affect the operation of:

  "T" button (write_label_timecourses_stats)
  "X" button (corr_over_label) searchlight-based xcorr
  tcl funct: find_FDR_from_pvals

