Clustering
Five shopper types, found without labels.
5
Best k
0.554
Silhouette
200
Customers
2–8
k tested
Overview
A mall wants to market differently to different shoppers, but nobody has labelled them. Unsupervised learning finds the groups from the data alone.
K-Means runs for every k from 2 to 8, and the silhouette score, not a guess, picks how many segments there are. Each segment then gets a plain-language name a marketing team can use.
How it works
From raw file to prediction.
Every number below comes from the training run.
- 01
Raw data
200 members
5 columns: age, gender, income, score
- 02
Features
2
Annual income and spending score
- 03
Cluster
k = 2 … 8
K-Means, 20 restarts for each k
- 04
Score
silhouette
How well separated each run is
- 05
Pick
k = 5
Best silhouette: 0.554
- 06
Name
5 segments
Named from income and spending vs the median
Inside the model
Groups nobody labelled.
K-means finds groups on its own: no right answers to learn from. Scroll to replay it on the 200 real mall customers.
The data
200 mall members, no labels.
Nobody told the model which shopper is which. It has to find the groups itself.
Mall Customers
A small teaching dataset of mall members: age, gender, yearly income and a spending score the mall assigns from purchase behaviour. Widely mirrored; this project uses a public GitHub copy.
200
members
5
columns
112 / 88
women / men
2
features used
Column dictionary
● used by the model
| Column | Type | What it means |
|---|---|---|
| CustomerID | id | Member number |
| Genre | category | Gender of the member |
| Age | number | Age in years |
| Annual Income (k$) | number | Yearly income in thousands of dollars |
| Spending Score (1-100) | number | Score the mall gives from purchase behaviour |
Explore the data
Before clustering, look at the shape.
Members per $10k band.
Members per 10-point band.
Try it
Pick a member, see their segment.
Click a row to drop that member on the map, or click the chart to add your own.
Real rows from the dataset
click a row to try it in the demo ↓
| Member | Gender | Age | Income k$ | Score | Segment (k=5) |
|---|---|---|---|---|---|
| 96 | Male | 24 | 60 | 52 | Mid income, average spenders |
| 16 | Male | 22 | 20 | 79 | Low income, big spenders |
| 31 | Male | 60 | 30 | 4 | Low income, careful spenders |
| 159 | Male | 34 | 78 | 1 | High income, careful spenders |
| 129 | Male | 59 | 71 | 11 | High income, careful spenders |
| 116 | Female | 19 | 65 | 50 | Mid income, average spenders |
| 70 | Female | 32 | 48 | 47 | Mid income, average spenders |
| 171 | Male | 40 | 87 | 13 | High income, careful spenders |
| 175 | Female | 52 | 88 | 13 | High income, careful spenders |
| 46 | Female | 24 | 39 | 65 | Low income, big spenders |
Live demo
runs in your browser
Spending score vs annual income
click to add a customer
Silhouette per k · best is k = 5
Segments
- Mid income, average spenders81
- High income, big spenders39
- Low income, big spenders22
- High income, careful spenders35
- Low income, careful spenders23
Click anywhere on the chart to drop a new customer.
How well it works
Why k = 5?
Two views of the same runs: tighter clusters (inertia) and better-separated clusters (silhouette).
Lower is tighter. The curve bends, but the elbow alone is a judgement call.
Higher is better separated. Peaks at k = 5 (0.554), so that's the pick.
The biggest group is "Mid income, average spenders" with 81 members.
| Segment | Members | Avg income (k$) | Avg score | Avg age | Women |
|---|---|---|---|---|---|
| Mid income, average spenders | 81 | 55.3 | 49.5 | 42.7 | 59% |
| High income, big spenders | 39 | 86.5 | 82.1 | 32.7 | 54% |
| Low income, big spenders | 22 | 25.7 | 79.4 | 25.3 | 59% |
| High income, careful spenders | 35 | 88.2 | 17.1 | 41.1 | 46% |
| Low income, careful spenders | 23 | 26.3 | 20.9 | 45.2 | 61% |
Build notes
How it's built, step by step.
The real code behind this page, taken from the repository when the site is built and split at each step of the training run. Copy any step, or the whole script with its imports and helpers.
Run it yourself
mall() from ml/train.py + 2 helpers (r, save)
pip install numpy pandas scikit-learn · data in ml/data/raw/
Training · Python
- 1
Load the customer list
Reads the mall CSV, renames the long column names, and keeps just two features to cluster on: annual income and spending score.
ml/train.py:319 · 4 lines
print("mall-segments") df = pd.read_csv(RAW / "mall" / "mall.csv") df = df.rename(columns={"Annual Income (k$)": "income", "Spending Score (1-100)": "score", "Genre": "gender"}) X = df[["income", "score"]].to_numpy(dtype=float) - 2
Try k from 2 to 8
K-Means (20 random starts each) runs for every k, recording inertia for the elbow chart and the silhouette score; the k with the best silhouette wins.
ml/train.py:325 · 11 lines
ks, runs = list(range(2, 9)), {} for k in ks: km = KMeans(n_clusters=k, n_init=20, random_state=SEED).fit(X) runs[k] = { "inertia": r(km.inertia_, 1), "silhouette": r(silhouette_score(X, km.labels_)), "labels": km.labels_.tolist(), "centroids": [[r(a, 2), r(b, 2)] for a, b in km.cluster_centers_], } print(f" k={k} silhouette={runs[k]['silhouette']:.3f}") best = max(ks, key=lambda k: runs[k]["silhouette"]) - 3
Name the segments
Each centroid is named by comparing its income and score with the medians (e.g. High income, big spenders), plus its size, average age and female share.
ml/train.py:338 · 22 lines
inc_med, sc_med = float(np.median(X[:, 0])), float(np.median(X[:, 1])) def name_segment(c): inc = "High income" if c[0] > inc_med * 1.15 else "Low income" if c[0] < inc_med * 0.85 else "Mid income" sp = "big spenders" if c[1] > sc_med * 1.2 else "careful spenders" if c[1] < sc_med * 0.8 else "average spenders" return f"{inc}, {sp}" best_run = runs[best] labels = np.array(best_run["labels"]) segments = [] for i, c in enumerate(best_run["centroids"]): m = labels == i segments.append( { "id": i, "name": name_segment(c), - 4
Pick demo customers
Ten random customers become the demo presets, each with the segment the best-k model assigned them.
ml/train.py:362 · 5 lines
samp = df.sample(10, random_state=SEED) samples = [ {"id": str(row.CustomerID), "gender": row.gender, "age": int(row.Age), "income": int(row.income), "score": int(row.score), "segment": int(labels[i])} for i, row in samp.iterrows() ] - 5
Export everything the page needs
The elbow table, labels and centroids for every k so the page can switch k, the named segments and histograms, written to src/data/models/mall-segments.json.
ml/train.py:369 · 17 lines
save( "mall-segments", { "dataset": {"name": "Mall Customers", "rows": int(len(df)), "raw_cols": int(df.shape[1]), "features_used": ["Annual Income (k$)", "Spending Score (1-100)"]}, "best_k": best, "elbow": [{"k": k, "inertia": runs[k]["inertia"], "silhouette": runs[k]["silhouette"]} for k in ks], "points": [[int(a), int(b)] for a, b in X], "runs": {str(k): {"labels": runs[k]["labels"], "centroids": runs[k]["centroids"]} for k in ks}, "segments": segments, "samples": samples, "eda": { "income_hist": {"bins": list(range(10, 150, 10)), "counts": np.histogram(df["income"], bins=range(10, 150, 10))[0].tolist()}, "score_hist": {"bins": list(range(0, 110, 10)), "counts": np.histogram(df["score"], bins=range(0, 110, 10))[0].tolist()}, "gender": {"Female": int((df.gender == "Female").sum()), "Male": int((df.gender == "Male").sum())}, }, }, )
Notes
The decisions behind it.
Approach
- 1
Ran K-Means for every k from 2 to 8 (20 restarts each).
- 2
Picked k with the best silhouette score instead of eyeballing the elbow.
- 3
Named each segment from where its centre sits against the median income and spending.
Silhouette score by k
Honest note
Two features make the clusters easy to see and explain. A production version would add age, visit frequency and basket data.
Reproduce: ml/train.py → mall()
Next project
NYC Taxi Anomalies