zer-cluster 1.0.0

Connected-components clustering and entity storage for the zer entity-resolution library
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125

use zer_cluster::{ClusterConfig, ClusterGraph};
use zer_core::{comparison::ComparisonVector, scoring::{MatchBand, ScoredPair}};

fn auto_match(a: u64, b: u64, prob: f32) -> ScoredPair {
    ScoredPair {
        record_a:          a,
        record_b:          b,
        match_weight:      0.0,
        match_probability: prob,
        vector:            ComparisonVector { record_a: a, record_b: b, levels: vec![] },
        band:              MatchBand::AutoMatch,
    }
}

fn config() -> ClusterConfig {
    ClusterConfig { max_cluster_size: 50, within_cluster_min: 0.85 }
}

// ── Connected-component basics ─────────────────────────────────────────────────

#[test]
fn single_pair_yields_one_cluster_of_two() {
    let mut g = ClusterGraph::new();
    g.add_pairs(&[auto_match(1, 2, 0.95)]);
    let clusters = g.compute_clusters(&config());
    assert_eq!(clusters.len(), 1);
    let mut c = clusters[0].clone();
    c.sort();
    assert_eq!(c, vec![1, 2]);
}

#[test]
fn three_nodes_in_chain_form_one_cluster() {
    let mut g = ClusterGraph::new();
    g.add_pairs(&[auto_match(1, 2, 0.95), auto_match(2, 3, 0.95)]);
    let clusters = g.compute_clusters(&config());
    assert_eq!(clusters.len(), 1);
    assert_eq!(clusters[0].len(), 3);
}

#[test]
fn two_disconnected_pairs_form_two_clusters() {
    let mut g = ClusterGraph::new();
    g.add_pairs(&[auto_match(1, 2, 0.95), auto_match(3, 4, 0.95)]);
    let clusters = g.compute_clusters(&config());
    assert_eq!(clusters.len(), 2);
}

#[test]
fn empty_graph_returns_no_clusters() {
    let g = ClusterGraph::new();
    assert!(g.compute_clusters(&config()).is_empty());
}

// ── Weak-edge removal / chain-breaking ────────────────────────────────────────

#[test]
fn weak_bridge_splits_chain_into_two_clusters() {
    // A -[0.95]- B -[0.28]- C -[0.95]- D
    // B-C edge is below within_cluster_min (0.85) → chain breaks
    let mut g = ClusterGraph::new();
    g.add_pairs(&[
        auto_match(1, 2, 0.95), // A-B strong
        auto_match(2, 3, 0.28), // B-C weak
        auto_match(3, 4, 0.95), // C-D strong
    ]);
    let mut clusters = g.compute_clusters(&config());
    clusters.sort_by_key(|c| *c.iter().min().unwrap());

    assert_eq!(clusters.len(), 2, "weak bridge must produce 2 clusters");

    let mut c0 = clusters[0].clone(); c0.sort();
    let mut c1 = clusters[1].clone(); c1.sort();
    assert_eq!(c0, vec![1, 2]);
    assert_eq!(c1, vec![3, 4]);
}

#[test]
fn strong_bridge_keeps_chain_intact() {
    // A -[0.95]- B -[0.90]- C  (0.90 >= 0.85 → no split)
    let mut g = ClusterGraph::new();
    g.add_pairs(&[auto_match(1, 2, 0.95), auto_match(2, 3, 0.90)]);
    let clusters = g.compute_clusters(&config());
    assert_eq!(clusters.len(), 1);
    assert_eq!(clusters[0].len(), 3);
}

#[test]
fn all_weak_edges_below_min_no_clusters() {
    // All edges below min → every edge removed → no component of size ≥ 2
    let mut g = ClusterGraph::new();
    g.add_pairs(&[
        auto_match(1, 2, 0.50),
        auto_match(2, 3, 0.60),
        auto_match(3, 4, 0.70),
    ]);
    let clusters = g.compute_clusters(&config());
    assert!(clusters.is_empty(), "all-weak edges should yield no clusters");
}

// ── Star pruning ───────────────────────────────────────────────────────────────

#[test]
fn star_pruning_handles_oversized_cluster_without_panic() {
    // Hub (0) connected to 60 satellites, exceeds max_cluster_size=50
    let cfg = ClusterConfig { max_cluster_size: 50, within_cluster_min: 0.85 };
    let mut g = ClusterGraph::new();
    let pairs: Vec<_> = (1u64..=60).map(|i| auto_match(0, i, 0.95)).collect();
    g.add_pairs(&pairs);

    let clusters = g.compute_clusters(&cfg);
    // Star pruning must complete without panic; result must cover non-trivial groups.
    let total: usize = clusters.iter().map(|c| c.len()).sum();
    assert!(total >= 2);
}

#[test]
fn duplicate_pairs_do_not_add_duplicate_edges() {
    let mut g = ClusterGraph::new();
    // Add the same pair twice.
    g.add_pairs(&[auto_match(1, 2, 0.95), auto_match(1, 2, 0.90)]);
    let clusters = g.compute_clusters(&config());
    assert_eq!(clusters.len(), 1);
    assert_eq!(clusters[0].len(), 2);
}