Baike.dev
All toolsOnline toolsAI codingTrendingOpen sourceNewsSubmit
Log in
< Back to tools
C

clustering-playbook

> 编程语言
Open source

Trilingual clustering tutorial with Mermaid diagrams, comparison tables, and Python 3.9+ runnable demos for K-Means++, Fuzzy C-Means, Hierarchical, DBSCAN, OPTI

394 stars0 likes0 views
WebsiteGitHub

About

Trilingual clustering tutorial with Mermaid diagrams, comparison tables, and Python 3.9+ runnable demos for K-Means++, Fuzzy C-Means, Hierarchical, DBSCAN, OPTI

Clustering Playbook: Trilingual Clustering Tutorial

…

Language: English | 简体中文 | 日本語

This repository is a refreshed clustering-algorithm learning project. It keeps the first four classic algorithms as readable hand-written Python demos, adds two widely used modern extensions, and turns the old blog-style notes into a GitHub-friendly, runnable reference.

What this repository offers

  • Python 3.9+ compatible scripts that run directly from the repository root.
  • Four hand-written teaching demos: K-Means++, Fuzzy C-Means, Agglomerative Hierarchical Clustering, and DBSCAN.
  • Two additional practical demos: OPTICS and Spectral Clustering.
  • Consistent CLI for every script: --seed, --samples, --output, and --show.
  • Shared plotting and dataset utilities in clustering_utils.py.
  • Smoke tests in tests/test_repository.py and CI in .github/workflows/ci.yml.

Clustering at a Glance

Clustering is the task of grouping unlabeled samples by similarity. The key difference between clustering algorithms is not just speed, but the very definition of what a "cluster" means: a tight group around a center, a connected dense region, a merge path in a hierarchy, or a partition in a similarity graph.

