'Clustering is an unsupervised machine learning method for grouping similar documents.
- k-means clustering returns a list of k clusters (each is a list of documents).
- hierarchical clustering returns a list of documents and Cluster objects,
where a Cluster is a list of documents and other clusters (see Cluster.flatten()).'

def cluster(self, method=KMEANS, **kwargs):

    documents = kwargs.get('documents', self.documents)
    if (not getattr(self, 'lsa', None)):
        (vectors, features) = ([d.vector for d in documents], self.vector.keys())
    else:
        (vectors, features) = ([self.lsa[d.id] for d in documents], range(len(self.lsa)))
    map = dict(((v.id, documents[i]) for (i, v) in enumerate(vectors)))
    if (method in (KMEANS, 'kmeans')):
        clusters = k_means(vectors, k=kwargs.pop('k', 10), iterations=kwargs.pop('iterations', 10), features=features, **kwargs)
    if (method == HIERARCHICAL):
        clusters = hierarchical(vectors, k=kwargs.pop('k', 1), iterations=kwargs.pop('iterations', 1000), features=features, **kwargs)
    if (method in (KMEANS, 'kmeans')):
        clusters = [[map[v.id] for v in cluster] for cluster in clusters]
    if (method == HIERARCHICAL):
        clusters.traverse(visit=(lambda cluster: [cluster.__setitem__(i, map[v.id]) for (i, v) in enumerate(cluster) if (not isinstance(v, Cluster))]))
    return clusters
