Merge pull request #8 from emilklindt/3-use-distance-in-k-means-conve…

…rgence-check

Use distance in k means convergence check (#3)

config/marker-clusterer.php

@@ -30,6 +30,20 @@
 
     'default_maximum_iterations' => 10,
 
+    /*
+    |--------------------------------------------------------------------------
+    | Default Maximum Convergence Distance
+    |--------------------------------------------------------------------------
+    |
+    | The maximum distance between iterations to count a cluster as converged,
+    | meaning that no further iteration is necessary. A higher value can provide
+    | better performance, due to the need of doing less iterations. A lower value
+    | will ensure that a cluster has actually converged.
+    |
+    */
+
+    'default_convergence_maximum' => 100,
+
     /*
     |--------------------------------------------------------------------------
     | Default Maximum Samples

src/BaseClusterer.php

@@ -64,6 +64,7 @@ private function mergeDefaultConfig(): void
             'samples' => config('marker-clusterer.default_maximum_samples'),
             'iterations' => config('marker-clusterer.default_maximum_iterations'),
             'distanceFormula' => config('marker-clusterer.default_distance_formula'),
+            'convergenceMaximum' => config('marker-clusterer.default_convergence_maximum'),
         ];
 
         foreach ($map as $key => $value) {

src/Clusterers/KMeansClusterer.php

@@ -34,6 +34,7 @@ public function validateConfig(): bool
         return is_int($this->config->k)
             && is_int($this->config->iterations)
             && is_int($this->config->samples)
+            && is_int($this->config->convergenceMaximum)
             && in_array($this->config->distanceFormula, DistanceFormula::getConstants());
     }
 
@@ -188,7 +189,8 @@ private function hasConverged(Collection $centroids): bool
     {
         return $this->clusters
             ->every(function (Cluster $cluster, int $index) use ($centroids) {
-                return $cluster->centroid == $centroids->get($index);
+                return $this->distanceCalculator->measure($cluster->centroid, $centroids->get($index))
+                    <= $this->config->convergenceMaximum;
             });
     }
 

src/Models/Config.php

@@ -18,6 +18,14 @@ class Config extends DataTransferObject
      */
     public ?int $iterations;
 
+    /**
+     * Maximum movement of a cluster between iterations,
+     * for it to count as convergence
+     *
+     * @see config/marker-clusterer.php
+     */
+    public ?int $convergenceMaximum;
+
     /**
      * Maximum number of clustering samples
      *

tests/Clusterers/KMeansClustererTest.php

@@ -19,6 +19,7 @@ private function getValidConfig()
             'iterations' => 10,
             'samples' => 10,
             'distanceFormula' => DistanceFormula::HAVERSINE,
+            'convergenceMaximum' => 1000,
         ]);
     }