←BaldanAll skillsLet's talk
Machine Learning lab

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.

  1. 01

    Raw data

    200 members

    5 columns: age, gender, income, score

  2. 02

    Features

    2

    Annual income and spending score

  3. 03

    Cluster

    k = 2 … 8

    K-Means, 20 restarts for each k

  4. 04

    Score

    silhouette

    How well separated each run is

  5. 05

    Pick

    k = 5

    Best silhouette: 0.554

  6. 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.

ANNUAL INCOME (K$)SPENDING SCORE (1–100)SILHOUETTE SCORE FOR EACH NUMBER OF GROUPS (HIGHER = CLEANER GROUPS)0.30k = 20.47k = 30.49k = 40.55k = 50.54k = 60.53k = 70.46k = 8

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

Copy used (GitHub mirror)

Column dictionary

● used by the model

ColumnTypeWhat it means
CustomerIDidMember number
GenrecategoryGender of the member
AgenumberAge in years
Annual Income (k$)numberYearly income in thousands of dollars
Spending Score (1-100)numberScore the mall gives from purchase behaviour

Explore the data

Before clustering, look at the shape.

Annual income

Members per $10k band.

0255010k40k70k100k130k
Spending score

Members per 10-point band.

02550020406080

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 ↓

MemberGenderAgeIncome k$ScoreSegment (k=5)
96Male246052Mid income, average spenders
16Male222079Low income, big spenders
31Male60304Low income, careful spenders
159Male34781High income, careful spenders
129Male597111High income, careful spenders
116Female196550Mid income, average spenders
70Female324847Mid income, average spenders
171Male408713High income, careful spenders
175Female528813High income, careful spenders
46Female243965Low income, big spenders

Live demo

runs in your browser

Spending score vs annual income

click to add a customer

025507510020406080100120140Annual income (k$)Spending score

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).

Elbow: inertia by k

Lower is tighter. The curve bends, but the elbow alone is a judgement call.

0k100k200k2345678k (number of segments)chosen
Silhouette by k

Higher is better separated. Peaks at k = 5 (0.554), so that's the pick.

0.000.350.702345678k (number of segments)chosen
Segment profiles

The biggest group is "Mid income, average spenders" with 81 members.

SegmentMembersAvg income (k$)Avg scoreAvg ageWomen
Mid income, average spenders8155.349.542.759%
High income, big spenders3986.582.132.754%
Low income, big spenders2225.779.425.359%
High income, careful spenders3588.217.141.146%
Low income, careful spenders2326.320.945.261%
05010081Mid income · …High income ·…22Low income · …High income ·…Low income · …

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. 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. 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. 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. 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. 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. 1

    Ran K-Means for every k from 2 to 8 (20 restarts each).

  2. 2

    Picked k with the best silhouette score instead of eyeballing the elbow.

  3. 3

    Named each segment from where its centre sits against the median income and spending.

Silhouette score by k

k = 20.297
k = 30.468
k = 40.493
k = 50.554chosen
k = 60.540
k = 70.529
k = 80.459

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