Added Sparse Cosine distance kernel

Author: andrewdalpino

CHANGELOG.md

@@ -10,6 +10,8 @@
     - Rename boosting `estimators` param to `epochs`
     - Neural net-based learners can now train for 0 epochs
     - Rename Labeled `stratify()` to `stratifyByLabel()`
+    - Added Sparse Cosine distance kernel
+    - Cosine distance now optimized for dense vectors
 
 - 1.2.1
     - Refactor stratified methods on Labeled dataset

docs/kernels/distance/cosine.md

@@ -7,9 +7,6 @@ $$
 {\displaystyle {\text{Cosine}}=1 - {\mathbf {A} \cdot \mathbf {B}  \over \|\mathbf {A} \|\|\mathbf {B} \|}=1 - {\frac {\sum \limits _{i=1}^{n}{A_{i}B_{i}}}{{\sqrt {\sum \limits _{i=1}^{n}{A_{i}^{2}}}}{\sqrt {\sum \limits _{i=1}^{n}{B_{i}^{2}}}}}}}
 $$
 
-!!! note
-    This distance kernel is optimized for sparse (mainly zeros) coordinate vectors.
-
 **Data Type Compatibility:** Continuous
 
 ## Parameters

docs/kernels/distance/sparse-cosine.md

@@ -0,0 +1,16 @@
+<span style="float:right;"><a href="https://github.com/RubixML/ML/blob/master/src/Kernels/Distance/SparseCosine.php">[source]</a></span>
+
+# Sparse Cosine
+A version of the Cosine distance kernel that is specifically optimized for computing sparse vectors.
+
+**Data Type Compatibility:** Continuous
+
+## Parameters
+This kernel does not have any parameters.
+
+## Example
+```php
+use Rubix\ML\Kernels\Distance\SparseCosine;
+
+$kernel = new SparseCosine();
+```

mkdocs.yml

@@ -204,6 +204,7 @@ nav:
         - Manhattan: kernels/distance/manhattan.md
         - Minkowski: kernels/distance/minkowski.md
         - Safe Euclidean: kernels/distance/safe-euclidean.md
+        - Sparse Cosine: kernels/distance/sparse-cosine.md
       - SVM:
         - Linear: kernels/svm/linear.md
         - Polynomial: kernels/svm/polynomial.md

src/Kernels/Distance/Cosine.php

@@ -16,8 +16,6 @@
  * satisfy the positive semi-definite condition, therefore the Cosine distance
  * is a number between 0 and 2.
  *
- * > **Note:** This distance kernel is optimized for sparse (mainly zeros) coordinate vectors.
- *
  * @category    Machine Learning
  * @package     Rubix/ML
  * @author      Andrew DalPino
