Finds centers of clusters and groups input samples around the clusters

labels = cv.kmeans(data, K)
[labels, centers, compactness] = cv.kmeans(...)
[...] = cv.kmeans(..., 'OptionName', optionValue, ...)

Input

• data Data for clustering. An array of D-dimensional points with floating-point coordinates is needed. Examples of this matrix can be: NxD numeric matrix (one row per sample), or Nx1xD/1xNxD array (with dimensions across slices).
• K Number of clusters to split the set by.

Output

• labels Integer array that stores the cluster indices for every sample.
• centers Output matrix of the cluster centers, one row per each cluster center.
• compactness Measure of compactness. See below.

Options

• Criteria The algorithm termination criteria, that is, the maximum number of iterations and/or the desired accuracy. The accuracy is specified as criteria.epsilon. As soon as each of the cluster centers moves by less than criteria.epsilon on some iteration, the algorithm stops. default struct('type','Count+EPS', 'maxCount',100, 'epsilon',eps('float'))
• Attempts The number of times the algorithm is executed using different initial labelings. The algorithm returns the labels that yield the best compactness (see the last function parameter). default 10.
• Initialization Method to initialize seeds. One of the followings:
  • Random Select random initial centers in each attempt. (default)
  • PP Use kmeans++ center initialization by Arthur and Vassilvitskii [Arthur2007].
• InitialLabels Integer array that stores the initial cluster indices for every sample. During the first (and possibly the only) attempt, kmeans uses the user-supplied labels instead of computing them from the initial centers. For the second and further attempts, it uses the random or semi-random centers. Use one of the Initialization methods to specify the exact method. Not set by default.

The function cv.kmeans implements a k-means algorithm that finds the centers of K clusters and groups the input samples around the clusters. As an output, labels(i) contains a 0-based cluster index for the sample stored in the i-th row of the samples matrix.

The function returns the compactness measure that is computed as:

sum_{i} (|| samples_i - centers_{labels_i} ||^2)

after every attempt. The best (minimum) value is chosen and the corresponding labels and the compactness value are returned by the function. Basically, you can use only the core of the function, set the number of attempts to 1, initialize labels each time using a custom algorithm, pass them with the InitialLabels option, and then choose the best (most-compact) clustering.

References

[Arthur2007]:

D. Arthur, S. Vassilvitskii: "k-means++: The Advantages of Careful Seeding". In Proceedings of the eighteenth annual ACM-SIAM symposium on Discrete algorithms, 1027-1035, 2007.