ferrolearn_cluster/
lib.rs

1//! # ferrolearn-cluster
2//!
3//! Clustering algorithms for the ferrolearn machine learning framework.
4//!
5//! This crate provides unsupervised clustering methods:
6//!
7//! - **[`KMeans`]** — K-Means clustering with k-Means++ initialization
8//!   and parallelized assignment via Rayon (REQ-6).
9//! - **[`DBSCAN`]** — Density-Based Spatial Clustering of Applications
10//!   with Noise (REQ-7).
11//! - **[`GaussianMixture`]** — Gaussian Mixture Models via the
12//!   Expectation-Maximisation algorithm, with four covariance types
13//!   (full, tied, diagonal, spherical) (REQ-3).
14//! - **[`AgglomerativeClustering`]** — Bottom-up hierarchical clustering
15//!   with Ward, Complete, Average, and Single linkage (REQ-5).
16//! - **[`MeanShift`]** — Non-parametric mode-seeking clustering (REQ-23).
17//! - **[`SpectralClustering`]** — Graph Laplacian eigenmap clustering (REQ-23).
18//! - **[`OPTICS`]** — Ordering Points To Identify the Clustering Structure (REQ-23).
19//! - **[`Hdbscan`]** — Hierarchical DBSCAN with automatic cluster detection.
20//! - **[`Birch`]** — Balanced Iterative Reducing and Clustering using Hierarchies.
21//! - **[`LabelPropagation`]** — Semi-supervised label propagation through a similarity graph.
22//! - **[`LabelSpreading`]** — Semi-supervised label spreading via normalized graph Laplacian.
23//! - **[`AffinityPropagation`]** — Exemplar-based clustering via message passing,
24//!   automatically determines number of clusters.
25//! - **[`BisectingKMeans`]** — Divisive hierarchical clustering that recursively
26//!   bisects the largest cluster.
27//! - **[`BayesianGaussianMixture`]** — Variational Bayesian GMM with
28//!   automatic component pruning via Dirichlet Process or Dirichlet
29//!   Distribution priors.
30//! - **[`FeatureAgglomeration`]** — Hierarchical clustering of features
31//!   (columns) with pooling-based dimensionality reduction.
32//!
33//! # Design
34//!
35//! All algorithms follow the compile-time safety pattern:
36//!
37//! - The unfitted config struct implements [`Fit`](ferrolearn_core::Fit)
38//!   with `Y = ()` (unsupervised).
39//! - [`KMeans`] produces [`FittedKMeans`], which implements
40//!   [`Predict`](ferrolearn_core::Predict) (assign to nearest centroid)
41//!   and [`Transform`](ferrolearn_core::Transform) (distance to each centroid).
42//! - [`DBSCAN`] produces [`FittedDBSCAN`], which only stores labels and
43//!   core sample indices — it does **not** implement `Predict`.
44//! - [`GaussianMixture`] produces [`FittedGaussianMixture`], which
45//!   implements [`Predict`](ferrolearn_core::Predict) (hard assignment) and
46//!   [`Transform`](ferrolearn_core::Transform) (soft responsibilities).
47//! - [`AgglomerativeClustering`] produces [`FittedAgglomerativeClustering`],
48//!   which stores labels and the merge tree — it does **not** implement
49//!   `Predict`.
50//! - [`MeanShift`] produces [`FittedMeanShift`], which implements
51//!   [`Predict`](ferrolearn_core::Predict) (assign to nearest center).
52//! - [`SpectralClustering`] produces [`FittedSpectralClustering`], which stores
53//!   labels — it does **not** implement `Predict`.
54//! - [`OPTICS`] produces [`FittedOPTICS`], which stores the reachability
55//!   ordering and distances — it does **not** implement `Predict`.
56//! - [`Hdbscan`] produces [`FittedHdbscan`], which stores labels and
57//!   probabilities — it does **not** implement `Predict`.
58//! - [`Birch`] produces [`FittedBirch`], which stores labels and subcluster
59//!   centers — it does **not** implement `Predict`.
60//! - [`LabelPropagation`] produces [`FittedLabelPropagation`], which implements
61//!   [`Predict`](ferrolearn_core::Predict) for new data via nearest-neighbor lookup.
62//! - [`LabelSpreading`] produces [`FittedLabelSpreading`], which implements
63//!   [`Predict`](ferrolearn_core::Predict) for new data via nearest-neighbor lookup.
64//! - [`AffinityPropagation`] produces [`FittedAffinityPropagation`], which stores
65//!   exemplar indices and labels — it does **not** implement `Predict`.
66//! - [`BisectingKMeans`] produces [`FittedBisectingKMeans`], which implements
67//!   [`Predict`](ferrolearn_core::Predict) (assign to nearest center).
68//! - [`BayesianGaussianMixture`] produces [`FittedBayesianGaussianMixture`],
69//!   which implements [`Predict`](ferrolearn_core::Predict) (hard assignment).
70//! - [`FeatureAgglomeration`] produces [`FittedFeatureAgglomeration`], which
71//!   implements [`Transform`](ferrolearn_core::Transform) (pool features).
72//!
73//! # Float Generics
74//!
75//! All algorithms are generic over `F: num_traits::Float + Send + Sync + 'static`,
76//! supporting both `f32` and `f64`.
77
78pub mod affinity_propagation;
79pub mod agglomerative;
80pub mod bayesian_gmm;
81pub mod birch;
82pub mod bisecting_kmeans;
83pub mod dbscan;
84pub mod feature_agglomeration;
85pub mod gmm;
86pub mod hdbscan;
87pub mod kmeans;
88pub mod label_propagation;
89pub mod label_spreading;
90pub mod mean_shift;
91pub mod mini_batch_kmeans;
92pub mod optics;
93pub mod spectral;
94
95// Re-export the main types at the crate root.
96pub use affinity_propagation::{AffinityPropagation, FittedAffinityPropagation};
97pub use agglomerative::{AgglomerativeClustering, FittedAgglomerativeClustering, Linkage};
98pub use bayesian_gmm::{
99    BayesianCovType, BayesianGaussianMixture, FittedBayesianGaussianMixture, WeightPriorType,
100};
101pub use birch::{Birch, FittedBirch};
102pub use bisecting_kmeans::{BisectingKMeans, BisectingStrategy, FittedBisectingKMeans};
103pub use dbscan::{DBSCAN, FittedDBSCAN};
104pub use feature_agglomeration::{
105    AgglomerativeLinkage, FeatureAgglomeration, FittedFeatureAgglomeration, PoolingFunc,
106};
107pub use gmm::{CovarianceType, FittedGaussianMixture, GaussianMixture};
108pub use hdbscan::{FittedHdbscan, Hdbscan};
109pub use kmeans::{FittedKMeans, KMeans};
110pub use label_propagation::{FittedLabelPropagation, LabelPropagation, LabelPropagationKernel};
111pub use label_spreading::{FittedLabelSpreading, LabelSpreading, LabelSpreadingKernel};
112pub use mean_shift::{FittedMeanShift, MeanShift};
113pub use mini_batch_kmeans::{FittedMiniBatchKMeans, MiniBatchKMeans, MiniBatchKMeansInit};
114pub use optics::{FittedOPTICS, OPTICS};
115pub use spectral::{FittedSpectralClustering, SpectralClustering};
ferrolearn_cluster/lib.rs

ferrolearn_cluster/
lib.rs
