\Header{diana}{DIvisive ANAlysis Clustering}
\keyword{cluster}{diana}
\begin{Description}\relax
Computes a divisive hierarchical clustering of the dataset
returning an object of class \code{diana}.\end{Description}
\begin{Usage}
\begin{verbatim}
diana(x, diss = inherits(x, "dist"), metric = "euclidean", stand = FALSE,
      keep.diss = n < 100, keep.data = !diss)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] data matrix or data frame, or dissimilarity matrix or object,
depending on the value of the \code{diss} argument.

In case of a matrix or data frame, each row corresponds to an observation,
and each column corresponds to a variable.  All variables must be numeric.
Missing values (\code{\Link{NA}}s) \emph{are} allowed.

In case of a dissimilarity matrix, \code{x} is typically the output
of \code{\Link{daisy}} or \code{\Link{dist}}.  Also a vector of
length n*(n-1)/2 is allowed (where n is the number of observations),
and will be interpreted in the same way as the output of the
above-mentioned functions. Missing values (NAs) are \emph{not} allowed.

\item[\code{diss}] logical flag: if TRUE (default for \code{dist} or
\code{dissimilarity} objects), then \code{x} will be considered as a
dissimilarity matrix.  If FALSE, then \code{x} will be considered as
a matrix of observations by variables.

\item[\code{metric}] character string specifying the metric to be used for calculating
dissimilarities between observations.\\
The currently available options are "euclidean" and
"manhattan".  Euclidean distances are root sum-of-squares of
differences, and manhattan distances are the sum of absolute
differences.  If \code{x} is already a dissimilarity matrix, then
this argument will be ignored.

\item[\code{stand}] logical; if true, the measurements in \code{x} are
standardized before calculating the dissimilarities.  Measurements
are standardized for each variable (column), by subtracting the
variable's mean value and dividing by the variable's mean absolute
deviation.  If \code{x} is already a dissimilarity matrix, then this
argument will be ignored.
\item[\code{keep.diss, keep.data}] logicals indicating if the dissimilarities
and/or input data \code{x} should be kept in the result.  Setting
these to \code{FALSE} can give much smaller results and hence even save
memory allocation \emph{time}.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
\code{diana} is fully described in chapter 6 of Kaufman and Rousseeuw (1990).
It is probably unique in computing a divisive hierarchy, whereas most
other software for hierarchical clustering is agglomerative.
Moreover, \code{diana} provides (a) the divisive coefficient
(see \code{diana.object}) which measures the amount of clustering structure
found; and (b) the banner, a novel graphical display
(see \code{plot.diana}).

The \code{diana}-algorithm constructs a hierarchy of clusterings,
starting with one large
cluster containing all n observations. Clusters are divided until each cluster
contains only a single observation.\\
At each stage, the cluster with the largest diameter is selected.
(The diameter of a cluster is the largest dissimilarity between any
two of its observations.)\\
To divide the selected cluster, the algorithm first looks for its most
disparate observation (i.e., which has the largest average dissimilarity to the
other observations of the selected cluster). This observation initiates the
"splinter group". In subsequent steps, the algorithm reassigns observations
that are closer to the "splinter group" than to the "old party". The result
is a division of the selected cluster into two new clusters.\end{Details}
\begin{Value}
an object of class \code{"diana"} representing the clustering.  See
\code{?\Link{diana.object}} for details.\end{Value}
\begin{SeeAlso}\relax
\code{\Link{agnes}} also for background and references;
\code{\Link{diana.object}}, \code{\Link{daisy}}, \code{\Link{dist}},
\code{\Link{plot.diana}}, \code{\Link{twins.object}}.\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
data(votes.repub)
dv <- diana(votes.repub, metric = "manhattan", stand = TRUE)
print(dv)
plot(dv)

data(agriculture)
## Plot similar to Figure 8 in ref
## Don't run: plot(diana(agriculture), ask = TRUE)

\end{ExampleCode}
\end{Examples}

