Struct CorrelationClustering 

pub struct CorrelationClustering { /* private fields */ }

Correlation clustering via PIVOT with optional local search refinement.

use clump::cluster::correlation::{CorrelationClustering, SignedEdge};

let edges = vec![
    SignedEdge { i: 0, j: 1, weight: 1.0 },
    SignedEdge { i: 0, j: 2, weight: -1.0 },
    SignedEdge { i: 1, j: 2, weight: -1.0 },
];

let result = CorrelationClustering::new()
    .with_seed(42)
    .fit(3, &edges)
    .unwrap();

assert_eq!(result.labels[0], result.labels[1]);
assert_ne!(result.labels[0], result.labels[2]);

Implementations

impl CorrelationClustering

pub fn new() -> CorrelationClustering

Create a new correlation clusterer with default parameters.

Defaults: max_iter = 100, no fixed seed.

pub fn with_seed(self, seed: u64) -> CorrelationClustering

Set the random seed for reproducibility.

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

Set the maximum number of local search iterations.

Pass 0 to skip local search and return the raw PIVOT solution.

pub fn fit( &self, n_items: usize, edges: &[SignedEdge], ) -> Result<CorrelationResult, Error>

Cluster items based on signed pairwise edges.

• n_items: total number of items. Items with no edges become singletons.
• edges: signed pairwise relationships.

Pipeline: precluster (merge almost-cliques) -> contract graph -> PIVOT + merge + local search on contracted graph -> iterated flip on contracted graph -> expand back to original vertices.

Preclustering is inspired by Cohen-Addad et al. (STOC 2024, arXiv 2404.05433). Vertex pairs with a positive edge and Jaccard similarity >= 0.5 over their positive neighborhoods are merged before the main algorithm runs, reducing the effective graph size and giving local search a better starting point.

Returns Error::InvalidParameter if any edge references an item index >= n_items.

pub fn edges_from_distances<D>( data: &[Vec<f32>], metric: &D, threshold: f32, ) -> Vec<SignedEdge>

where D: DistanceMetric,

Create signed edges from a distance matrix and a threshold.

Pairs closer than threshold get positive weight = threshold - distance. Pairs farther than threshold get negative weight = threshold - distance (which is negative). Pairs at exactly threshold get weight 0 and are included but contribute no cost.

Trait Implementations

impl Clone for CorrelationClustering

fn clone(&self) -> CorrelationClustering

Returns a duplicate of the value.

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

Performs copy-assignment from source.

impl Debug for CorrelationClustering

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

Formats the value using the given formatter.

impl Default for CorrelationClustering

fn default() -> CorrelationClustering

Returns the “default value” for a type.