Course topics

By WebNest Studio Engineering Team

Python Tutorial

Unsupervised Learning: Clustering with k-Means

Sometimes there is no label to predict — you want to discover structure. Clustering groups similar examples together: customer segments for marketing, similar documents, store locations with similar demand, unusual behaviour that fits no group.

k-means is the most widely used clustering algorithm. You choose the number of clusters k; it places k centres, assigns every point to its nearest centre, moves each centre to the mean of its points, and repeats until nothing changes. This lesson covers k-means, choosing k with the elbow method and silhouette score, and a customer segmentation example.

Why it matters

Often there are no labels at all: nobody has marked which customers are similar. Clustering finds the groups in the data itself, and customer segmentation with k-means is one of the most widely used analyses in marketing. It is also the standard introduction to unsupervised learning.

Using k-means Well

k-means uses distances, so scale the features first — otherwise income in rupees drowns out age in years. Set random_state for reproducible results (n_init reruns with different starting centres and keeps the best). k-means finds round, similar-sized clusters; for irregular shapes or noise, DBSCAN or hierarchical clustering (AgglomerativeClustering) may fit better.

Choosing k

The elbow method plots inertia_ (total squared distance of points to their centres) for several k; it always decreases, but the "elbow" where improvement slows suggests a good k. The silhouette score (−1 to 1) measures how well each point fits its own cluster compared with the nearest other cluster; higher is better. Finally, clusters must make sense to people — describe each one with groupby means and give it a name.

Examples

k-means on simple 2-D data, with the elbow and silhouette scores

Python
from sklearn.cluster import KMeans
from sklearn.datasets import make_blobs
from sklearn.metrics import silhouette_score

X, true_groups = make_blobs(n_samples=300, centers=4, cluster_std=0.8, random_state=7)

print(" k   inertia  silhouette")
for k in range(2, 7):
    km = KMeans(n_clusters=k, n_init=10, random_state=0).fit(X)
    print(f"{k:>2}  {km.inertia_:>8.1f}  {silhouette_score(X, km.labels_):.3f}")

best = KMeans(n_clusters=4, n_init=10, random_state=0).fit(X)
print("cluster sizes:", sorted([int((best.labels_ == c).sum()) for c in range(4)]))
print("centres:", best.cluster_centers_.round(1).tolist())
print("new points go to clusters:", best.predict([[0, 0], [-8, 8]]))
Output
 k   inertia  silhouette
 2    8867.6  0.605
 3    2313.8  0.786
 4     365.6  0.846
 5     327.1  0.735
 6     293.0  0.595
cluster sizes: [75, 75, 75, 75]
centres: [[9.5, 0.6], [-1.3, 4.5], [0.1, -8.7], [-8.4, 5.5]]
new points go to clusters: [1 3]

Customer segmentation with scaled features

Python
import numpy as np
import pandas as pd
from sklearn.cluster import KMeans
from sklearn.pipeline import make_pipeline
from sklearn.preprocessing import StandardScaler

rng = np.random.default_rng(11)
def group(n, orders, spend, days):
    return pd.DataFrame({"orders_per_year": rng.normal(orders, 2, n).clip(1).round(),
                         "avg_order_value": rng.normal(spend, 150, n).clip(100).round(),
                         "days_since_last_order": rng.normal(days, 10, n).clip(1).round()})
customers = pd.concat([group(120, 4, 600, 120),    # occasional shoppers
                       group(80, 24, 900, 10),     # loyal regulars
                       group(40, 6, 3500, 30)],    # big spenders
                      ignore_index=True)

model = make_pipeline(StandardScaler(), KMeans(n_clusters=3, n_init=10, random_state=0))
customers["segment"] = model.fit_predict(customers)

profile = customers.groupby("segment").agg(
    customers=("orders_per_year", "size"),
    orders=("orders_per_year", "mean"),
    order_value=("avg_order_value", "mean"),
    recency_days=("days_since_last_order", "mean"),
).round(0).sort_values("order_value")
print(profile)

names = dict(zip(profile.index, ["Occasional", "Loyal regulars", "Big spenders"]))
print(customers["segment"].map(names).value_counts().to_dict())
Output
         customers  orders  order_value  recency_days
