Just publishedA GitHub Actions CI/CD Security Baseline: Pinned Actions, Scoped Secrets, Verified Artifacts, and Useful Logs
UgraByte
Unsupervised learning

K-Means Clustering Visualizer — Watch Unsupervised Learning in Action

Place unlabelled points, pick k, and step through the algorithm as it finds the clusters for itself.

Loading the interactive version…

What this actually is

Unsupervised learning is what happens when the data has no labels. Nobody has marked which points belong together, so there is no right answer to reproduce and no accuracy to measure. The algorithm has only the data's own shape to work with.

K-means is the most widely used version of that idea. You tell it how many groups to look for — the k — and it alternates two steps until nothing changes: assign every point to its nearest centre, then move every centre to the average of the points that chose it. Each step can only reduce the spread within clusters, which is why it always settles. But you have to supply k, and the algorithm cannot tell you when you picked wrong.

What you’re watching

The dots are unlabelled data — nothing tells the algorithm which belong together. The crosses are centroids, dropped onto randomly chosen data points, because k-means has to start somewhere and has no information to start cleverly.

Each press of Step performs one half of one iteration, and the button says which half is next. On an assign step, every point picks its nearest centroid and takes that colour. On an update step, every centroid jumps to the mean of its points, leaving a ring and a dashed line behind.

Those trails are the clearest signal of convergence: long arrows early, then shorter, then none, which is when the algorithm stops. Inertia is the quantity being minimised — total squared distance from each point to its centroid — and it falls on every step and never rises. Re-initialise without changing the data and you sometimes get a different answer, because k-means only guarantees a local optimum.

How to drive it

  1. Randomise the points or tap the canvas to place your own, then choose how many clusters to look for with the k control.

  2. Press Step repeatedly to alternate between assigning points and moving centroids, and watch the inertia figure fall.

  3. Or press Run to let it play out automatically until it converges.

  4. Re-initialise the centroids on the same points to see whether it reaches the same answer, and try a k larger than the number of groups you can actually see to watch two centroids split one group.

How this relates to real systems

Production clustering runs on far more than two dimensions — customer segmentation on forty behavioural features, document embeddings on several hundred. The algorithm is identical, but nobody can look at the result, so this plot is replaced by summary statistics and arguing about whether the clusters mean anything.

The problems you can create here are the ones real teams hit. Choosing k is answered in practice by the elbow method: run a range of values and find where inertia stops improving. Initialisation sensitivity is why production code defaults to k-means++ and runs several attempts. And because the algorithm minimises distance to a centre, it only finds roughly round groups — crescents defeat it, which is when teams reach for DBSCAN.

Frequently asked questions

How do I choose the right number of clusters?
There is no way to read it off the data, which is the honest answer. The standard approach is the elbow method: run k-means for a range of k values, plot the inertia each one settles at, and look for the bend where adding another cluster stops buying much improvement. Inertia always falls as k rises — at k equal to the number of points it reaches zero — so the goal is the point of diminishing returns rather than the minimum.
Why does it give a different answer when I re-initialise?
Because k-means finds a local optimum, not the global one. Both alternating steps reduce inertia, so the process always settles, but where it settles depends on where the centroids started. Production implementations deal with this by running the algorithm ten or more times from different starts and keeping the lowest-inertia result, and by using k-means++ initialisation, which spreads the initial centroids out deliberately instead of placing them at random.
What is inertia and why does it only go down?
Inertia is the sum of squared distances from every point to the centroid it is assigned to — the quantity k-means exists to minimise. It never rises because each half-step can only reduce it: reassigning a point to a nearer centroid reduces that point's contribution by definition, and moving a centroid to the mean of its cluster is precisely the position that minimises the sum of squared distances to those points. When neither step can reduce it any further, the algorithm has converged.
Why did one of my centroids end up with no points?
Because every point was closer to some other centroid. It is uncommon in this demo, since the centroids start on randomly chosen data points and so each one begins owning at least the point it landed on; it shows up mainly when you ask for more clusters than you have points, or when a centroid loses all of its points to its neighbours after a few updates. This demo leaves the stranded centroid where it is, marked with a dashed ring, because that is what the plain algorithm does. Production implementations usually detect the empty cluster and re-seed that centroid onto the point furthest from any existing centre.
When is k-means the wrong tool?
When your clusters are not roughly round and roughly the same size. Because it minimises squared distance to a single centre point, k-means implicitly assumes each cluster is a compact blob, and it will cut straight through crescents, rings and long thin bands. It also has no concept of an outlier — every point is assigned to something, and a distant point drags its centroid toward it. Density-based methods like DBSCAN handle both cases and, as a bonus, work out the number of clusters themselves.