@@ -54,20 +52,10 @@ public function compute(array $a, array $b) : float
         foreach ($a as $i => $valueA) {
             $valueB = $b[$i];
 
-            if ($valueA != 0 and $valueB != 0) {
-                $sigma += $valueA * $valueB;
-
-                $ssA += $valueA ** 2;
-                $ssB += $valueB ** 2;
-            } else {
-                if ($valueA != 0) {
-                    $ssA += $valueA ** 2;
-                }
+            $sigma += $valueA * $valueB;
 
-                if ($valueB != 0) {
-                    $ssB += $valueB ** 2;
-                }
-            }
+            $ssA += $valueA ** 2;
+            $ssB += $valueB ** 2;
         }
 
         if ($ssA === 0.0 and $ssB === 0.0) {

src/Kernels/Distance/SparseCosine.php

@@ -0,0 +1,86 @@
+<?php
+
+namespace Rubix\ML\Kernels\Distance;
+
+use Rubix\ML\DataType;
+
+/**
+ * Sparse Cosine
+ *
+ * A version of the Cosine distance kernel that is specifically optimized for computing sparse vectors.
+ *
+ * @category    Machine Learning
+ * @package     Rubix/ML
+ * @author      Andrew DalPino
+ */
+class SparseCosine implements Distance
+{
+    /**
+     * Return the data types that this kernel is compatible with.
+     *
+     * @internal
+     *
+     * @return list<\Rubix\ML\DataType>
+     */
+    public function compatibility() : array
+    {
+        return [
+            DataType::continuous(),
+        ];
+    }
+
+    /**
+     * Compute the distance between two vectors.
+     *
+     * @internal
+     *
+     * @param list<int|float> $a
+     * @param list<int|float> $b
+     * @return float
+     */
+    public function compute(array $a, array $b) : float
+    {
+        $sigma = $ssA = $ssB = 0.0;
+
+        foreach ($a as $i => $valueA) {
+            $valueB = $b[$i];
+
+            if ($valueA != 0 and $valueB != 0) {
+                $sigma += $valueA * $valueB;
+
+                $ssA += $valueA ** 2;
+                $ssB += $valueB ** 2;
+            } else {
+                if ($valueA != 0) {
+                    $ssA += $valueA ** 2;
+                }
+
+                if ($valueB != 0) {
+                    $ssB += $valueB ** 2;
+                }
+            }
+        }
+
+        if ($ssA === 0.0 and $ssB === 0.0) {
+            return 0.0;
+        }
+
+        if ($ssA === 0.0 or $ssB === 0.0) {
+            return 2.0;
+        }
+
+        return 1.0 - ($sigma / sqrt($ssA * $ssB));
+    }
+
+    /**
+     * Return the string representation of the object.
+     *
+     * @internal
+     *
+     * @return string
+     */
+    public function __toString() : string
+    {
+        return 'Sparse Cosine';
+    }
+}

tests/Kernels/Distance/SparseCosineTest.php

@@ -0,0 +1,89 @@
+<?php
+
+namespace Rubix\ML\Tests\Kernels\Distance;
+
+use Rubix\ML\Kernels\Distance\SparseCosine;
+use Rubix\ML\Kernels\Distance\Distance;
+use PHPUnit\Framework\TestCase;
+use Generator;
+
+/**
+ * @group Distances
+ * @covers \Rubix\ML\Kernels\Distance\Cosine
+ */
+class SparseCosineTest extends TestCase
+{
+    /**
+     * @var \Rubix\ML\Kernels\Distance\SparseCosine
+     */
+    protected $kernel;
+
+    /**
+     * @before
+     */
+    protected function setUp() : void
+    {
+        $this->kernel = new SparseCosine();
+    }
+
+    /**
+     * @test
+     */
+    public function build() : void
+    {
+        $this->assertInstanceOf(SparseCosine::class, $this->kernel);
+        $this->assertInstanceOf(Distance::class, $this->kernel);
+    }
+
+    /**
+     * @test
+     * @dataProvider computeProvider
+     *
+     * @param (int|float)[] $a
+     * @param (int|float)[] $b
+     * @param float $expected
+     */
+    public function compute(array $a, array $b, float $expected) : void
+    {
+        $distance = $this->kernel->compute($a, $b);
+
+        $this->assertGreaterThanOrEqual(0.0, $distance);
+        $this->assertEquals($expected, $distance);
+    }
+
+    /**
+     * @return \Generator<array>
+     */
+    public function computeProvider() : Generator
+    {
+        yield [
+            [2, 1, 4, 0], [-2, 1, 8, -2],
+            0.2593263058537443,
+        ];
+
+        yield [
+            [7.4, -2.5], [0.01, -1],
+            0.6704765571747832,
+        ];
+
+        yield [
+            [1000, -2000, 3000], [1000, -2000, 3000],
+            0.0,
+        ];
+
+        yield [
+            [1000, -2000, 3000], [-1000, 2000, -3000],
+            2.0,
+        ];
+
+        yield [
+            [1.0, 2.0, 3.0], [0.0, 0.0, 0.0],
+            2.0,
+        ];
+
+        yield [
+            [0.0, 0.0, 0.0], [0.0, 0.0, 0.0],
+            0.0,
+        ];
+    }
+}