| % File src/library/stats/man/cmdscale.Rd |
| % Part of the R package, https://www.R-project.org |
| % Copyright 1995-2018 R Core Team |
| % Distributed under GPL 2 or later |
| |
| \name{cmdscale} |
| \alias{cmdscale} |
| \concept{ordination} |
| \concept{MDS} |
| \title{Classical (Metric) Multidimensional Scaling} |
| \usage{ |
| cmdscale(d, k = 2, eig = FALSE, add = FALSE, x.ret = FALSE, |
| list. = eig || add || x.ret) |
| } |
| \description{ |
| Classical multidimensional scaling (MDS) of a data matrix. |
| Also known as \emph{principal coordinates analysis} (Gower, 1966). |
| } |
| \arguments{ |
| \item{d}{a distance structure such as that returned by \code{dist} |
| or a full symmetric matrix containing the dissimilarities.} |
| \item{k}{the maximum dimension of the space which the data are to be |
| represented in; must be in \eqn{\{1, 2, \ldots, n-1\}}{{1, 2, \dots, n-1}}.} |
| \item{eig}{indicates whether eigenvalues should be returned.} |
| \item{add}{logical indicating if an additive constant \eqn{c*} should |
| be computed, and added to the non-diagonal dissimilarities such that |
| the modified dissimilarities are Euclidean.} |
| \item{x.ret}{indicates whether the doubly centred symmetric distance |
| matrix should be returned.} |
| \item{list.}{logical indicating if a \code{\link{list}} should be |
| returned or just the \eqn{n \times k}{n * k} matrix, see \sQuote{Value:}.} |
| } |
| \details{ |
| Multidimensional scaling takes a set of dissimilarities and returns a |
| set of points such that the distances between the points are |
| approximately equal to the dissimilarities. (It is a major part of |
| what ecologists call \sQuote{ordination}.) |
| |
| A set of Euclidean distances on \eqn{n} points can be represented |
| exactly in at most \eqn{n - 1} dimensions. \code{cmdscale} follows |
| the analysis of Mardia (1978), and returns the best-fitting |
| \eqn{k}-dimensional representation, where \eqn{k} may be less than the |
| argument \code{k}. |
| |
| The representation is only determined up to location (\code{cmdscale} |
| takes the column means of the configuration to be at the origin), |
| rotations and reflections. The configuration returned is given in |
| principal-component axes, so the reflection chosen may differ between |
| \R platforms (see \code{\link{prcomp}}). |
| |
| When \code{add = TRUE}, a minimal additive constant \eqn{c*} is |
| computed such that the dissimilarities \eqn{d_{ij} + c*}{d[i,j] + |
| c*} are Euclidean and hence can be represented in \code{n - 1} |
| dimensions. Whereas S (Becker \emph{et al}, 1988) computes this |
| constant using an approximation suggested by Torgerson, \R uses the |
| analytical solution of Cailliez (1983), see also Cox and Cox (2001). |
| Note that because of numerical errors the computed eigenvalues need |
| not all be non-negative, and even theoretically the representation |
| could be in fewer than \code{n - 1} dimensions. |
| } |
| \value{ |
| If \code{.list} is false (as per default), a matrix with \code{k} |
| columns whose rows give the coordinates of the points chosen to |
| represent the dissimilarities. |
| |
| Otherwise, a \code{\link{list}} containing the following components. |
| \item{points}{a matrix with up to \code{k} columns whose rows give the |
| coordinates of the points chosen to represent the dissimilarities.} |
| \item{eig}{the \eqn{n} eigenvalues computed during the scaling process if |
| \code{eig} is true. \strong{NB}: versions of \R before 2.12.1 |
| returned only \code{k} but were documented to return \eqn{n - 1}.} |
| \item{x}{the doubly centered distance matrix if \code{x.ret} is true.} |
| \item{ac}{the additive constant \eqn{c*}, \code{0} if \code{add = FALSE}.} |
| \item{GOF}{a numeric vector of length 2, equal to say |
| \eqn{(g_1,g_2)}{(g.1,g.2)}, where |
| \eqn{g_i = (\sum_{j=1}^k \lambda_j)/ (\sum_{j=1}^n T_i(\lambda_j))}{g.i = (sum{j=1..k} \lambda[j]) / (sum{j=1..n} T.i(\lambda[j]))}, |
| where \eqn{\lambda_j}{\lambda[j]} are the eigenvalues (sorted in |
| decreasing order), |
| \eqn{T_1(v) = \left| v \right|}{T.1(v) = abs(v)}, and |
| \eqn{T_2(v) = max( v, 0 )}{T.2(v) = max(v, 0)}. |
| } |
| } |
| \references{ |
| Becker, R. A., Chambers, J. M. and Wilks, A. R. (1988). |
| \emph{The New S Language}. |
| Wadsworth & Brooks/Cole. |
| |
| Cailliez, F. (1983). |
| The analytical solution of the additive constant problem. |
| \emph{Psychometrika}, \bold{48}, 343--349. |
| \doi{10.1007/BF02294026}. |
| |
| Cox, T. F. and Cox, M. A. A. (2001). |
| \emph{Multidimensional Scaling}. Second edition. |
| Chapman and Hall. |
| |
| Gower, J. C. (1966). |
| Some distance properties of latent root and vector |
| methods used in multivariate analysis. |
| \emph{Biometrika}, \bold{53}, 325--328. |
| \doi{10.2307/2333639}. |
| |
| Krzanowski, W. J. and Marriott, F. H. C. (1994). |
| \emph{Multivariate Analysis. Part I. Distributions, Ordination and |
| Inference.} |
| London: Edward Arnold. |
| (Especially pp.\sspace{}108--111.) |
| |
| Mardia, K.V. (1978). |
| Some properties of classical multidimensional scaling. |
| \emph{Communications on Statistics -- Theory and Methods}, \bold{A7}, |
| 1233--41. |
| \doi{10.1080/03610927808827707} |
| |
| Mardia, K. V., Kent, J. T. and Bibby, J. M. (1979). |
| Chapter 14 of \emph{Multivariate Analysis}, London: Academic Press. |
| |
| Seber, G. A. F. (1984). |
| \emph{Multivariate Observations}. |
| New York: Wiley. |
| |
| Torgerson, W. S. (1958). |
| \emph{Theory and Methods of Scaling}. |
| New York: Wiley. |
| } |
| \seealso{ |
| \code{\link{dist}}. |
| |
| \code{\link[MASS]{isoMDS}} and \code{\link[MASS]{sammon}} |
| in package \CRANpkg{MASS} provide alternative methods of |
| multidimensional scaling. |
| } |
| \examples{ |
| require(graphics) |
| |
| loc <- cmdscale(eurodist) |
| x <- loc[, 1] |
| y <- -loc[, 2] # reflect so North is at the top |
| ## note asp = 1, to ensure Euclidean distances are represented correctly |
| plot(x, y, type = "n", xlab = "", ylab = "", asp = 1, axes = FALSE, |
| main = "cmdscale(eurodist)") |
| text(x, y, rownames(loc), cex = 0.6) |
| } |
| \keyword{multivariate} |