[REVIEW] Improve documentation and return a hausdorff matrix.

CHANGELOG.md

@@ -17,6 +17,7 @@
 - PR #44 Update all demos with Python API
 - PR #45 Improve documentation in haversine and point in polygon
 - PR #61 Point-in-polygon DataFrame output
+- PR #58 Hausdorff distance returns a DataFrame, and better docs.
 
 ## Bug Fixes
 

python/cuspatial/cuspatial/core/gis.py

@@ -25,10 +25,41 @@ def directed_hausdorff_distance(x, y, count):
     ----------
     {params}
 
-    returns
-    DataFrame: 'min', 'max' columns of Hausdorff distances for each polygon
+    Example
+    -------
+    Consider a pair of lines on a grid.
+
+     |
+     o
+    -oxx-
+     |
+    o = [[0, 0], [0, 1]]
+    x = [[1, 0], [2, 0]]
+
+    o[0] is the nearer point in o to x. The distance from o[0] to the farthest
+    point in x = 2.
+    x[0] is the nearer point in x to o. The distance from x[0] to the farthest
+    point in o = 1.414.
+
+        result = cuspatial.directed_hausdorff_distance(
+            cudf.Series([0, 1, 0, 0]),
+            cudf.Series([0, 0, 1, 2]),
+            cudf.Series([2, 2,]),
+        )
+        print(result)
+             0         1
+        0  0.0  1.414214
+        1  2.0  0.000000
+
+    Returns
+    -------
+    DataFrame: The pairwise Hausdorff distance of each set to each other set.
     """
-    return cpp_directed_hausdorff_distance(x, y, count)
+    result = cpp_directed_hausdorff_distance(x, y, count)
+    dim = len(count)
+    return DataFrame.from_gpu_matrix(
+        result.data.to_gpu_array().reshape(dim, dim)
+    )
 
 
 def haversine_distance(p1_lon, p1_lat, p2_lon, p2_lat):

python/cuspatial/cuspatial/tests/test_hausdorff_distance.py

@@ -13,7 +13,7 @@ def test_zeros():
     distance = cuspatial.directed_hausdorff_distance(
         cudf.Series([0.0]), cudf.Series([0.0]), cudf.Series([1])
     )
-    assert cudf.Series(distance)[0] == 0
+    assert_eq(distance, cudf.DataFrame([0.0]))
 
 
 def test_empty_x():
@@ -52,15 +52,14 @@ def test_large():
     cnt = cudf.Series(py_cnt)
     distance = cuspatial.directed_hausdorff_distance(pnt_x, pnt_y, cnt)
 
-    expect = np.array([0, 1, 1, 0])
-    assert np.allclose(distance.data.to_array(), expect)
+    assert_eq(distance, cudf.DataFrame({0: [0, 1.0], 1: [1.0, 0]}))
 
 
 def test_count_one():
     distance = cuspatial.directed_hausdorff_distance(
         cudf.Series([0.0, 0.0]), cudf.Series([0.0, 1.0]), cudf.Series([1, 1])
     )
-    assert_eq(cudf.Series([0, 1.0, 1, 0]), cudf.Series(distance))
+    assert_eq(distance, cudf.DataFrame({0: [0, 1.0], 1: [1.0, 0]}))
 
 
 def test_count_two():
@@ -69,9 +68,8 @@ def test_count_two():
         cudf.Series([0.0, -1.0, 1.0, -1.0]),
         cudf.Series([2, 2]),
     )
-    print(cudf.Series(distance))
     assert_eq(
-        cudf.Series([0.0, 1, 1.4142135623730951, 0]), cudf.Series(distance)
+        distance, cudf.DataFrame({0: [0, 1.4142135623730951], 1: [1, 0.0]})
     )
 
 
@@ -91,20 +89,17 @@ def test_values():
     cnt = cudf.Series(py_cnt)
     distance = cuspatial.directed_hausdorff_distance(pnt_x, pnt_y, cnt)
 
-    expect = np.array(
-        [
-            0,
-            4.12310563,
-            4.0,
-            3.60555128,
-            0.0,
-            1.41421356,
-            4.47213595,
-            1.41421356,
-            0.0,
-        ]
+    print(distance)
+    assert_eq(
+        distance,
+        cudf.DataFrame(
+            {
+                0: [0, 3.605551, 4.472136],
+                1: [4.123106, 0.0, 1.414214],
+                2: [4.0, 1.414214, 0.0],
+            }
+        ),
     )
-    assert np.allclose(distance.data.to_array(), expect)
 
 
 # def test_count_1():