@alkocats/k-means NPM

k-means

This package is a typescript implementation of the k-means algorithm with different customization capabilities.

Installation

Use npm to install k-means:

npm install k-means

Usage

Simplest setup for the usage of k-means:

import { KMeans, Vector } from '@alkocats/k-means'

const kMeans = new KMeans({
    clusterCount: 2
});
const points: Vector[] = [
    [1, 1],
    [1.5, 2],
    [3, 4],
    [5, 7],
    [3.5, 5],
    [4.5, 5],
    [3.5, 4.5],
];
const result = kMeans.fit(points);

// As the starting centroids are set randomly, this values might change
// or one cluster might even get deleted
console.log(result.meanSquaredError);
// 0.9252
console.log(result.iterations);
// 6
console.log(result.clusterIndices);
// [ 1, 1, 0, 0, 0, 0, 0 ]
console.log(result.clusters[0].centroid);
// [ 3.9, 5.1 ]
console.log(result.clusters[0].vectors);
// [ [ 3, 4 ], [ 5, 7 ], [ 3.5, 5 ], [ 4.5, 5 ], [ 3.5, 4.5 ] ]
console.log(result.clusters[1].centroid);
// [ 1.25, 1.5 ]
console.log(result.clusters[1].vectors);
// [ [ 1, 1 ], [ 1.5, 2 ] ]

Options

Name	Type	Default
`metric`	`Metric`	`new EuclidianDistance()`
`centroidCalculator`	`CentroidCalculator`	`new MeanCentroidCalculator()`
`clusterCount`	`number`	`1`
`maxIterations`	`number`	`100`
`centroidSelection`	`CentroidSelection`	`CentroidSelection.RANDOM`
`centroids`	`Vector[] \\| Matrix`	`null`
`emptyAction`	`EmptyAction`	`EmptyAction.DROP`

Metrics

new EuclidianDistance(): Calculates the euclidian distance between two vectors with the same number of elements (n).
new ManhattanDistance(): Calculates the manhattan distance between two vectors with the same number of elements (n).

Centroid Calculators

new MeanCentroidCalculator(): Calculates the center of an array of vectors according to the mean of the vectors.
new MedianCentroidCalculator(): Calculates the center of an array of vectors according to the median of the vectors.

CentroidSelection

CentroidSelection.RANDOM: Generates n (accodring to clusterCount) starting centroids by selecting random points within the vector limits.
CentroidSelection.PREDEFINED: Takes the centroids given by centroids as the starting centroids.
CentroidSelection.KMEANSPLUSPLUS: Uses the k-means++ algorithm to determine the starting centroid.

EmptyAction

EmptyAction.DROP: Deletes a cluster if it does not have any vectors assigned to.
EmptyAction.ERROR: Throws an error if any cluster does not have any vectors assigned to.