segment
1              120     4.0        596.0         121.0
0               80    24.0        900.0          10.0
2               40     6.0       3475.0          33.0
{'Occasional': 120, 'Loyal regulars': 80, 'Big spenders': 40}

Common Mistakes

  • Clustering unscaled features, so one large-valued column dominates.
  • Picking k without checking the elbow, silhouette or whether the clusters make business sense.
  • Treating cluster numbers as meaningful labels — they are arbitrary and can change between runs.
  • Using k-means for elongated or irregular clusters where DBSCAN fits better.
  • Forgetting that k-means is sensitive to outliers.

Exercise

Run k-means with 2 clusters on the six points. Cluster numbers are arbitrary, so check the grouping without relying on them: print whether the first three points share a label, whether the last three share a label, and whether the two groups have different labels. Then print the cluster centres, rounded to 2 decimals and sorted.

Expected output: True True True then [[1.33, 1.33], [10.33, 10.33]]

Python · starter code
from sklearn.cluster import KMeans

points = [[1, 1], [1, 2], [2, 1], [10, 10], [10, 11], [11, 10]]

# TODO: fit KMeans with n_clusters=2, n_init=10 and random_state=0
# TODO: print the three checks on the labels, on one line
# TODO: print the centres, rounded to 2 decimals, as a sorted list
Show hints
  • After fitting, the labels are in model.labels_ and the centres in model.cluster_centers_.
  • len(set(labels[:3])) == 1 is true when the first three labels are all the same.
Show solution
Python · solution
from sklearn.cluster import KMeans

points = [[1, 1], [1, 2], [2, 1], [10, 10], [10, 11], [11, 10]]

model = KMeans(n_clusters=2, n_init=10, random_state=0)
model.fit(points)

labels = model.labels_.tolist()
print(len(set(labels[:3])) == 1, len(set(labels[3:])) == 1, labels[0] != labels[3])

print(sorted(model.cluster_centers_.round(2).tolist()))

Quick quiz

1. Does k-means need labelled data?

  • A. No; it is an unsupervised algorithm
  • B. Yes
  • C. Only for the first cluster
  • D. Only for the test set
Show answer

A. It groups points by distance, with no target column.

2. What must be chosen before k-means is run?

  • A. The labels
  • B. The number of clusters, k
  • C. The test size
  • D. The learning rate
Show answer

B. The elbow method and the silhouette score help to choose it.

3. Why should features be scaled before k-means?

  • A. To speed up printing
  • B. It requires integers
  • C. It uses distances, so a feature with large values would dominate the result
  • D. To remove duplicates
Show answer

C. Income in thousands would otherwise outweigh age in years.

Interview questions

How does the k-means algorithm work?

Show answer

It starts with k initial centres. It then repeats two steps: assign every point to its nearest centre, and move each centre to the mean of the points assigned to it. This continues until the assignments stop changing. The result depends on the starting centres, so the algorithm is run several times with different starts and the best result, the one with the smallest total distance from points to their centres, is kept.

How do you choose the number of clusters?

Show answer

With the elbow method, k-means is run for a range of k and the within-cluster sum of squares is plotted; the point where the curve stops falling steeply suggests a value. The silhouette score measures how well each point fits its own cluster compared with the nearest other one, and the k with the highest average is preferred. The choice should also make sense for how the clusters will be used.

Key Points to Remember

  • Clustering finds groups in unlabelled data; k-means is the standard starting point.
  • Scale features and set random_state/n_init.
  • Choose k with the elbow (inertia) and silhouette score, then sanity-check the groups.
  • Profile clusters with groupby to turn them into named, actionable segments.
  • DBSCAN and hierarchical clustering handle other cluster shapes.

Practice in the playground

Write and run your own code for this topic, or start from the exercise or an example. Runs Python in your browser. Your code for each topic is kept in this browser.

Run the examples

Change an input, predict the result, then compare it with the output. Explain why the result changes.

These examples need a project environment on your computer, so they can be copied but not run here. Codelab runs Python, FastAPI backends with SQLite, plain Java 17 and HTML/CSS/JavaScript.

WebNest Studio

Written by

WebNest Studio Engineering Team

Practical lessons from developers working with Java, Python, React, databases and production systems.

Led by Vansh Duggal, Founder, WebNest Studio · Full-stack & software engineering