cluster-ts

Lightweight clustering library for TypeScript. Zero dependencies, < 5kB gzipped.

Install

npm install cluster-ts

Usage

K-Means

import { kmeans } from 'cluster-ts';

const result = kmeans(data, { k: 3 });

result.clusters;   // [0, 0, 1, 1, 2, 2] - cluster assignment per point
result.centroids;  // final centroid positions
result.converged;  // true if converged
result.iterations; // iteration count
result.inertia;    // sum of squared distances

Options:

| Option | Default | Description | |--------|---------|-------------| | k | required | Number of clusters | | maxIterations | 100 | Max iterations | | tolerance | 1e-4 | Convergence threshold | | initialization | 'kmeans++' | 'random' or 'kmeans++' | | distance | 'euclidean' | 'euclidean', 'manhattan', 'cosine', or custom function | | seed | — | Random seed for reproducibility |

DBSCAN

import { dbscan } from 'cluster-ts';

const result = dbscan(data, { epsilon: 2, minPoints: 3 });

result.clusters;     // cluster assignment (-1 = noise)
result.noise;        // indices of noise points
result.clusterCount; // number of clusters found

Options:

| Option | Default | Description | |--------|---------|-------------| | epsilon | required | Max distance between neighbors | | minPoints | required | Min points to form a cluster | | distance | 'euclidean' | Distance metric or custom function |

Custom Distance Function

const chebyshev = (a: number[], b: number[]) => 
  Math.max(...a.map((v, i) => Math.abs(v - b[i])));

kmeans(data, { k: 3, distance: chebyshev });

Distance Functions

import { euclidean, manhattan, cosine } from 'cluster-ts';

K-Means vs DBSCAN

| | K-Means | DBSCAN | |-|---------|--------| | Cluster count | You specify k | Auto-detected | | Cluster shape | Spherical | Arbitrary | | Handles outliers | No | Yes | | Deterministic | No (use seed) | Yes |

K-Means: Know cluster count, need speed, spherical clusters.

DBSCAN: Unknown cluster count, need outlier detection, irregular shapes.

Types

type Point = number[];
type DistanceFunction = (a: Point, b: Point) => number;

License

MIT