\HeaderA{coef.hclust}{Agglomerative Coefficient for 'hclust' Objects}{coef.hclust}
\aliasA{coef.twins}{coef.hclust}{coef.twins}
\keyword{cluster}{coef.hclust}
\begin{Description}\relax
Computes the \dQuote{agglomerative coefficient}, measuring the
clustering structure of the dataset.

For each observation i, denote by \eqn{m(i)}{} its dissimilarity to the
first cluster it is merged with, divided by the dissimilarity of the
merger in the final step of the algorithm.  The agglomerative
coefficient is the average of all \eqn{1 - m(i)}{}.  It can also be seen
as the average width (or the percentage filled) of the banner plot.

Because it grows with the number of observations, this measure should not
be used to compare datasets of very different sizes.
\end{Description}
\begin{Usage}
\begin{verbatim}
coef.hclust(object, ...)
## S3 method for class 'hclust':
coef(object, ...)
## S3 method for class 'twins':
coef(object, ...)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{object}] an object of class \code{"hclust"} or \code{"twins"},
i.e., typically the result of
\code{\LinkA{hclust}{hclust}(.)},\code{\LinkA{agnes}{agnes}(.)}, or \code{\LinkA{diana}{diana}(.)}.

Since \code{coef.hclust} only uses \code{object\$heights}, and
\code{object\$merge}, \code{object} can be any list-like object with
appropriate \code{merge} and \code{heights} components.

\item[\code{...}] currently unused potential further arguments
\end{ldescription}
\end{Arguments}
\begin{Value}
a number specifying the \emph{agglomerative} (or \emph{divisive} for
\code{diana} objects) coefficient as defined by Kaufman and Rousseeuw,
see \code{\LinkA{agnes.object}{agnes.object} \$ ac} or \code{\LinkA{diana.object}{diana.object} \$ dc}.
\end{Value}
\begin{Examples}
\begin{ExampleCode}
data(agriculture)
aa <- agnes(agriculture)
coef(aa) # really just extracts aa$ac
coef(as.hclust(aa))# recomputes

\end{ExampleCode}
\end{Examples}

