kmeans — Partition observations into k clusters with k-means clustering.

kmeans(X,k) clusters the rows of a numeric observation matrix into k clusters. It supports MATLAB-style multi-output use: [idx,C,sumd,D] = kmeans(...).

Syntax

idx = kmeans(X, k)
idx = kmeans(X, k, Name, Value)
[idx, C] = kmeans(___)
[idx, C, sumd] = kmeans(___)
[idx, C, sumd, D] = kmeans(___)

Inputs

Returns

Returned values from kmeans depend on how many outputs the caller requests.

Errors

How kmeans works

• X must be a real numeric vector or 2-D matrix. Matrix rows are observations; row and column vectors are treated as one-dimensional observations.
• Rows containing NaN are omitted from fitting and receive NaN in the returned idx and D outputs. Inf values are rejected.
• The default distance is "sqeuclidean". Supported distances are "sqeuclidean", "cityblock", "cosine", "correlation", and "hamming".
• Start supports "plus", "sample", "uniform", "cluster", a numeric k-by-p start matrix, or a numeric k-by-p-by-r array of replicate starts.
• When Start is numeric, k can be []; RunMat infers the cluster count from the first dimension of the start matrix or array.
• Replicates runs multiple starts and returns the result with the smallest finite within-cluster objective. Numeric 3-D starts set the replicate count from their third dimension.
• MaxIter limits Lloyd iterations. EmptyAction supports "singleton", "error", and "drop".
• Display is accepted for script compatibility. OnlinePhase="on" runs an additional bounded batch-refinement phase in the CPU runtime.
• Options accepts statset-style structs. MaxIter and Display fields are honored; parallel stream fields are rejected when enabled because RunMat's CPU implementation is single-process.
• For "cityblock" and "hamming", RunMat updates centroids with component-wise medians. Other distances use mean centroids in the metric's transformed space.
• Outputs are idx, centroid matrix C, per-cluster distance sums sumd, and the observation-by-cluster distance matrix D.

Examples

Cluster a two-group data set

X = [0 0; 0.2 0.1; 9.8 9.9; 10 10.1];
[idx,C,sumd,D] = kmeans(X, 2, 'Start', [0 0; 10 10])

Expected output:

`idx` assigns the first two rows to one cluster and the last two rows to the other; `C` contains two centroids.

Use cityblock distance

idx = kmeans(X, 2, 'Distance', 'cityblock', 'Replicates', 3)

Expected output:

RunMat runs three starts and returns the best cityblock clustering.

Infer k from numeric starts

[idx,C] = kmeans(X, [], 'Start', [0 0; 10 10])

Expected output:

RunMat infers two clusters from the two rows of the start matrix.

Treat missing rows consistently

idx = kmeans([1; 2; NaN; 20], 2)

Expected output:

The third `idx` element is `NaN`; the complete rows are clustered normally.

Using kmeans with coding agents

Open a RunMat example with live inputs, then ask the agent to explain how kmeans changes the result.

FAQ

Related Stats functions

Open-source implementation

Unlike proprietary runtimes, every RunMat function is open-source. Read exactly how kmeans is executed, line by line, in Rust.

• View the source for kmeans in Rust on GitHub
• Learn how the RunMat runtime works
• Found a bug? Open an issue with a minimal reproduction.

About RunMat

RunMat is an open-source runtime that executes MATLAB-syntax code blazing on any GPU. It is licensed under the Apache 2.0 license.

• RunMat automatically optimizes your math for GPU execution on Apple, Nvidia, and AMD hardware. No code changes needed. Simulations that took hours now take minutes.
• Start running code in seconds. RunMat runs in the browser, on the desktop, or from the CLI. No license server, no IT ticket.

Getting started · Benchmarks · Pricing