Signature

sp.build_dbscan_chart(
    title: str,
    x_values: list[float],
    y_values: list[float],
    *,
    eps: float = 0.5,
    min_samples: int = 5,
    width: int = 900,
    height: int = 480,
    x_label: str = "",
    y_label: str = "",
    gridlines: bool = True,
    palette: list[int] | None = None,
    background: str | None = None,
    normalize: bool = False,
) -> Chart

Alias : sp.dbscan

Description

Graphique de clustering DBSCAN 2D. Exécute l'algorithme DBSCAN (implémenté en Rust) et trace chaque point coloré selon son appartenance à un cluster. Les points de bruit sont affichés en gris.

Le DBSCAN de SeraPlot tourne jusqu'à 600× plus vite que scikit-learn sur de grands jeux de données.

Paramètres

Retourne

Chart

Performance vs scikit-learn

Le DBSCAN de SeraPlot est entièrement implémenté en Rust avec indexation spatiale. Sur le même matériel et le même jeu de données, il tourne jusqu'à 600× plus vite que l'implémentation de scikit-learn.

L'écart se creuse avec la taille car SeraPlot utilise un KD-tree avec accélération SIMD en interne, tandis que la surcharge Python pure de scikit-learn domine à grand nombre de points.

build_dbscan_chart exécute l'algorithme et rend le graphique en un seul appel. Si vous n'avez besoin que des étiquettes de cluster (pas du graphique), utilisez la classe DBSCAN qui est compatible sklearn (fit, labels_, n_clusters_, n_noise_).

Choisir eps et min_samples

• eps : commencez par un graphe k-distance. Un bon eps correspond au "coude" des distances triées aux k plus proches voisins. Trop petit → tout est du bruit. Trop grand → tout devient un seul cluster.
• min_samples : typiquement dim × 2 où dim est le nombre de variables. Des valeurs plus grandes produisent des clusters plus robustes mais marquent plus de points comme bruit.

Exemples

Blobs synthétiques

import seraplot as sp
import random
def make_blob(cx, cy, n=150, s=0.5):
    return [(cx + random.gauss(0, s), cy + random.gauss(0, s)) for _ in range(n)]
pts  = make_blob(0, 0) + make_blob(5, 5) + make_blob(10, 0)
x, y = zip(*pts)
chart = sp.build_dbscan_chart(
    "Clustering DBSCAN",
    x_values=list(x),
    y_values=list(y),
    eps=1.0,
    min_samples=5,
    x_label="Variable 1",
    y_label="Variable 2",
)

const sp = require('seraplot');
function makeBlob(cx, cy, n = 150, s = 0.5) {
    return Array.from({length: n}, () => [cx + (Math.random()-0.5)*s*2, cy + (Math.random()-0.5)*s*2]);
}
const pts = [...makeBlob(0,0), ...makeBlob(5,5), ...makeBlob(10,0)];
const x = pts.map(p => p[0]);
const y = pts.map(p => p[1]);
const chart = sp.build_dbscan_chart("Clustering DBSCAN", x, {
    y_values: y, eps: 1.0, min_samples: 5,
    x_label: "Variable 1", y_label: "Variable 2"
});

import * as sp from 'seraplot';
function makeBlob(cx: number, cy: number, n = 150, s = 0.5): [number, number][] {
    return Array.from({length: n}, () => [cx + (Math.random()-0.5)*s*2, cy + (Math.random()-0.5)*s*2]);
}
const pts = [...makeBlob(0,0), ...makeBlob(5,5), ...makeBlob(10,0)];
const x: number[] = pts.map(p => p[0]);
const y: number[] = pts.map(p => p[1]);
const chart = sp.build_dbscan_chart("Clustering DBSCAN", x, {
    y_values: y, eps: 1.0, min_samples: 5,
    x_label: "Variable 1", y_label: "Variable 2"
});

Avec normalisation

import seraplot as sp

chart = sp.build_dbscan_chart(
    "DBSCAN — Normalisé",
    x_values=x,
    y_values=y,
    eps=0.1,
    min_samples=5,
    normalize=True,
)

Fonctionnement algorithmique

DBSCAN regroupe les points situés dans des régions denses et marque les points isolés comme du bruit. Il ne nécessite pas de spécifier le nombre de clusters à l'avance.

Concepts clés

Pour un point $p$, son $\epsilon$-voisinage est :

• Point cœur : $|N_\epsilon(p)| \geq \text{min_samples}$
• Point frontière : accessible depuis un point cœur, mais pas lui-même un point cœur
• Point bruit : non accessible depuis aucun point cœur — label $-1$

Les clusters sont les ensembles maximaux de points densément connexes. Deux points sont densément connexes s'il existe une chaîne de sauts directement accessibles les reliant via des points cœurs.

Implémentation

SeraPlot construit un KD-tree sur les points d'entrée pour des requêtes de rayon en $O(\log n)$, puis étend chaque point cœur non visité par BFS parallèle. Un calcul de distance accéléré par SIMD est appliqué à chaque feuille de l'arbre.

Avec normalize=True, les variables sont normalisées dans $[0, 1]$ avant la construction de l'arbre, pour éviter que les dimensions à grande magnitude dominent $\epsilon$.

Voir aussi

• Classe DBSCAN — pour accéder aux étiquettes et métadonnées des clusters
• DBSCAN 3D
• Nuage de points