# gizml:cluster clustering with a predict step: k-means (k-means++ and Lloyd), mini-batch k-means, BIRCH (CF subclusters, then Ward agglomeration by the nearest-neighbor chain), affinity propagation and mean shift. A model is a set of centers with a cluster label each: a row takes the label of its nearest center. Matrices are row-major. ```gizlang import * as Cluster from "gizml:cluster"; ``` ## Types ### `Centers` ```gizlang type Centers = { centers: Vec; count: i64; features: i64; labels: Vec; } ``` The result of clustering: the centers (row-major), their count and feature width, and the center of each sample. - `centers`: `Vec` - `count`: `i64` - `features`: `i64` - `labels`: `Vec` ### `MiniBatch` ```gizlang type MiniBatch = { centers: Vec; counts: Vec; k: i64; features: i64; } ``` Mini-batch k-means fed one batch at a time (scikit-learn's partial_fit): the first batch places the centers by k-means++, and each batch is one step. - `centers`: `Vec` - `counts`: `Vec` - `k`: `i64` - `features`: `i64` ## Functions ### `kmeans` ```gizlang function kmeans(x: Vec, n: i64, d: i64, k: i64, maxIter: i64, tol: f64, rng: mut Random): Centers ``` k-means: k-means++ seeds, then Lloyd until the squared center shift is at most tol × the mean feature variance. Effects: fail. ### `miniBatch` ```gizlang function miniBatch(k: i64, d: i64): MiniBatch ``` A mini-batch k-means of K centers over D features, before its first batch. Effects: fail. ### `miniBatchKmeans` ```gizlang function miniBatchKmeans(x: Vec, n: i64, d: i64, k: i64, batch: i64, maxIter: i64, rng: mut Random): Centers ``` Mini-batch k-means: k-means++ on a sample of 3 batches, then batch steps with a per-center rate of 1 / count, until the smoothed batch inertia does not improve for 10 steps. Effects: fail. ### `birch` ```gizlang function birch(x: Vec, n: i64, d: i64, threshold: f64, k: i64): Centers ``` BIRCH: CF subclusters of radius at most `threshold` (each row joins its nearest subcluster when the merged radius stays within it), then Ward agglomeration of their centroids into k clusters (k 0: each subcluster is a cluster). Effects: fail. ### `affinityPropagation` ```gizlang function affinityPropagation(x: Vec, n: i64, d: i64, damping: f64, maxIter: i64, convergence: i64, rng: mut Random): Centers ``` Affinity propagation on negative squared distances, the preference the median similarity. No convergence in maxIter iterations gives no centers, as scikit-learn labels every row -1. Effects: fail. ### `meanShift` ```gizlang function meanShift(x: Vec, n: i64, d: i64, bandwidth0: f64, maxIter: i64): Centers ``` Mean shift with a flat kernel from every row; the bandwidth (0: estimated as the mean distance to the 30% nearest neighbor), centers closer than the bandwidth to a stronger one removed. Effects: fail. ## Methods ### `Centers.nearest` ```gizlang function Centers.nearest(self: Centers, row: Vec): i64 ``` The label of the center nearest to the row; -1 when there are no centers. Effects: fail. ### `MiniBatch.step` ```gizlang function MiniBatch.step(self: mut MiniBatch, x: Vec, n: i64, rng: mut Random): bool throws string ``` One step of mini-batch k-means on the N rows of X: the first batch seeds the centers by k-means++. Effects: fail. ### `MiniBatch.result` ```gizlang function MiniBatch.result(self: MiniBatch): Centers ``` The centers that the batches so far found, as a fitted model. Effects: fail.