|
1 |
+ |
//! Unsupervised clustering bootstrap (cold-start for the tag pipeline).
|
|
2 |
+ |
//!
|
|
3 |
+ |
//! Groups a library's persisted feature vectors so the user can name clusters and seed
|
|
4 |
+ |
//! the first labels before any rules or manual tagging exist. k-means runs over
|
|
5 |
+ |
//! z-standardized features (MFCC and spectral scales differ by orders of magnitude) with
|
|
6 |
+ |
//! deterministic farthest-first seeding — no RNG dependency, reproducible results.
|
|
7 |
+ |
//!
|
|
8 |
+ |
//! Clustering itself writes nothing; `apply_cluster_tag` is what a named cluster does,
|
|
9 |
+ |
//! recording `source = 'cluster'` provenance (sticky — the rules engine never reconciles
|
|
10 |
+ |
//! these away). See [`crate::rules`] for the provenance model.
|
|
11 |
+ |
|
|
12 |
+ |
use crate::db::Database;
|
|
13 |
+ |
use crate::error::{CoreError, Result};
|
|
14 |
+ |
use tracing::instrument;
|
|
15 |
+ |
|
|
16 |
+ |
use super::classify::{FEATURE_VERSION, NUM_FEATURES};
|
|
17 |
+ |
|
|
18 |
+ |
/// One cluster: a representative (medoid) sample plus its members.
|
|
19 |
+ |
#[derive(Debug, Clone)]
|
|
20 |
+ |
pub struct Cluster {
|
|
21 |
+ |
pub id: usize,
|
|
22 |
+ |
/// Member nearest the centroid — a playable representative for naming.
|
|
23 |
+ |
pub medoid_hash: String,
|
|
24 |
+ |
pub member_hashes: Vec<String>,
|
|
25 |
+ |
}
|
|
26 |
+ |
|
|
27 |
+ |
/// Result of clustering a library.
|
|
28 |
+ |
#[derive(Debug, Clone)]
|
|
29 |
+ |
pub struct ClusterResult {
|
|
30 |
+ |
pub clusters: Vec<Cluster>,
|
|
31 |
+ |
/// Feature-extractor version the vectors were produced with.
|
|
32 |
+ |
pub feature_version: u32,
|
|
33 |
+ |
}
|
|
34 |
+ |
|
|
35 |
+ |
/// Suggested cluster count for `n` samples: ~sqrt(n/2), clamped to a sane UI range.
|
|
36 |
+ |
pub fn suggest_k(n: usize) -> usize {
|
|
37 |
+ |
if n < 2 {
|
|
38 |
+ |
return n;
|
|
39 |
+ |
}
|
|
40 |
+ |
let k = ((n as f64 / 2.0).sqrt()).round() as usize;
|
|
41 |
+ |
k.clamp(2, 24).min(n)
|
|
42 |
+ |
}
|
|
43 |
+ |
|
|
44 |
+ |
/// Load all current-version feature vectors as `(hash, vector)` pairs.
|
|
45 |
+ |
fn load_vectors(db: &Database) -> Result<Vec<(String, Vec<f64>)>> {
|
|
46 |
+ |
let mut stmt = db.conn().prepare(
|
|
47 |
+ |
"SELECT hash, vector FROM sample_features WHERE feat_version = ?1",
|
|
48 |
+ |
)?;
|
|
49 |
+ |
let rows = stmt.query_map([FEATURE_VERSION], |row| {
|
|
50 |
+ |
Ok((row.get::<_, String>(0)?, row.get::<_, String>(1)?))
|
|
51 |
+ |
})?;
|
|
52 |
+ |
|
|
53 |
+ |
let mut out = Vec::new();
|
|
54 |
+ |
for r in rows {
|
|
55 |
+ |
let (hash, json) = r?;
|
|
56 |
+ |
let v: Vec<f64> =
|
|
57 |
+ |
serde_json::from_str(&json).map_err(|e| CoreError::Serialization(e.to_string()))?;
|
|
58 |
+ |
if v.len() == NUM_FEATURES {
|
|
59 |
+ |
out.push((hash, v));
|
|
60 |
+ |
}
|
|
61 |
+ |
}
|
|
62 |
+ |
Ok(out)
|
|
63 |
+ |
}
|
|
64 |
+ |
|
|
65 |
+ |
/// z-standardize each dimension across the dataset (in place). Zero-variance dims
|
|
66 |
+ |
/// collapse to 0.0. Returns nothing — operates on the supplied matrix.
|
|
67 |
+ |
fn standardize(vectors: &mut [Vec<f64>]) {
|
|
68 |
+ |
if vectors.is_empty() {
|
|
69 |
+ |
return;
|
|
70 |
+ |
}
|
|
71 |
+ |
let dims = vectors[0].len();
|
|
72 |
+ |
let n = vectors.len() as f64;
|
|
73 |
+ |
for d in 0..dims {
|
|
74 |
+ |
let mean = vectors.iter().map(|v| v[d]).sum::<f64>() / n;
|
|
75 |
+ |
let var = vectors.iter().map(|v| (v[d] - mean).powi(2)).sum::<f64>() / n;
|
|
76 |
+ |
let std = var.sqrt();
|
|
77 |
+ |
if std > f64::EPSILON {
|
|
78 |
+ |
for v in vectors.iter_mut() {
|
|
79 |
+ |
v[d] = (v[d] - mean) / std;
|
|
80 |
+ |
}
|
|
81 |
+ |
} else {
|
|
82 |
+ |
for v in vectors.iter_mut() {
|
|
83 |
+ |
v[d] = 0.0;
|
|
84 |
+ |
}
|
|
85 |
+ |
}
|
|
86 |
+ |
}
|
|
87 |
+ |
}
|
|
88 |
+ |
|
|
89 |
+ |
fn sq_dist(a: &[f64], b: &[f64]) -> f64 {
|
|
90 |
+ |
a.iter().zip(b).map(|(x, y)| (x - y).powi(2)).sum()
|
|
91 |
+ |
}
|
|
92 |
+ |
|
|
93 |
+ |
/// Deterministic farthest-first seeding (Gonzalez): start from the point nearest the
|
|
94 |
+ |
/// dataset mean, then repeatedly take the point maximizing its distance to the chosen
|
|
95 |
+ |
/// set. Ties break by lowest index.
|
|
96 |
+ |
fn init_centroids(points: &[Vec<f64>], k: usize) -> Vec<Vec<f64>> {
|
|
97 |
+ |
let dims = points[0].len();
|
|
98 |
+ |
let n = points.len() as f64;
|
|
99 |
+ |
let mean: Vec<f64> = (0..dims)
|
|
100 |
+ |
.map(|d| points.iter().map(|p| p[d]).sum::<f64>() / n)
|
|
101 |
+ |
.collect();
|
|
102 |
+ |
|
|
103 |
+ |
let first = (0..points.len())
|
|
104 |
+ |
.min_by(|&a, &b| {
|
|
105 |
+ |
sq_dist(&points[a], &mean)
|
|
106 |
+ |
.partial_cmp(&sq_dist(&points[b], &mean))
|
|
107 |
+ |
.unwrap()
|
|
108 |
+ |
})
|
|
109 |
+ |
.unwrap();
|
|
110 |
+ |
|
|
111 |
+ |
let mut centroids = vec![points[first].clone()];
|
|
112 |
+ |
let mut min_d: Vec<f64> = points.iter().map(|p| sq_dist(p, &points[first])).collect();
|
|
113 |
+ |
|
|
114 |
+ |
while centroids.len() < k {
|
|
115 |
+ |
let next = (0..points.len())
|
|
116 |
+ |
.max_by(|&a, &b| min_d[a].partial_cmp(&min_d[b]).unwrap())
|
|
117 |
+ |
.unwrap();
|
|
118 |
+ |
centroids.push(points[next].clone());
|
|
119 |
+ |
for (i, p) in points.iter().enumerate() {
|
|
120 |
+ |
min_d[i] = min_d[i].min(sq_dist(p, &points[next]));
|
|
121 |
+ |
}
|
|
122 |
+ |
}
|
|
123 |
+ |
centroids
|
|
124 |
+ |
}
|
|
125 |
+ |
|
|
126 |
+ |
/// Cluster the library's feature vectors into `k` groups.
|
|
127 |
+ |
///
|
|
128 |
+ |
/// Returns clusters with member hashes and a medoid representative. `k` is clamped to
|
|
129 |
+ |
/// the number of vectors. Returns an empty result if nothing is analyzed yet.
|
|
130 |
+ |
#[instrument(skip_all)]
|
|
131 |
+ |
pub fn cluster_library(db: &Database, k: usize, max_iters: usize) -> Result<ClusterResult> {
|
|
132 |
+ |
let loaded = load_vectors(db)?;
|
|
133 |
+ |
if loaded.is_empty() || k == 0 {
|
|
134 |
+ |
return Ok(ClusterResult { clusters: Vec::new(), feature_version: FEATURE_VERSION });
|
|
135 |
+ |
}
|
|
136 |
+ |
let hashes: Vec<String> = loaded.iter().map(|(h, _)| h.clone()).collect();
|
|
137 |
+ |
let mut points: Vec<Vec<f64>> = loaded.into_iter().map(|(_, v)| v).collect();
|
|
138 |
+ |
standardize(&mut points);
|
|
139 |
+ |
|
|
140 |
+ |
let k = k.min(points.len());
|
|
141 |
+ |
let mut centroids = init_centroids(&points, k);
|
|
142 |
+ |
let mut assign = vec![0usize; points.len()];
|
|
143 |
+ |
|
|
144 |
+ |
for _ in 0..max_iters.max(1) {
|
|
145 |
+ |
// Assignment step.
|
|
146 |
+ |
let mut changed = false;
|
|
147 |
+ |
for (i, p) in points.iter().enumerate() {
|
|
148 |
+ |
let best = (0..k)
|
|
149 |
+ |
.min_by(|&a, &b| {
|
|
150 |
+ |
sq_dist(p, ¢roids[a])
|
|
151 |
+ |
.partial_cmp(&sq_dist(p, ¢roids[b]))
|
|
152 |
+ |
.unwrap()
|
|
153 |
+ |
})
|
|
154 |
+ |
.unwrap();
|
|
155 |
+ |
if best != assign[i] {
|
|
156 |
+ |
assign[i] = best;
|
|
157 |
+ |
changed = true;
|
|
158 |
+ |
}
|
|
159 |
+ |
}
|
|
160 |
+ |
if !changed {
|
|
161 |
+ |
break;
|
|
162 |
+ |
}
|
|
163 |
+ |
// Update step. Empty clusters keep their previous centroid (no NaN drift).
|
|
164 |
+ |
let dims = points[0].len();
|
|
165 |
+ |
let mut sums = vec![vec![0.0f64; dims]; k];
|
|
166 |
+ |
let mut counts = vec![0usize; k];
|
|
167 |
+ |
for (i, p) in points.iter().enumerate() {
|
|
168 |
+ |
let c = assign[i];
|
|
169 |
+ |
counts[c] += 1;
|
|
170 |
+ |
for d in 0..dims {
|
|
171 |
+ |
sums[c][d] += p[d];
|
|
172 |
+ |
}
|
|
173 |
+ |
}
|
|
174 |
+ |
for c in 0..k {
|
|
175 |
+ |
if counts[c] > 0 {
|
|
176 |
+ |
for d in 0..dims {
|
|
177 |
+ |
centroids[c][d] = sums[c][d] / counts[c] as f64;
|
|
178 |
+ |
}
|
|
179 |
+ |
}
|
|
180 |
+ |
}
|
|
181 |
+ |
}
|
|
182 |
+ |
|
|
183 |
+ |
// Build clusters + medoids.
|
|
184 |
+ |
let mut members: Vec<Vec<usize>> = vec![Vec::new(); k];
|
|
185 |
+ |
for (i, &c) in assign.iter().enumerate() {
|
|
186 |
+ |
members[c].push(i);
|
|
187 |
+ |
}
|
|
188 |
+ |
let mut clusters = Vec::new();
|
|
189 |
+ |
for (c, idxs) in members.into_iter().enumerate() {
|
|
190 |
+ |
if idxs.is_empty() {
|
|
191 |
+ |
continue;
|
|
192 |
+ |
}
|
|
193 |
+ |
let medoid = *idxs
|
|
194 |
+ |
.iter()
|
|
195 |
+ |
.min_by(|&&a, &&b| {
|
|
196 |
+ |
sq_dist(&points[a], ¢roids[c])
|
|
197 |
+ |
.partial_cmp(&sq_dist(&points[b], ¢roids[c]))
|
|
198 |
+ |
.unwrap()
|
|
199 |
+ |
})
|
|
200 |
+ |
.unwrap();
|
|
201 |
+ |
clusters.push(Cluster {
|
|
202 |
+ |
id: c,
|
|
203 |
+ |
medoid_hash: hashes[medoid].clone(),
|
|
204 |
+ |
member_hashes: idxs.into_iter().map(|i| hashes[i].clone()).collect(),
|
|
205 |
+ |
});
|
|
206 |
+ |
}
|
|
207 |
+ |
|
|
208 |
+ |
Ok(ClusterResult { clusters, feature_version: FEATURE_VERSION })
|
|
209 |
+ |
}
|
|
210 |
+ |
|
|
211 |
+ |
/// Name a cluster: apply `tag` to every member with `source = 'cluster'` provenance.
|
|
212 |
+ |
/// Returns the number of samples that gained the tag.
|
|
213 |
+ |
#[instrument(skip_all)]
|
|
214 |
+ |
pub fn apply_cluster_tag(db: &Database, member_hashes: &[String], tag: &str) -> Result<usize> {
|
|
215 |
+ |
let mut added = 0;
|
|
216 |
+ |
for hash in member_hashes {
|
|
217 |
+ |
if crate::rules::apply_tag_sourced(db, hash, tag, "cluster")? {
|
|
218 |
+ |
added += 1;
|
|
219 |
+ |
}
|
|
220 |
+ |
}
|
|
221 |
+ |
Ok(added)
|
|
222 |
+ |
}
|
|
223 |
+ |
|
|
224 |
+ |
#[cfg(test)]
|
|
225 |
+ |
mod tests {
|
|
226 |
+ |
use super::*;
|
|
227 |
+ |
|
|
228 |
+ |
fn db_with_features(rows: &[(&str, [f64; NUM_FEATURES])]) -> Database {
|
|
229 |
+ |
let db = Database::open_in_memory().unwrap();
|
|
230 |
+ |
for (hash, vec) in rows {
|
|
231 |
+ |
db.conn()
|
|
232 |
+ |
.execute(
|
|
233 |
+ |
"INSERT INTO samples (hash, original_name, file_extension, file_size, import_date, last_modified) \
|
|
234 |
+ |
VALUES (?1, ?1, 'wav', 1, 0, 0)",
|
|
235 |
+ |
[hash],
|
|
236 |
+ |
)
|
|
237 |
+ |
.unwrap();
|
|
238 |
+ |
let json = serde_json::to_string(&vec.to_vec()).unwrap();
|
|
239 |
+ |
db.conn()
|
|
240 |
+ |
.execute(
|
|
241 |
+ |
"INSERT INTO sample_features (hash, feat_version, vector, computed_at) VALUES (?1, ?2, ?3, 0)",
|
|
242 |
+ |
rusqlite::params![hash, FEATURE_VERSION, json],
|
|
243 |
+ |
)
|
|
244 |
+ |
.unwrap();
|
|
245 |
+ |
}
|
|
246 |
+ |
db
|
|
247 |
+ |
}
|
|
248 |
+ |
|
|
249 |
+ |
fn vec_at(base: f64) -> [f64; NUM_FEATURES] {
|
|
250 |
+ |
[base; NUM_FEATURES]
|
|
251 |
+ |
}
|
|
252 |
+ |
|
|
253 |
+ |
#[test]
|
|
254 |
+ |
fn suggest_k_is_sane() {
|
|
255 |
+ |
assert_eq!(suggest_k(0), 0);
|
|
256 |
+ |
assert_eq!(suggest_k(1), 1);
|
|
257 |
+ |
assert!((2..=24).contains(&suggest_k(100)));
|
|
258 |
+ |
assert_eq!(suggest_k(3), 2); // sqrt(1.5) rounds to 1, clamped up to 2
|
|
259 |
+ |
}
|
|
260 |
+ |
|
|
261 |
+ |
#[test]
|
|
262 |
+ |
fn empty_library_yields_no_clusters() {
|
|
263 |
+ |
let db = Database::open_in_memory().unwrap();
|
|
264 |
+ |
let res = cluster_library(&db, 4, 20).unwrap();
|
|
265 |
+ |
assert!(res.clusters.is_empty());
|
|
266 |
+ |
}
|
|
267 |
+ |
|
|
268 |
+ |
#[test]
|
|
269 |
+ |
fn separates_two_obvious_groups() {
|
|
270 |
+ |
// Two tight groups far apart in feature space.
|
|
271 |
+ |
let rows = [
|
|
272 |
+ |
("a1", vec_at(0.0)),
|
|
273 |
+ |
("a2", vec_at(0.1)),
|
|
274 |
+ |
("a3", vec_at(-0.1)),
|
|
275 |
+ |
("b1", vec_at(100.0)),
|
|
276 |
+ |
("b2", vec_at(100.1)),
|
|
277 |
+ |
("b3", vec_at(99.9)),
|
|
278 |
+ |
];
|
|
279 |
+ |
let db = db_with_features(&rows);
|
|
280 |
+ |
let res = cluster_library(&db, 2, 50).unwrap();
|
|
281 |
+ |
assert_eq!(res.clusters.len(), 2);
|
|
282 |
+ |
|
|
283 |
+ |
// Each cluster must be all-a or all-b.
|
|
284 |
+ |
for cluster in &res.clusters {
|
|
285 |
+ |
let all_a = cluster.member_hashes.iter().all(|h| h.starts_with('a'));
|
|
286 |
+ |
let all_b = cluster.member_hashes.iter().all(|h| h.starts_with('b'));
|
|
287 |
+ |
assert!(all_a || all_b, "cluster mixed groups: {:?}", cluster.member_hashes);
|
|
288 |
+ |
assert_eq!(cluster.member_hashes.len(), 3);
|
|
289 |
+ |
}
|
|
290 |
+ |
}
|
|
291 |
+ |
|
|
292 |
+ |
#[test]
|
|
293 |
+ |
fn deterministic_across_runs() {
|
|
294 |
+ |
let rows = [
|
|
295 |
+ |
("a1", vec_at(0.0)),
|
|
296 |
+ |
("b1", vec_at(50.0)),
|
|
297 |
+ |
("c1", vec_at(100.0)),
|
|
298 |
+ |
("a2", vec_at(1.0)),
|
|
299 |
+ |
("b2", vec_at(51.0)),
|
|
300 |
+ |
];
|
|
301 |
+ |
let db = db_with_features(&rows);
|
|
302 |
+ |
let r1 = cluster_library(&db, 3, 50).unwrap();
|
|
303 |
+ |
let r2 = cluster_library(&db, 3, 50).unwrap();
|
|
304 |
+ |
let sig = |r: &ClusterResult| {
|
|
305 |
+ |
let mut v: Vec<Vec<String>> = r
|
|
306 |
+ |
.clusters
|
|
307 |
+ |
.iter()
|
|
308 |
+ |
.map(|c| {
|
|
309 |
+ |
let mut m = c.member_hashes.clone();
|
|
310 |
+ |
m.sort();
|
|
311 |
+ |
m
|
|
312 |
+ |
})
|
|
313 |
+ |
.collect();
|
|
314 |
+ |
v.sort();
|
|
315 |
+ |
v
|
|
316 |
+ |
};
|
|
317 |
+ |
assert_eq!(sig(&r1), sig(&r2));
|
|
318 |
+ |
}
|
|
319 |
+ |
|
|
320 |
+ |
#[test]
|
|
321 |
+ |
fn apply_cluster_tag_writes_sticky_provenance() {
|
|
322 |
+ |
let rows = [("a1", vec_at(0.0)), ("a2", vec_at(0.1))];
|
|
323 |
+ |
let db = db_with_features(&rows);
|
|
324 |
+ |
let members = vec!["a1".to_string(), "a2".to_string()];
|
|
325 |
+ |
assert_eq!(apply_cluster_tag(&db, &members, "kit.my-kicks").unwrap(), 2);
|
|
326 |
+ |
|
|
327 |
+ |
assert!(crate::tags::get_sample_tags(&db, "a1").unwrap().contains(&"kit.my-kicks".to_string()));
|
|
328 |
+ |
let prov = crate::rules::sample_tag_provenance(&db, "a1").unwrap();
|
|
329 |
+ |
assert_eq!(prov[0].1, "cluster");
|
|
330 |
+ |
|
|
331 |
+ |
// Removable as a batch (undo the pass).
|
|
332 |
+ |
let removed = crate::rules::remove_tags_by_source(&db, "cluster").unwrap();
|
|
333 |
+ |
assert_eq!(removed, 2);
|
|
334 |
+ |
assert!(crate::tags::get_sample_tags(&db, "a1").unwrap().is_empty());
|
|
335 |
+ |
}
|
|
336 |
+ |
}
|