k-means

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

• Installation
• Usage
  • Options
  • Metrics
  • Centroid Calculators
  • CentroidSelection
  • EmptyAction
• Contributing
• License

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.

Contributing

Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.

License

MIT