
----------------------------------------------------------------

OPTIMIZATION OF THE CONFIGURATION:

Since you were able to start up xgvis with a valid dataset, begin by
clicking "Run MDS" and see what happens: You should see the points in
the XGobi window move and a curve evolve in a subwindow titled "Stress
function" in the XGvis panel.  The motion is generated by a gradient
descent algorithm; the curve shows the criterion, called Stress.

Click again and the motion stops.  Click one more time and leave "Run
MDS" on in what follows.  This allows you to immediately see the
effects of various manipulations.

By default, XGvis performs gradient descent of a stress function for
metric Kruskal-Shepard distance scaling.  See its help window for the
formula.

----------------------------------------------------------------

CONTROLS IN THE RIGHT HAND COLUMN OF THE XGVIS PANEL:

k = Dimension of the points, default: 3.
    For 3-D viewing, choose in the XGobi window "View:..." -> "Rotation"
    Click on "<=" to lower the dimension to 2.
    For 2-D viewing, choose in the XGobi window "View:..." -> "XYPlot"
    The dimension k can be as high as 12.  
    For viewing 4 and higher-D, choose in XGobi "View:..." -> "Grand Tour"

Stepsize: The stress optimization uses a fixed-size gradient step.
    This slider permits controlling the step size in terms of a
    fraction of the size of the point configuration.  Default: 0.02
    (gradient sz = 2% config sz).

p = Exponent of the power transformation of D in metric MDS.
    Playing with the slider allows you to interactively optimize stress.
    Also, see what happens as p -> 0 (scaling of a simplex).

m = Minkowski norm: Used to calculate the current interpoint distances.
    Default: m=2, the Euclidean metric on k-space.

r = Weight parameter: The dissimilarities D can be weighted with w=D^r
    in the stress function.  Default: r=0, equal weights.

wb = Within/between parameter: If there are color/glyph groups, the
    parameter allows one to differentially weight dissimilarities that
    link points within groups versus between groups.  
    Extremes: wb=(2,0): Use only within groups, remove between groups;
              wb=(0,2): Remove within groups, use only between groups.
    Default:  wb=(1,1): Weight within and between groups equally.    

    Color/glyph groups can be provided in input files (xyz.glyphs,
    xyz.colors), or created interactively with "View:..." -> "Brush".

MDS with Groups: 

  - Click "Groups", a window for group selection will pop up.  Click
    in the "Hide" column to remove and restore groups.  Watch the
    effects on the point configuration.

  - Click on the menu underneath "MDS with Groups".  

  . Select "Dists within groups": same as wb=(2,0) above, but
    implemented more efficiently without weights.
    Similar for "Dists between groups" (~ wb=(0,2)).
    Default: "Ignore groups" (~ wb=(1,1)).

  . Select "Dists from&in anchor": anchored MDS maps points within an
    anchor set by MDS (as usual), but it maps the points outside the
    anchor set with the dissimilarities w.r.t. the anchor set (hence
    the term).

    The anchor set consists of the points with the glyph that appears
    to the right of "MDS with Groups".  You can change the anchor set
    by selecting "View:..." -> "Move Points" in the XGobi window.
    Click MIDDLE on a point, and the points with that color glyph
    become the new anchor set.

  . Select "Dists from anchor": same, except the anchor points remain
    fixed.  This allows you to mess with the anchor points manually by
    dragging them around with the LEFT mouse button depressed.

Selection probability: random subselection of dissimilarities; a form
   of stability check.  Implementation: a uniform [0,1] random number
   is generated for each dissimilarity, which is included in the
   stress function if the random number is below the selection
   probability read from the slider.  The "New" button allows you to
   create a new set of random numbers.  Select for example a selection
   probability 0.9 and click "New" repeatedly.  This will show how
   stable the configuration is under removal of roughly 1 in 10
   dissimilarities.  Default: 1.0 (all dissimilarities included).

Perturbation: perturb the configuration with normal random vectors.
   The slider value s determines the relative fractions of
   configuration and perturbation: (1-s)*Config + s*Random.  
   Extremes: s=1.0: pure random, i.e., a random start (default).  
             s=0.0: pure configuration, i.e., no perturbation.
   Click "New" to initiate a perturbation.

----------------------------------------------------------------

PLOTS AT THE BOTTOM OF THE XGVIS PANEL:

Stress function plot: shows the evolution of the stress values as
   optimization progresses.  No interactive controls. 

Histogram of transformed dissimilarities (bottom of the XGvis panel):
   Note the grips on either end of the horizontal axis!  You can move
   them to trim large and small dissimilarities.  The right grip trims
   large ones; the left grip small ones.  This allows you to check
   their importance.

----------------------------------------------------------------

CONTROLS IN THE LEFT HAND COLUMN OF THE XGVIS PANEL:

"File": following conventions, this menu has I/O and Exit.
   You can save the dissimilarity matrix, which can be useful if it
   was generated from a discrete graph or a multivariate dataset.

"Run MDS": We used this at the beginning.

"Metric" versus "Nonmetric": choice of metric and nonmetric MDS

"Krsk/Sh" versus "Classic": choice of Kruskal-Shepard distance scaling
   versus Torgersen-Gower dot-product scaling (also called classical MDS).

IMPORTANT for those who know about MDS: XGvis has a version of
   nonmetric classical (!) scaling.  That is, the two pairs of choices
   above are in fact fully crossed.  Nonmetric classical scaling is
   not very stable, but it works with good starting configurations.

   [Technical remark: The idea is to perform dot-product scaling of
   -D^2under the constraint that the configuration remains centered.
   This is equivalent to doubly-centering -D^2 and performing
   unconstrained dot-product scaling.  The advantage of the former is
   that it can be made nonmetric by replacing -D^2 with an isotonic
   transform f(-D) which can be estimated by regressing the
   configuration distances on -D.]
   
"Step": an alternative to "Run MDS" if you wish to follow the gradient
   steps one by one.

"Re-init config": Re-initialize the configuration to the initial positions.

"Center config": Center and scale the configuration.  Can be useful if
  for some reason the configuration has collapsed or got lost from the
  window.

"Shepard Plot": starts up a separate XGobi window with the following
   variables:
   d_ij     = interpoint distances
   f(D_ij)  = transformed dissimilarities; 
              metric: power; nonmetric: isotonic.
   D_ij     = raw dissimilarities
   Res_ij   = residuals f(D_ij) - d_ij
   Wgt_ij   = weights, informative only if r or wb is non-default
   i        = the first index  \   useful for checking the patterns
   j        = the second index /   of missing or omitted dissimilarities
              
   The number of dissimilarities can be large!  The field below
   "Shepard Plot" tells you how many there are.  For N>500 you might
   want to be careful.  Use "Select'n prob" with "Run MDS" off to get
   a random sample of manageable size.

"Help...": several help pages, such as this one.

   For the technically interested user the pages with the stress and
   strain formulae will be informative.


----------------------------------------------------------------

