\HeaderA{fanny}{Fuzzy Analysis Clustering}{fanny}
\keyword{cluster}{fanny}
\begin{Description}\relax
Computes a fuzzy clustering of the data into \code{k} clusters.
\end{Description}
\begin{Usage}
\begin{verbatim}
fanny(x, k, diss = inherits(x, "dist"), memb.exp = 2,
      metric = c("euclidean", "manhattan", "SqEuclidean"),
      stand = FALSE, iniMem.p = NULL, cluster.only = FALSE,
      keep.diss = !diss && !cluster.only && n < 100,
      keep.data = !diss && !cluster.only,
      maxit = 500, tol = 1e-15, trace.lev = 0)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{x}] data matrix or data frame, or dissimilarity matrix, 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 (NAs) are allowed.

In case of a dissimilarity matrix, \code{x} is typically the output
of \code{\LinkA{daisy}{daisy}} or \code{\LinkA{dist}{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 not allowed.

\item[\code{k}] integer giving the desired number of clusters.  It is
required that \eqn{0 < k < n/2}{} where \eqn{n}{} is the number of
observations.
\item[\code{diss}] logical flag: if TRUE (default for \code{dist} or
\code{dissimilarity} objects), then \code{x} is assumed to be a
dissimilarity matrix.  If FALSE, then \code{x} is treated as
a matrix of observations by variables.

\item[\code{memb.exp}] number \eqn{r}{} strictly larger than 1 specifying the
\emph{membership exponent} used in the fit criterion; see the
\sQuote{Details} below. Default: \code{2} which used to be hardwired
inside FANNY.
\item[\code{metric}] character string specifying the metric to be used for
calculating dissimilarities between observations.  Options are
\code{"euclidean"} (default), \code{"manhattan"}, and
\code{"SqEuclidean"}.  Euclidean distances are root sum-of-squares
of differences, and manhattan distances are the sum of absolute
differences, and \code{"SqEuclidean"}, the \emph{squared} euclidean
distances are sum-of-squares of differences.  Using this last option is
equivalent (but somewhat slower) to computing so called \dQuote{fuzzy C-means}.
\\
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{iniMem.p}] numeric \eqn{n \times k}{n * k} matrix or \code{NULL}
(by default); can be used to specify a starting \code{membership}
matrix, i.e., a matrix of non-negative numbers, each row summing to
one.

\item[\code{cluster.only}] logical; if true, no silhouette information will be
computed and returned, see details.
\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 smaller results and hence also save
memory allocation \emph{time}.
\item[\code{maxit, tol}] maximal number of iterations and default tolerance
for convergence (relative convergence of the fit criterion) for the
FANNY algorithm.  The defaults \code{maxit = 500} and \code{tol =
      1e-15} used to be hardwired inside the algorithm.
\item[\code{trace.lev}] integer specifying a trace level for printing
diagnostics during the C-internal algorithm.
Default \code{0} does not print anything; higher values print
increasingly more.
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
In a fuzzy clustering, each observation is \dQuote{spread out} over
the various clusters.  Denote by \eqn{u_{iv}}{u(i,v)} the membership
of observation \eqn{i}{} to cluster \eqn{v}{}.

The memberships are nonnegative, and for a fixed observation i they sum to 1.
The particular method \code{fanny} stems from chapter 4 of
Kaufman and Rousseeuw (1990) (see the references in
\code{\LinkA{daisy}{daisy}}) and has been extended by Martin Maechler to allow
user specified \code{memb.exp}, \code{iniMem.p}, \code{maxit},
\code{tol}, etc.

Fanny aims to minimize the objective function
\deqn{\sum_{v=1}^k
\frac{\sum_{i=1}^n\sum_{j=1}^n u_{iv}^r u_{jv}^r d(i,j)}{
2 \sum_{j=1}^n u_{jv}^r}}{SUM_[v=1..k] (SUM_(i,j) u(i,v)^r u(j,v)^r d(i,j)) / (2 SUM_j u(j,v)^r)}
where \eqn{n}{} is the number of observations, \eqn{k}{} is the number of
clusters, \eqn{r}{} is the membership exponent \code{memb.exp} and
\eqn{d(i,j)}{} is the dissimilarity between observations \eqn{i}{} and \eqn{j}{}.
\\ Note that \eqn{r \to 1}{r -> 1} gives increasingly crisper
clusterings whereas \eqn{r \to \infty}{r -> Inf} leads to complete
fuzzyness.  K\&R(1990), p.191 note that values too close to 1 can lead
to slow convergence.  Further note that even the default, \eqn{r = 2}{}
can lead to complete fuzzyness, i.e., memberships \eqn{u_{iv} \equiv
1/k}{u(i,v) == 1/k}.  In that case a warning is signalled and the
user is advised to chose a smaller \code{memb.exp} (\eqn{=r}{}).

Compared to other fuzzy clustering methods, \code{fanny} has the following
features: (a) it also accepts a dissimilarity matrix; (b) it is
more robust to the \code{spherical cluster} assumption; (c) it provides
a novel graphical display, the silhouette plot (see
\code{\LinkA{plot.partition}{plot.partition}}).
\end{Details}
\begin{Value}
an object of class \code{"fanny"} representing the clustering.
See \code{\LinkA{fanny.object}{fanny.object}} for details.
\end{Value}
\begin{SeeAlso}\relax
\code{\LinkA{agnes}{agnes}} for background and references;
\code{\LinkA{fanny.object}{fanny.object}}, \code{\LinkA{partition.object}{partition.object}},
\code{\LinkA{plot.partition}{plot.partition}}, \code{\LinkA{daisy}{daisy}}, \code{\LinkA{dist}{dist}}.
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
## generate 10+15 objects in two clusters, plus 3 objects lying
## between those clusters.
x <- rbind(cbind(rnorm(10, 0, 0.5), rnorm(10, 0, 0.5)),
           cbind(rnorm(15, 5, 0.5), rnorm(15, 5, 0.5)),
           cbind(rnorm( 3,3.2,0.5), rnorm( 3,3.2,0.5)))
fannyx <- fanny(x, 2)
## Note that observations 26:28 are "fuzzy" (closer to # 2):
fannyx
summary(fannyx)
plot(fannyx)

(fan.x.15 <- fanny(x, 2, memb.exp = 1.5)) # 'crispier' for obs. 26:28
(fanny(x, 2, memb.exp = 3))               # more fuzzy in general

data(ruspini)
f4 <- fanny(ruspini, 4)
stopifnot(rle(f4$clustering)$lengths == c(20,23,17,15))
plot(f4, which = 1)
## Plot similar to Figure 6 in Stryuf et al (1996)
plot(fanny(ruspini, 5))
\end{ExampleCode}
\end{Examples}

