adding GPS clustering algorithm using Haversine formula

Author: bdelespierre

src/Algorithm.php

@@ -25,23 +25,15 @@ public function __construct(InitializationSchemeInterface $initScheme)
         $this->initScheme = $initScheme;
     }
 
-    abstract protected function getDistanceBetween(PointInterface $pointA, PointInterface $pointB): float;
-
-    abstract protected function findCentroid(PointCollectionInterface $points): PointInterface;
-
     public function registerIterationCallback(callable $callback): void
     {
         $this->iterationCallbacks[] = $callback;
     }
 
     public function clusterize(PointCollectionInterface $points, int $nbClusters): ClusterCollectionInterface
     {
-        try {
-            // initialize clusters
-            $clusters = $this->initScheme->initializeClusters($points, $nbClusters);
-        } catch (\Exception $e) {
-            throw new \RuntimeException("Cannot initialize clusters", 0, $e);
-        }
+        // initialize clusters
+        $clusters = $this->initScheme->initializeClusters($points, $nbClusters);
 
         // iterate until convergence is reached
         do {

src/ClusterCollection.php

@@ -29,14 +29,17 @@ public function __construct(SpaceInterface $space, array $clusters = [])
         }
     }
 
+    // ------------------------------------------------------------------------
+    // ClusterCollectionInterface
+
     public function contains(ClusterInterface $cluster): bool
     {
         return $this->clusters->contains($cluster);
     }
 
     public function attach(ClusterInterface $cluster): void
     {
-        if ($cluster->getCentroid()->getSpace() !== $this->getSpace()) {
+        if (! $this->getSpace()->isEqualTo($cluster->getSpace())) {
             throw new \InvalidArgumentException(
                 "Cannot add cluster to collection: cluster space is not same as collection space"
             );
@@ -50,6 +53,9 @@ public function detach(ClusterInterface $cluster): void
         $this->clusters->detach($cluster);
     }
 
+    // ------------------------------------------------------------------------
+    // Iterator
+
     public function current()
     {
         return $this->clusters->current();
@@ -75,6 +81,9 @@ public function valid(): bool
         return $this->clusters->valid();
     }
 
+    // ------------------------------------------------------------------------
+    // Countable
+
     public function count(): int
     {
         return count($this->clusters);

src/Concerns/HasDataTrait.php

@@ -0,0 +1,27 @@
+<?php
+
+namespace Kmeans\Concerns;
+
+trait HasDataTrait
+{
+    /**
+     * @var mixed
+     */
+    private $data;
+
+    /**
+     * @return mixed
+     */
+    public function getData()
+    {
+        return $this->data;
+    }
+
+    /**
+     * @param mixed $data
+     */
+    public function setData($data): void
+    {
+        $this->data = $data;
+    }
+}

src/Euclidean/Algorithm.php

@@ -9,14 +9,26 @@
 
 class Algorithm extends BaseAlgorithm
 {
-    protected function getDistanceBetween(PointInterface $pointA, PointInterface $pointB): float
+    public function getDistanceBetween(PointInterface $pointA, PointInterface $pointB): float
     {
+        if (! $pointA instanceof Point || ! $pointB instanceof Point) {
+            throw new \InvalidArgumentException(
+                "Euclidean Algorithm can only calculate distance between euclidean points"
+            );
+        }
+
         return Math::euclideanDist($pointA->getCoordinates(), $pointB->getCoordinates());
     }
 
-    protected function findCentroid(PointCollectionInterface $points): PointInterface
+    public function findCentroid(PointCollectionInterface $points): PointInterface
     {
-        return new Point($points->getSpace(), Math::centroid(
+        if (! $points->getSpace() instanceof Space) {
+            throw new \InvalidArgumentException(
+                "Point collection should consist of Euclidean points"
+            );
+        }
+
+        return $points->getSpace()->makePoint(Math::centroid(
             array_map(fn (PointInterface $point) => $point->getCoordinates(), iterator_to_array($points))
         ));
     }

src/Euclidean/Point.php

@@ -2,32 +2,29 @@
 
 namespace Kmeans\Euclidean;
 
+use Kmeans\Concerns\HasDataTrait;
 use Kmeans\Concerns\HasSpaceTrait;
 use Kmeans\Interfaces\PointInterface;
 use Kmeans\Interfaces\SpaceInterface;
 
 class Point implements PointInterface
 {
     use HasSpaceTrait;
+    use HasDataTrait;
 
     /**
      * @var array<float>
      */
     private array $coordinates;
 
-    /**
-     * @var mixed
-     */
-    private $data;
-
     /**
      * @param array<int, float> $coordinates
      */
     public function __construct(SpaceInterface $space, array $coordinates)
     {
         if (! $space instanceof Space) {
             throw new \LogicException(
-                "An euclidean point must belong to an euclidean space."
+                "An euclidean point must belong to an euclidean space"
             );
         }
 
@@ -40,16 +37,6 @@ public function getCoordinates(): array
         return $this->coordinates;
     }
 
-    public function getData()
-    {
-        return $this->data;
-    }
-
-    public function setData($data): void
-    {
-        $this->data = $data;
-    }
-
     /**
      * @param array<float> $coordinates
      * @return array<float>

src/Euclidean/Space.php

@@ -2,6 +2,7 @@
 
 namespace Kmeans\Euclidean;
 
+use Kmeans\Interfaces\PointInterface;
 use Kmeans\Interfaces\SpaceInterface;
 
 class Space implements SpaceInterface
@@ -32,4 +33,12 @@ public function isEqualTo(SpaceInterface $space): bool
         return $space instanceof self
             && $this->dimensions == $space->dimensions;
     }
+
+    /**
+     * @param array<float> $coordinates
+     */
+    public function makePoint(array $coordinates): PointInterface
+    {
+        return new Point($this, $coordinates);
+    }
 }

src/Gps/Algorithm.php

@@ -9,30 +9,30 @@
 
 class Algorithm extends BaseAlgorithm
 {
-    protected function getDistanceBetween(PointInterface $pointA, PointInterface $pointB): float
+    public function getDistanceBetween(PointInterface $pointA, PointInterface $pointB): float
     {
         if (! $pointA instanceof Point || ! $pointB instanceof Point) {
             throw new \InvalidArgumentException(
-                "Expecting \\Kmeans\\GPS\\Point"
+                "GPS algorithm can only calculate distance from GPS locations"
             );
         }
 
         return Math::haversine($pointA->getCoordinates(), $pointB->getCoordinates());
     }
 
-    protected function findCentroid(PointCollectionInterface $points): PointInterface
+    public function findCentroid(PointCollectionInterface $points): PointInterface
     {
         if (! $points->getSpace() instanceof Space) {
             throw new \InvalidArgumentException(
                 "Point collection should consist of GPS coordinates"
             );
         }
 
-        /** @var array<Point> $points */
-        $points = iterator_to_array($points);
+        /** @var array<Point> $pointsArray */
+        $pointsArray = iterator_to_array($points);
 
-        return new Point(Math::gpsCentroid(
-            array_map(fn (Point $point) => $point->getCoordinates(), $points)
+        return $points->getSpace()->makePoint(Math::gpsCentroid(
+            array_map(fn (Point $point) => $point->getCoordinates(), $pointsArray)
         ));
     }
 }

src/Gps/Point.php

@@ -2,36 +2,40 @@
 
 namespace Kmeans\Gps;
 
-use Kmeans\Euclidean\Point as BasePoint;
+use Kmeans\Concerns\HasDataTrait;
+use Kmeans\Concerns\HasSpaceTrait;
+use Kmeans\Interfaces\PointInterface;
 
 /**
  * @method array{0: float, 1: float} getCoordinates()
  */
-class Point extends BasePoint
+class Point implements PointInterface
 {
-    /**
-     * @param array<float> $coordinates
-     */
-    public function __construct(array $coordinates)
-    {
-        $this->validateCoordinates($coordinates);
+    use HasDataTrait;
+    use HasSpaceTrait;
+
+    private float $lat;
 
-        parent::__construct(new Space(), $coordinates);
+    private float $long;
+
+    public function __construct(float $lat, float $long)
+    {
+        $this->validateCoordinates($lat, $long);
+        $this->setSpace(Space::singleton());
+        $this->lat = $lat;
+        $this->long = $long;
     }
 
     /**
-     * @param array<float> $coordinates
+     * @return array{0: float, 1: float}
      */
-    private function validateCoordinates(array $coordinates): void
+    public function getCoordinates(): array
     {
-        if (count($coordinates) != 2) {
-            throw new \InvalidArgumentException(
-                "Invalid GPS coordinates"
-            );
-        }
-
-        list($lat, $long) = $coordinates;
+        return [$this->lat, $this->long];
+    }
 
+    private function validateCoordinates(float $lat, float $long): void
+    {
         if ($lat < -90 || $lat > 90 || $long < -180 || $long > 180) {
             throw new \InvalidArgumentException(
                 "Invalid GPS coordinates"

src/Gps/Space.php

@@ -2,12 +2,28 @@
 
 namespace Kmeans\Gps;
 
+use Kmeans\Interfaces\PointInterface;
 use Kmeans\Interfaces\SpaceInterface;
 
 class Space implements SpaceInterface
 {
+    public static function singleton(): self
+    {
+        static $space = new self();
+
+        return $space;
+    }
+
     public function isEqualTo(SpaceInterface $other): bool
     {
         return $other instanceof self;
     }
+
+    /**
+     * @param array{0: float, 1: float} $coordinates
+     */
+    public function makePoint(array $coordinates): PointInterface
+    {
+        return new Point(...$coordinates);
+    }
 }

src/Interfaces/AlgorithmInterface.php

@@ -5,4 +5,8 @@
 interface AlgorithmInterface
 {
     public function clusterize(PointCollectionInterface $points, int $nbClusters): ClusterCollectionInterface;
+
+    public function getDistanceBetween(PointInterface $pointA, PointInterface $pointB): float;
+
+    public function findCentroid(PointCollectionInterface $points): PointInterface;
 }