def kmeans(obs, k_or_guess, iter=<NUM_LIT:20>, thresh=<NUM_LIT>):
if int(iter) < <NUM_LIT:1>:<EOL><INDENT>raise ValueError('<STR_LIT>')<EOL><DEDENT>if type(k_or_guess) == type(array([])):<EOL><INDENT>guess = k_or_guess<EOL>if guess.size < <NUM_LIT:1>:<EOL><INDENT>raise ValueError("<STR_LIT>" %<EOL>guess)<EOL><DEDENT>result = _kmeans(obs, guess, thresh=thresh)<EOL><DEDENT>else:<EOL><INDENT>best_dist = np.inf<EOL>No = obs.shape[<NUM_LIT:0>]<EOL>k = k_or_guess<EOL>if k < <NUM_LIT:1>:<EOL><INDENT>raise ValueError("<STR_LIT>")<EOL><DEDENT>for i in range(iter):<EOL><INDENT>guess = take(obs, randint(<NUM_LIT:0>, No, k), <NUM_LIT:0>)<EOL>book, dist = _kmeans(obs, guess, thresh=thresh)<EOL>if dist < best_dist:<EOL><INDENT>best_book = book<EOL>best_dist = dist<EOL><DEDENT><DEDENT>result = best_book, best_dist<EOL><DEDENT>return result<EOL>
Performs k-means on a set of observation vectors forming k clusters.

The k-means algorithm adjusts the centroids until sufficient
progress cannot be made, i.e. the change in distortion since
the last iteration is less than some threshold. This yields
a code book mapping centroids to codes and vice versa.

Distortion is defined as the sum of the squared differences
between the observations and the corresponding centroid.

Parameters
----------
obs : ndarray
   Each row of the M by N array is an observation vector. The
   columns are the features seen during each observation.
   The features must be whitened first with the `whiten` function.

k_or_guess : int or ndarray
   The number of centroids to generate. A code is assigned to
   each centroid, which is also the row index of the centroid
   in the code_book matrix generated.

   The initial k centroids are chosen by randomly selecting
   observations from the observation matrix. Alternatively,
   passing a k by N array specifies the initial k centroids.

iter : int, optional
   The number of times to run k-means, returning the codebook
   with the lowest distortion. This argument is ignored if
   initial centroids are specified with an array for the
   ``k_or_guess`` parameter. This parameter does not represent the
   number of iterations of the k-means algorithm.

thresh : float, optional
   Terminates the k-means algorithm if the change in
   distortion since the last k-means iteration is less than
   or equal to thresh.

Returns
-------
codebook : ndarray
   A k by N array of k centroids. The i'th centroid
   codebook[i] is represented with the code i. The centroids
   and codes generated represent the lowest distortion seen,
   not necessarily the globally minimal distortion.

distortion : float
   The distortion between the observations passed and the
   centroids generated.

See Also
--------
kmeans2 : a different implementation of k-means clustering
   with more methods for generating initial centroids but without
   using a distortion change threshold as a stopping criterion.

whiten : must be called prior to passing an observation matrix
   to kmeans.

Examples
--------
>>> from numpy import array
>>> from scipy.cluster.vq import vq, kmeans, whiten
>>> features  = array([[ 1.9,2.3],
...                    [ 1.5,2.5],
...                    [ 0.8,0.6],
...                    [ 0.4,1.8],
...                    [ 0.1,0.1],
...                    [ 0.2,1.8],
...                    [ 2.0,0.5],
...                    [ 0.3,1.5],
...                    [ 1.0,1.0]])
>>> whitened = whiten(features)
>>> book = array((whitened[0],whitened[2]))
>>> kmeans(whitened,book)
(array([[ 2.3110306 ,  2.86287398],
       [ 0.93218041,  1.24398691]]), 0.85684700941625547)

>>> from numpy import random
>>> random.seed((1000,2000))
>>> codes = 3
>>> kmeans(whitened,codes)
(array([[ 2.3110306 ,  2.86287398],
       [ 1.32544402,  0.65607529],
       [ 0.40782893,  2.02786907]]), 0.5196582527686241)