% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/plot_dist.R
\name{plot_dist}
\alias{plot_dist}
\title{Plot a distance matrix as a 2D projection}
\usage{
plot_dist(
  d,
  method = c("cmds", "isomds", "tsne"),
  highlight = NULL,
  gp = NULL,
  point.alpha = 0.8
)
}
\arguments{
\item{d}{A distance matrix of class \code{\link[stats]{dist}}. Labels must be
set (i.e. \code{labels(d)} must not be \code{NULL}). Duplicate labels are
not permitted.}

\item{method}{Character string specifying the dimensionality-reduction
method. One of:
\describe{
  \item{\code{"cmds"}}{Classical (metric) Multidimensional Scaling via
    \code{\link[stats]{cmdscale}}. This is the default.}
  \item{\code{"isomds"}}{Non-metric (isotonic) MDS via
    \code{\link[MASS]{isoMDS}}. Automatically falls back to
    \code{"cmds"} with a message when \code{n < 3}.}
  \item{\code{"tsne"}}{t-distributed Stochastic Neighbour Embedding via
    \code{\link[Rtsne]{Rtsne}}. Perplexity is set automatically to
    \code{min(30, floor((n - 1) / 3))}.}
}}

\item{highlight}{Optional character vector of labels to highlight in the
plot. Matching identifiers are plotted in \strong{red}; all others in
black. \code{NULL} (default) disables highlighting. Every value must be
present in \code{labels(d)}.}

\item{gp}{Optional named character vector mapping labels to group names
(\code{names(gp)} = labels, values = group names). When supplied, the plot
is split into one facet panel per group via
\code{\link[ggplot2]{facet_wrap}}. The set of names must match
\code{labels(d)} exactly. \code{NULL} (default) produces a single panel.}

\item{point.alpha}{Alpha transparency value for points.}
}
\value{
A \code{\link[ggplot2]{ggplot}} object. The plot can be further
  customised with standard \pkg{ggplot2} additions before printing or saving.
}
\description{
Reduces a distance matrix to two dimensions using Classical MDS, Isotonic
MDS, or t-SNE, and returns a \code{ggplot2} scatter plot in which proximity
reflects similarity. Points can optionally be highlighted or split into facet
panels by group.
}
\examples{
# Basic usage with the built-in eurodist dataset
plot_dist(eurodist)

# Non-metric MDS with two highlighted cities
plot_dist(eurodist, method = "isomds",
          highlight = c("Madrid", "Rome"))

# Classical MDS split by a user-defined grouping
regions <-
  c(Athens = "South",  Barcelona = "South", Brussels = "North",
    Calais = "North",  Cherbourg = "North", Cologne = "North",
    Copenhagen = "North", Geneva = "South", Gibraltar = "South",
    Hamburg = "North", `Hook of Holland` = "North", Lisbon = "South",
    Lyons = "South",  Madrid = "South",  Marseilles = "South",
    Milan = "South",  Munich = "North",  Paris = "North",
    Rome = "South",   Stockholm = "North", Vienna = "North")

plot_dist(eurodist, method = "cmds", gp = regions,
          highlight = c("Madrid", "Cherbourg", "Rome", "Brussels"))

}
\seealso{
\code{\link[stats]{cmdscale}}, \code{\link[MASS]{isoMDS}},
\code{\link[Rtsne]{Rtsne}}, \code{\link[ggplot2]{ggplot}}
}
