\name{Clusters}
\alias{Clusters}
\title{
The K-means cluster analysis.
}
\description{
This function computes cluster centers and their time series of occurrences, 
with the K-means clustering method using Euclidean distance, of a matrix of 
input data var(time, space). Specifically, it partitions var along time axis 
in K groups or clusters in which each space vector/array belongs to (i.e.,
is a member of) the cluster with the nearest center or centroid. This function 
requires NbClust package (Charrad et al., 2014 JSS). For more information about 
the K-means see Chapter 15 Cluster Analysis in Wilks, 2011, Statistical Methods 
in the Atmospheric Sciences, 3rd ed., Elsevire, pp 676. 
}
\usage{
Clusters(var, weights, nclusters = NULL, index = 'sdindex')
}
\arguments{
  \item{var}{
A 2D matrix (time, space); the 2nd, spatial, dimension can correspond either  
to area-averages over a series of domains or the grid points for any sptial 
grid structure (x), (y), (z), (x,y), (x,y,z), (y,z), .. organised/stretched 
into a vector/array for each time step.
  }
  \item{weights}{ 
A 1D vector/array of multiplicative weights of the areas covering each 
domain/region or grid-cell of var; the length of weights must be equal to 
the 2nd spatial dimension of var.
  }
  \item{nclusters}{
This is positive integer K that must be bigger than 1. K is the number of clusters 
to be computed, or K initial cluster centers to be used in the method. Default is NULL 
and then user has to specify which index from NbClust and the associated criteria for 
selecting the optimal number of clusters will be used for K-means clustering of var.
  }
  \item{index}{
A validity index from NbClust package that can be used to determine optimal K 
if K is not specified as positive integer bigger than 1 or initial/seed cluster 
centers in nclusters. 'sdindex' is deafult (Halkidi et al. 2001, JIIS). Other 
indices also available in NBClust are "kl", "ch", "hartigan", "ccc", "scott", "marriot", 
"trcovw", "tracew", "friedman", "rubin", "cindex", "db", "silhouette", "duda", "pseudot2", 
"beale", "ratkowsky", "ball", "ptbiserial", "gap", "frey", "mcclain", "gamma", "gplus", 
"tau", "dunn", "hubert", "sdindex", and "sdbw". One can also use all of them with
the option 'alllong' or almost all indices except gap, gamma, gplus and tau with 'all', 
when the optimal number of clusters K is detremined by the majority rule (the maximum of 
histogram of the results of all indices with finite solutions). Use of some indices on 
a big and/or unstructured dataset can be computationally intense and/or could lead to 
numerical singularity. 
  }
}
\value{
  \item{cluster}{ 
A vector (time series) of integers indicating the occurrence of a cluster, i.e., when
certain data member in time is allocated to a specific cluster (e.g., 2 1 3 1 1 1 ..).
  }
  \item{centers}{
A matrix of cluster centres or centroids (e.g. [1:K, 1:spatial degrees of freedom]).
  }
  \item{totss}{
The total sum of squares. 
  }
  \item{withinss}{
A vector of within-cluster sum of squares, one component per cluster. 
  }
  \item{tot.withinss}{
Total within-cluster sum of squares, i.e., sum(withinss). 
  }
  \item{betweenss}{
The between-cluster sum of squares, i.e. totss-tot.withinss. 
  }
  \item{size}{
The number of points in each cluster. 
  }
}
\examples{

a1 <- array(dim=c(30,3))
x1 <- c(1, 1, 1); for (i1 in c(1,2,4,7,12,20,28,29))                { a1[i1,] <- x1 + rnorm(3, mean=0, sd=0.5) }
x2 <- c(2, 2, 4); for (i2 in c(3,6,8,9,10,11,14,16,23,25,26,27,30)) { a1[i2,] <- x2 + rnorm(3, mean=0, sd=0.5) }
x3 <- c(3, 3, 1); for (i3 in c(5,13,15,17,18,19,21,22,24))          { a1[i3,] <- x3 + rnorm(3, mean=0, sd=0.5) }

res1 <- Clusters(var=a1, weights=c(1,1,1), ncluster=3)
print(res1$cluster)
print(res1$centers)

}
\author{
History:
1.0  #  2014-10  (N.S. Fuckar, neven.fuckar@bsc.es)  #  Original code
}
\keyword{datagen}
