cluster-ts

Lightweight clustering library for TypeScript. Zero dependencies, < 4kB 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