Struct KMeans 

pub struct KMeans { /* private fields */ }

K-Means clustering algorithm.

Uses Lloyd’s algorithm with k-means++ initialization for faster convergence.

Algorithm

1. Initialize centroids using k-means++
2. Assign each sample to nearest centroid
3. Update centroids as mean of assigned samples
4. Repeat until convergence or max iterations

Examples

use aprender::prelude::*;

let data = Matrix::from_vec(6, 2, vec![
    1.0, 2.0,
    1.5, 1.8,
    5.0, 8.0,
    8.0, 8.0,
    1.0, 0.6,
    9.0, 11.0,
]).expect("Valid matrix dimensions and data length");

let mut kmeans = KMeans::new(2);
kmeans.fit(&data).expect("Fit succeeds with valid data");

let labels = kmeans.predict(&data);
assert_eq!(labels.len(), 6);

Performance

• Time complexity: O(nkdi) where n=samples, k=clusters, d=features, i=iterations
• Space complexity: O(nk)

Implementations

impl KMeans

pub fn new(n_clusters: usize) -> KMeans

Creates a new K-Means with the specified number of clusters.

pub fn with_max_iter(self, max_iter: usize) -> KMeans

Sets the maximum number of iterations.

pub fn with_tol(self, tol: f32) -> KMeans

Sets the convergence tolerance.

pub fn with_random_state(self, seed: u64) -> KMeans

Sets the random seed for reproducibility.

pub fn centroids(&self) -> &Matrix<f32>

Returns the cluster centroids.

Panics

Panics if model is not fitted.

pub fn inertia(&self) -> f32

Returns the inertia (within-cluster sum of squares).

pub fn n_iter(&self) -> usize

Returns the number of iterations run.

pub fn is_fitted(&self) -> bool

Returns true if the model has been fitted.

pub fn n_clusters(&self) -> usize

Returns the number of clusters.

pub fn max_iter(&self) -> usize

Returns the maximum number of iterations.

pub fn tol(&self) -> f32

Returns the convergence tolerance.

pub fn random_state(&self) -> Option<u64>

Returns the random state.

pub fn save<P>(&self, path: P) -> Result<(), String>

where P: AsRef<Path>,

Saves the model to a binary file using bincode.

Errors

Returns an error if serialization or file writing fails.

pub fn load<P>(path: P) -> Result<KMeans, String>

where P: AsRef<Path>,

Loads a model from a binary file.

Errors

Returns an error if file reading or deserialization fails.

pub fn save_safetensors<P>(&self, path: P) -> Result<(), String>

where P: AsRef<Path>,

Saves the K-Means model to a SafeTensors file.

Arguments

• path - Path where the SafeTensors file will be saved

Errors

Returns an error if the model is unfitted or if saving fails.

pub fn load_safetensors<P>(path: P) -> Result<KMeans, String>

where P: AsRef<Path>,

Loads a K-Means model from a SafeTensors file.

Arguments

• path - Path to the SafeTensors file

Errors

Returns an error if loading fails or if the file format is invalid.

Trait Implementations

impl Clone for KMeans

fn clone(&self) -> KMeans

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for KMeans

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Default for KMeans

fn default() -> KMeans

Returns the “default value” for a type.

impl<'de> Deserialize<'de> for KMeans

fn deserialize<__D>( __deserializer: __D, ) -> Result<KMeans, <__D as Deserializer<'de>>::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl Serialize for KMeans

fn serialize<__S>( &self, __serializer: __S, ) -> Result<<__S as Serializer>::Ok, <__S as Serializer>::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl UnsupervisedEstimator for KMeans

fn fit(&mut self, x: &Matrix<f32>) -> Result<(), AprenderError>

Fits the K-Means model to data.

Errors

Returns an error if:

• Data has fewer samples than clusters
• Data is empty

fn predict(&self, x: &Matrix<f32>) -> Vec<usize>

Predicts cluster labels for new data.

type Labels = Vec<usize>

The type of labels/clusters produced.