mermaid
flowchart TD
    A["Raw unlabeled samples"] --> B{"What makes points belong together?"}
    B --> C["Nearest prototype or center
K-Means++, Fuzzy C-Means"]
    B --> D["Repeatedly merge closest groups
Agglomerative Hierarchical"]
    B --> E["Dense reachable neighborhoods
DBSCAN, OPTICS"]
    B --> F["Graph neighborhood structure
Spectral Clustering"]

Quick Start

bash
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

Run any demo directly:

bash
python3 k_means_plus_plus.py
python3 fuzzy_c_means.py
python3 agglomerative_hierarchical.py
python3 dbscan.py
python3 optics.py
python3 spectral_clustering.py

Useful options shared by all scripts:

  • --seed: controls reproducibility.
  • --samples: controls the dataset size.
  • --output: saves the figure to a custom path.
  • --show: displays the figure after saving it.

Run the smoke tests:

bash
pytest

Repository Layout

File Purpose
clustering_utils.py Shared dataset generation, plotting helpers, validation helpers, and k-means++ initialization.
k_means_plus_plus.py Hand-written K-Means++ demo for convex blob-shaped clusters.
fuzzy_c_means.py Hand-written fuzzy c-means demo for soft memberships.
agglomerative_hierarchical.py Hand-written agglomerative hierarchical clustering demo.
dbscan.py Hand-written DBSCAN demo for noise-aware density clustering.
optics.py OPTICS demo with a reachability plot, using scikit-learn.
spectral_clustering.py Spectral clustering demo for non-convex shapes, using scikit-learn.
requirements.txt Minimal dependencies for scripts and tests.

Algorithm Comparison

Algorithm Family Need k in advance? Handles noise? Works well on non-convex shapes? Typical complexity Best fit
K-Means++ Prototype / partitioning Yes No Usually no Time O(nkt), space O(n + k) Fast baseline when clusters are compact and roughly spherical
Fuzzy C-Means Soft partitioning Yes No Usually no Time O(nkt), space O(nk) When soft memberships are more informative than hard assignments
Agglomerative Hierarchical Hierarchical No fixed k during merging, but you choose a cut level Limited Sometimes Demo time O(n^3), space O(n^2) Small datasets where merge history matters
DBSCAN Density-based No Yes Yes Demo time O(n^2), space O(n^2) Irregular clusters with outliers and unknown cluster count
OPTICS Density-based ordering No Yes Yes Often near O(n log n) with indexing, worst O(n^2) Datasets with different local densities
Spectral Clustering Graph / partitioning Yes No explicit noise model Yes Time often O(n^3), space O(n^2) Non-convex manifolds and graph-like similarity structure

Choosing an Algorithm Quickly

  • Start with K-Means++ when you know the cluster count and expect compact groups.
  • Choose Fuzzy C-Means when overlap matters and you want degrees of membership.
  • Choose Agglomerative Hierarchical Clustering when you care about multi-level structure or cluster merge history.
  • Choose DBSCAN when you need outlier resistance and arbitrary cluster shapes.
  • Choose OPTICS when DBSCAN feels too sensitive to a single global density threshold.
  • Choose Spectral Clustering when clusters are better described by neighborhood graphs than by geometric centers.

How to Read the Demos

  • The scripts in this repository are intentionally small, so each one highlights the core training loop or clustering expansion step instead of hiding everything behind a large framework.
  • The generated figures show the final assignments, while the code snippets below focus on the one operation that makes each algorithm different from the others.
  • When comparing algorithms, look at three things together: whether noise is isolated, whether curved shapes stay intact, and whether the method needs the cluster count in advance.

Decision Table

If your data looks like this Best first algorithm Why it is a good starting point
Compact blob-like groups and a known cluster count K-Means++ Fast, stable, and easy to explain
Samples overlap and hard labels hide useful uncertainty Fuzzy C-Means Keeps soft memberships instead of a single forced label
You want to inspect coarse-to-fine grouping structure Agglomerative Hierarchical The merge path itself is part of the result
Clusters are irregular and outliers matter DBSCAN Density expansion naturally separates noise
Density changes a lot across regions OPTICS More flexible than DBSCAN under one global threshold
Rings, moons, or graph-shaped neighborhoods dominate Spectral Clustering Uses graph structure instead of center geometry

Parameter Cheat Sheet

Algorithm Most important knobs If you increase it If you decrease it
K-Means++ --clusters, --tolerance More clusters can split groups; larger tolerance stops earlier Fewer clusters merge groups; smaller tolerance runs longer
Fuzzy C-Means --clusters, --fuzziness Larger fuzziness makes memberships softer Smaller fuzziness makes assignments harder
Agglomerative --clusters, --linkage More target clusters keeps finer structure Fewer target clusters force more merging
DBSCAN --eps, --min-samples Larger eps or smaller min-samples tends to merge more points Smaller eps or larger min-samples tends to split clusters and create more noise
OPTICS --xi, --min-cluster-size Larger minimum size favors broader, more conservative clusters Smaller minimum size allows finer clusters but can fragment the result
Spectral --clusters, --neighbors More neighbors smooth the graph more strongly Fewer neighbors keep local structure sharper but can disconnect the graph

K-Means++

Core idea

K-Means++ is still the classic k-means objective, but it replaces random seeding with a smarter initialization strategy. By spreading the initial centers apart, it usually reaches better local optima and converges faster than naive random starts.

Algorithm steps

  1. Pick the first center randomly.
  2. Pick each later center with probability proportional to its squared distance from the closest existing center.
  3. Assign every sample to the nearest center.
  4. Recompute each center as the mean of its assigned samples.
  5. Repeat the assign-and-update cycle until the centers barely move.

Process map

mermaid
flowchart TD
    A["Initialize centers with k-means++"] --> B["Assign every point to the nearest center"]
    B --> C["Recompute each center as the cluster mean"]
    C --> D{"Centers moved less than tolerance?"}
    D -- "No" --> B
    D -- "Yes" --> E["Return labels, centers, and center trace"]

Key parameters

  • --clusters: number of centers to fit.
  • --max-iter: optimization steps before forcing a stop.
  • --tolerance: convergence threshold for center movement.

Strengths

  • Fast and easy to interpret.
  • Excellent baseline for compact, balanced clusters.
  • Initialization is much more stable than plain random k-means.

Limitations

  • Requires the number of clusters in advance.
  • Sensitive to strong outliers because every point must belong somewhere.
  • Assumes mean-like centers represent the cluster shape well.

Use when

  • You need a simple, strong baseline.
  • The data contains roughly spherical or blob-like clusters.
  • Speed matters more than modeling complex geometry.

Avoid when

  • Cluster shapes are curved, nested, or strongly non-convex.
  • The dataset contains obvious noise points.
  • You need soft assignments instead of one label per point.

Complexity

  • Time: O(nkt) where n is the sample count, k is the cluster count, and t is the number of iterations.
  • Space: O(n + k) for the main state in this demo.

Run

bash
python3 k_means_plus_plus.py --samples 320 --clusters 4 --output k_means_plus_plus.png

Core source snippet

…

Key parameters

  • --clusters: number of fuzzy centers.
  • --fuzziness: controls how soft the memberships are. Values closer to 1 behave more like hard clustering.
  • --max-iter: optimization budget.
  • --tolerance: convergence threshold.

Strengths

  • Preserves uncertainty at cluster boundaries.
  • More expressive than hard assignments when groups overlap.
  • Useful for exploratory analysis and soft decision support.

Limitations

  • Still requires the cluster count in advance.
  • Still does not have a native noise model.
  • Costs more than K-Means because it updates the full membership matrix.

Use when

  • Samples can reasonably belong to more than one group.
  • You want interpretable center-based clustering with soft confidence.
  • You need a bridge between hard partitioning and probabilistic thinking.

Avoid when

  • Noise rejection is the first priority.
  • You need a very large-scale solution with minimal memory use.
  • Non-convex cluster shapes dominate the problem.

Complexity

  • Time: O(nkt) with a larger constant than K-Means.
  • Space: O(nk) because the membership matrix is stored explicitly.

Run

bash
python3 fuzzy_c_means.py --samples 320 --clusters 4 --fuzziness 2.0 --output fuzzy_c_means.png

Core source snippet

…

Source: fuzzy_c_means.py

Agglomerative Hierarchical Clustering

Core idea

Agglomerative clustering starts with one cluster per point and repeatedly merges the closest pair of clusters. Instead of committing to one level immediately, it builds structure from fine detail to coarse detail.

Algorithm steps

  1. Treat each point as its own cluster.
  2. Compute inter-cluster distances with a linkage rule.
  3. Merge the closest pair of clusters.
  4. Repeat until only the requested number of clusters remains.

Process map

mermaid
flowchart TD
    A["Start with one cluster per point"] --> B["Measure distances between clusters"]
    B --> C["Merge the closest two clusters"]
    C --> D{"Target number of clusters reached?"}
    D -- "No" --> B
    D -- "Yes" --> E["Cut the hierarchy and output labels"]

Key parameters

  • --clusters: number of clusters to keep at the cut level.
  • --linkage: single, average, or complete.

Strengths

  • Produces a multi-lev

Issues· 0 open

View all issuesOpen on GitHub

No open issues yet, or sync has not completed.

> Tags

Python

No comments yet. Be the first to share.

> Details

PublishedAug 1, 2026
UpdatedSep 17, 2026
Category编程语言
PricingOpen source

> Related tools

T
TypeScript
JavaScript 的超集,为前端与全栈提供静态类型
P
Python
通用编程语言,广泛用于 Web、数据与 AI
G
Go
Google 推出的简洁高效系统语言