Skip to main content

solow_cluster/
lib.rs

1//! # solow-cluster
2//!
3//! Unsupervised clustering for the Solow statistical stack.
4//!
5//! The crate ships three families that together cover the classical
6//! unsupervised-learning use cases:
7//!
8//! * **Centroid-based:** [`KMeans`] with the Arthur-Vassilvitskii
9//!   [`k-means++`](https://en.wikipedia.org/wiki/K-means%2B%2B)
10//!   initialisation and Lloyd's iterative refinement. Deterministic
11//!   under a caller-supplied seed via a portable MMIX-LCG PRNG.
12//! * **Density-based:** [`Dbscan`] — the Ester-Kriegel-Sander-Xu
13//!   (KDD 1996) `ε`, `min_samples` classifier. Reports per-point
14//!   `Core` / `Border` / `Noise` roles alongside the cluster label.
15//! * **Hierarchical:** [`AgglomerativeClustering`] with `Single`,
16//!   `Complete`, `Average`, or `Ward` linkage. Uses the Lance-Williams
17//!   update recurrence so the whole dendrogram is built in `O(n² · log n)`
18//!   time with `O(n²)` space.
19//!
20//! Every clusterer exposes the classical `fit_predict(x) -> labels`
21//! call, plus a richer typed result carrying centroids / linkage
22//! matrices / core-point flags when applicable. All types derive
23//! `Serialize` / `Deserialize` under the opt-in `serde` feature.
24//!
25//! ## Convergence and complexity
26//!
27//! * `KMeans`: each Lloyd iteration is `O(n · k · d)`. `k-means++`
28//!   pre-fit is `O(n · k · d)` in expectation and guarantees an
29//!   `O(log k)`-competitive initial inertia (Arthur & Vassilvitskii 2007).
30//! * `DBSCAN`: naive neighbour lookup is `O(n²)`; use
31//!   [`solow-neighbors`](https://docs.rs/solow-neighbors) `KDTree`
32//!   externally to obtain `O(n log n)` for low-dimensional data.
33//! * `AgglomerativeClustering`: `O(n² · log n)` time, `O(n²)` space
34//!   via Müllner (2011) *Modern hierarchical, agglomerative clustering
35//!   algorithms*.
36//!
37//! ## Determinism
38//!
39//! Every stochastic component (`KMeans` init, `MiniBatchKMeans` batch
40//! draws) uses a portable 64-bit MMIX linear-congruential generator
41//! seeded by the caller. Fits are bit-identical across runs and
42//! platforms given a fixed seed and input.
43
44#![forbid(unsafe_code)]
45#![warn(missing_docs)]
46
47pub mod affinity_propagation;
48pub mod agglomerative;
49pub mod bgmm;
50pub mod birch;
51pub mod dbscan;
52pub mod gmm;
53pub mod hdbscan;
54pub mod kmeans;
55pub mod meanshift;
56pub mod minibatch;
57pub mod optics;
58pub mod spectral;
59
60pub use affinity_propagation::AffinityPropagation;
61pub use agglomerative::{AgglomerativeClustering, DendrogramNode, Linkage};
62pub use bgmm::BayesianGaussianMixture;
63pub use birch::Birch;
64pub use dbscan::{Dbscan, DbscanResult, PointRole};
65pub use gmm::{CovType, GaussianMixture};
66pub use hdbscan::Hdbscan;
67pub use kmeans::{KMeans, KMeansInit, KMeansResult};
68pub use meanshift::MeanShift;
69pub use minibatch::{BisectingKMeans, MiniBatchKMeans};
70pub use optics::Optics;
71pub use spectral::SpectralClustering;
72
73/// Commonly-used imports.
74pub mod prelude {
75    pub use crate::affinity_propagation::AffinityPropagation;
76    pub use crate::agglomerative::{AgglomerativeClustering, DendrogramNode, Linkage};
77    pub use crate::birch::Birch;
78    pub use crate::dbscan::{Dbscan, DbscanResult, PointRole};
79    pub use crate::hdbscan::Hdbscan;
80    pub use crate::kmeans::{KMeans, KMeansInit, KMeansResult};
81    pub use crate::minibatch::{BisectingKMeans, MiniBatchKMeans};
82    pub use crate::optics::Optics;
83    pub use crate::spectral::SpectralClustering;
84}