

   SSaammmmoonn''ss NNoonn--LLiinneeaarr MMaappppiinngg

        sammon(d, y=cmdscale(d), k=2, niter=100, trace=T,
        magic=0.2, tol=1e-4)

   AArrgguummeennttss::

          d: distance structure of the form returned by `dist',
             or a full, symmetric matrix.  Data are assumed to
             be dissimilarities or relative distances, but must
             be positive except for self-distance.

          y: An initial configuration. If none is supplied,
             `cmdscale' is used to provide the classical solu-
             tion.

          k: The dimension of the configuration.

      niter: The maximum number of iterations.

      trace: Logical for tracing optimization. Default `True'.

      magic: initial value of the step size constant in diago-
             nal Newton method.

        tol: Tolerance for stopping, in units of stress.

   DDeessccrriippttiioonn::

        One form of non-metric multidimensional scaling.

   DDeettaaiillss::

        This chooses a two-dimensional configuration to mini-
        mize the stress, the sum of squared differences between
        the input distances and those of the configuration,
        weighted by the distances, the whole sum being divided
        by the sum of input distances to make the stress scale-
        free.

        An iterative algorithm is used, which will usually con-
        verge in around 50 iterations. As this is necessarily
        an O(n^2) calculation, it is slow for large datasets.
        Further, since the configuration is only determined up
        to rotations and reflections (by convention the cen-
        troid is at the origin), the result can vary consider-
        ably from machine to machine.  In this release the
        algorithm has been modified by adding a step-length
        search (`magic') to ensure that it always goes down-
        hill.

   VVaalluuee::

        Two components:

     points: A two-column vector of the fitted configuration.

     stress: The final stress achieved.

   SSiiddee EEffffeeccttss::

        If trace is true, the initial stress and the current
        stress are printed out every 10 iterations.

   RReeffeerreenncceess::

        Sammon, J. W. (1969) A non-linear mapping for data
        structure analysis.  IEEE Trans. Comput.  C-18 401-409.

   SSeeee AAllssoo::

        `cmdscale', `isoMDS'

   EExxaammpplleess::

        data(swiss)
        swiss.x <- as.matrix(swiss[, -1])
        swiss.sam <- sammon(dist(swiss.x))
        plot(swiss.sam$points, type="n")
        text(swiss.sam$points, labels=as.character(1:nrow(swiss.x)))

