KDTree: added 'queryIterable' method (#217)

Author: gyrdym

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 16.10.0
+- KDTree:
+    - Added `queryIterable` method
+
 ## 16.9.0
 - KDTree:
     - Supported `cosine`, `manhattan` and `hamming` distance

lib/src/retrieval/kd_tree/kd_tree.dart

@@ -120,4 +120,31 @@ abstract class KDTree implements Serializable {
   /// ```
   Iterable<KDTreeNeighbour> query(Vector point, int k,
       [Distance distance = Distance.euclidean]);
+
+  /// Returns [k] nearest neighbours for [point], [point] is [Iterable] unlike
+  /// [query] method where [point] is [Vector] from ml_linalg library
+  ///
+  /// One can use the method in the scenario apart from ml_algo ecosystem,
+  /// since the method doesn't require dependencies such as ml_linalg
+  ///
+  /// The neighbour is represented by an index and the distance between [point]
+  /// and the neighbour itself. The index is a zero-based index of a point in
+  /// the source [points] matrix. Example:
+  ///
+  /// ```dart
+  /// import 'package:ml_dataframe/ml_dataframe.dart';
+  /// import 'package:ml_linalg/vector.dart';
+  ///
+  /// final data = [
+  ///   [21, 34, 22, 11],
+  ///   [11, 33, 44, 55],
+  ///   ...,
+  /// ];
+  /// final kdTree = KDTree.fromIterable(data);
+  /// final neighbours = kdTree.queryIterable([1, 2, 3, 4], 2);
+  ///
+  /// print(neighbours[0].index); // let's say, it outputs `3` which means that the nearest neighbour is kdTree.points[3]
+  /// ```
+  Iterable<KDTreeNeighbour> queryIterable(Iterable<num> point, int k,
+      [Distance distance = Distance.euclidean]);
 }

lib/src/retrieval/kd_tree/kd_tree_impl.dart

@@ -61,6 +61,11 @@ class KDTreeImpl with SerializableMixin implements KDTree {
     return neighbours.toList().reversed;
   }
 
+  @override
+  Iterable<KDTreeNeighbour> queryIterable(Iterable<num> point, int k,
+          [Distance distanceType = Distance.euclidean]) =>
+      query(Vector.fromList(point.toList(), dtype: dtype), k);
+
   void _findKNNRecursively(KDTreeNode? node, Vector point, int k,
       HeapPriorityQueue<KDTreeNeighbour> neighbours, Distance distanceType) {
     if (node == null) {

pubspec.yaml

@@ -1,6 +1,6 @@
 name: ml_algo
 description: Machine learning algorithms, Machine learning models performance evaluation functionality
-version: 16.9.0
+version: 16.10.0
 homepage: https://github.com/gyrdym/ml_algo
 
 environment:

test/retrieval/kd_tree/kd_tree_test.dart

@@ -61,6 +61,19 @@ void main() {
       expect(result, hasLength(3));
     });
 
+    test(
+        'should find the closest neighbours for Iterable [2.79, -9.15, 6.56, -18.59, 13.53], leafSize=1',
+        () {
+      final kdTree = KDTree(DataFrame(data, headerExists: false), leafSize: 1);
+      final sample = [2.79, -9.15, 6.56, -18.59, 13.53];
+      final result = kdTree.queryIterable(sample, 3).toList();
+
+      expect(result[0].index, 12);
+      expect(result[1].index, 4);
+      expect(result[2].index, 18);
+      expect(result, hasLength(3));
+    });
+
     test(
         'should find the closest neighbours for [2.79, -9.15, 6.56, -18.59, 13.53], leafSize=3, splitStrategy=KDTreeSplitStrategy.largestVariance',
         () {
@@ -235,6 +248,32 @@ void main() {
       expect((kdTree as KDTreeImpl).searchIterationCount, 13);
     });
 
+    test(
+        'should find the closest neighbours for [2.79, -9.15, 6.56, -18.59, 13.53], leafSize=3,  manhatten distance',
+        () {
+      final kdTree = KDTree(DataFrame(data, headerExists: false), leafSize: 3);
+      final sample = Vector.fromList([2.79, -9.15, 6.56, -18.59, 13.53]);
+      final result = kdTree.query(sample, 3, Distance.manhattan).toList();
+
+      expect(result[0].index, 12);
+      expect(result[1].index, 4);
+      expect(result[2].index, 13);
+      expect(result, hasLength(3));
+    });
+
+    test(
+        'should find the closest neighbours for [2.79, -9.15, 6.56, -18.59, 13.53], leafSize=1,  manhatten distance',
+        () {
+      final kdTree = KDTree(DataFrame(data, headerExists: false), leafSize: 1);
+      final sample = Vector.fromList([2.79, -9.15, 6.56, -18.59, 13.53]);
+      final result = kdTree.query(sample, 3, Distance.manhattan).toList();
+
+      expect(result[0].index, 12);
+      expect(result[1].index, 4);
+      expect(result[2].index, 13);
+      expect(result, hasLength(3));
+    });
+
     test('should throw an exception if the query point is of invalid length',
         () {
       final kdTree = KDTree(DataFrame(data, headerExists: false), leafSize: 3);