YingYang, release candidate

Author: Andrey Oskin

docs/src/index.md

@@ -56,11 +56,14 @@ git checkout experimental
 - [X] Implementation of [Hamerly implementation](https://www.researchgate.net/publication/220906984_Making_k-means_Even_Faster).
 - [X] Interface for inclusion in Alan Turing Institute's [MLJModels](https://github.com/alan-turing-institute/MLJModels.jl#who-is-this-repo-for).
 - [X] Full Implementation of Triangle inequality based on [Elkan - 2003 Using the Triangle Inequality to Accelerate K-Means"](https://www.aaai.org/Papers/ICML/2003/ICML03-022.pdf).
+- [X] Implementation of [Yinyang K-Means: A Drop-In Replacement of the Classic K-Means
+with Consistent Speedup](https://www.microsoft.com/en-us/research/wp-content/uploads/2016/02/ding15.pdf)
 - [ ] Implementation of [Geometric methods to accelerate k-means algorithm](http://cs.baylor.edu/~hamerly/papers/sdm2016_rysavy_hamerly.pdf).
 - [ ] Support for other distance metrics supported by [Distances.jl](https://github.com/JuliaStats/Distances.jl#supported-distances).
 - [ ] Native support for tabular data inputs outside of MLJModels' interface.
 - [ ] Refactoring and finalizaiton of API desgin.
 - [ ] GPU support.
+- [ ] Distributed calculations support.
 - [ ] Implementation of other K-Means algorithm variants based on recent literature.
 - [ ] Optimization of code base.
 - [ ] Improved Documentation
@@ -103,6 +106,7 @@ r.converged             # whether the procedure converged
 - [Lloyd()](https://cs.nyu.edu/~roweis/csc2515-2006/readings/lloyd57.pdf)
 - [Hamerly()](https://www.researchgate.net/publication/220906984_Making_k-means_Even_Faster)
 - [Elkan()](https://www.aaai.org/Papers/ICML/2003/ICML03-022.pdf)
+- [YingYang()](https://www.microsoft.com/en-us/research/wp-content/uploads/2016/02/ding15.pdf)
 - [Geometric()](http://cs.baylor.edu/~hamerly/papers/sdm2016_rysavy_hamerly.pdf) - (Coming soon)
 - [MiniBatch()](https://www.eecs.tufts.edu/~dsculley/papers/fastkmeans.pdf) - (Coming soon)
 
@@ -174,8 +178,10 @@ ________________________________________________________________________________
 
 - 0.1.0 Initial release.
 - 0.1.1 Added interface for MLJ.
-- 0.1.2 Added Elkan algorithm.
+- 0.1.2 Added `Elkan` algorithm.
 - 0.1.3 Faster & optimized execution.
+- 0.1.4 Bug fixes
+- 0.1.5 Added `YingYang` algorithm.
 
 ## Contributing
 

src/yingyang.jl

@@ -5,22 +5,30 @@ YingYang algorithm implementation, based on "Yufei Ding et al. 2015. Yinyang K-M
 Replacement of the Classic K-Means with Consistent Speedup. Proceedings of the 32nd International
 Conference on Machine Learning, ICML 2015, Lille, France, 6-11 July 2015"
 
+Generally it outperform `Hamerly` algorithm and has roughly the same time as `Elkan`
+algorithm with much lower memory consumption.
+
 It can be used directly in `kmeans` function
 
 ```julia
 X = rand(30, 100_000)   # 100_000 random points in 30 dimensions
 
 kmeans(YingYang(), X, 3) # 3 clusters, YingYang algorithm
 ```
+
+`YingYang` supports following arguments:
+`auto`: `Bool`, indicates whether to perform automated or manual grouping
+`group_size`: `Int`, estimation of average number of clusters per group. Lower numbers
+corresponds to higher calculation speed and higher memory consumption and vice versa.
 """
 struct YingYang <: AbstractKMeansAlg
     auto::Bool
-    divider::Int
+    group_size::Int
 end
 
 YingYang() = YingYang(true, 7)
 YingYang(auto::Bool) = YingYang(auto, 7)
-YingYang(divider::Int) = YingYang(true, divider)
+YingYang(group_size::Int) = YingYang(true, group_size)
 
 function kmeans!(alg::YingYang, containers, X, k;
                 n_threads = Threads.nthreads(),
@@ -98,7 +106,7 @@ function create_containers(alg::YingYang, k, nrow, ncol, n_threads)
     end
 
     if alg.auto
-        t = k ÷ alg.divider
+        t = k ÷ alg.group_size
         t = t < 1 ? 1 : t
     else
         t = 1

test/test00_yingyang.jl

@@ -0,0 +1,113 @@
+module TestYingYang
+
+using ParallelKMeans
+using Test
+using Random
+
+@testset "basic kmeans yingyang" begin
+    X = [1. 2. 4.;]
+    res = kmeans(YingYang(false), X, 1; n_threads = 1, tol = 1e-6, verbose = false)
+    @test res.assignments == [1, 1, 1]
+    @test res.centers[1] ≈ 2.3333333333333335
+    @test res.totalcost ≈ 4.666666666666666
+    @test res.converged
+
+    res = kmeans(YingYang(false), X, 2; n_threads = 1, init = [1.0 4.0], tol = 1e-6, verbose = false)
+    @test res.assignments == [1, 1, 2]
+    @test res.centers ≈ [1.5 4.0]
+    @test res.totalcost ≈ 0.5
+    @test res.converged
+end
+
+@testset "yingyang no convergence yield last result" begin
+    X = [1. 2. 4.;]
+    res = kmeans(YingYang(false), X, 2; n_threads = 1, init = [1.0 4.0], tol = 1e-6, max_iters = 1, verbose = false)
+    @test !res.converged
+    @test res.totalcost ≈ 0.5
+end
+
+@testset "yingyang singlethread linear separation" begin
+    Random.seed!(2020)
+
+    X = rand(3, 100)
+    res = kmeans(YingYang(false), X, 3; n_threads = 1, tol = 1e-10, max_iters = 10, verbose = false)
+
+    @test res.totalcost ≈ 14.16198704459199
+    @test !res.converged
+    @test res.iterations == 10
+end
+
+@testset "yingyang multithread linear separation quasi two threads" begin
+    Random.seed!(2020)
+
+    X = rand(3, 100)
+    res = kmeans(YingYang(false), X, 3; n_threads = 2, tol = 1e-6, verbose = false)
+
+    @test res.totalcost ≈ 14.16198704459199
+    @test res.converged
+end
+
+@testset "yingyang different modes" begin
+    Random.seed!(2020)
+    X = rand(3, 100)
+    init = ParallelKMeans.smart_init(X, 20).centroids
+    baseline = kmeans(Lloyd(), X, 20, init = init, tol = 1e-10, n_threads = 1, verbose = false, max_iters = 1000)
+
+    res = kmeans(YingYang(false), X, 20, init = init, tol = 1e-10, n_threads = 1, verbose = false, max_iters = 1000)
+    @test res.converged
+    @test res.totalcost ≈ baseline.totalcost
+    @test res.assignments == baseline.assignments
+    @test res.centers ≈ baseline.centers
+    @test res.iterations == baseline.iterations
+
+    res = kmeans(YingYang(), X, 20, init = init, tol = 1e-10, n_threads = 1, verbose = false, max_iters = 1000)
+    @test res.converged
+    @test res.totalcost ≈ baseline.totalcost
+    @test res.assignments == baseline.assignments
+    @test res.centers ≈ baseline.centers
+    @test res.iterations == baseline.iterations
+
+    res = kmeans(YingYang(10), X, 20, init = init, tol = 1e-10, n_threads = 1, verbose = false, max_iters = 1000)
+    @test res.converged
+    @test res.totalcost ≈ baseline.totalcost
+    @test res.assignments == baseline.assignments
+    @test res.centers ≈ baseline.centers
+    @test res.iterations == baseline.iterations
+
+    res = kmeans(YingYang(7), X, 20, init = init, tol = 1e-10, n_threads = 1, verbose = false, max_iters = 1000)
+    @test res.converged
+    @test res.totalcost ≈ baseline.totalcost
+    @test res.assignments == baseline.assignments
+    @test res.centers ≈ baseline.centers
+    @test res.iterations == baseline.iterations
+
+    res = kmeans(YingYang(false), X, 20, init = init, tol = 1e-10, n_threads = 2, verbose = false, max_iters = 1000)
+    @test res.converged
+    @test res.totalcost ≈ baseline.totalcost
+    @test res.assignments == baseline.assignments
+    @test res.centers ≈ baseline.centers
+    @test res.iterations == baseline.iterations
+
+    res = kmeans(YingYang(), X, 20, init = init, tol = 1e-10, n_threads = 2, verbose = false, max_iters = 1000)
+    @test res.converged
+    @test res.totalcost ≈ baseline.totalcost
+    @test res.assignments == baseline.assignments
+    @test res.centers ≈ baseline.centers
+    @test res.iterations == baseline.iterations
+
+    res = kmeans(YingYang(10), X, 20, init = init, tol = 1e-10, n_threads = 2, verbose = false, max_iters = 1000)
+    @test res.converged
+    @test res.totalcost ≈ baseline.totalcost
+    @test res.assignments == baseline.assignments
+    @test res.centers ≈ baseline.centers
+    @test res.iterations == baseline.iterations
+
+    res = kmeans(YingYang(7), X, 20, init = init, tol = 1e-10, n_threads = 2, verbose = false, max_iters = 1000)
+    @test res.converged
+    @test res.totalcost ≈ baseline.totalcost
+    @test res.assignments == baseline.assignments
+    @test res.centers ≈ baseline.centers
+    @test res.iterations == baseline.iterations
+end
+
+end # module