Fix directed_hausdorff_distance space_offsets name + documentation(#332)

Fixes #316

Authors:
  - Christopher Harris <xixonia@gmail.com>
  - Christopher Harris <charris@nvidia.com>

Approvers:
  - Mark Harris
  - Paul Taylor
  - Keith Kraus

URL: #332

CHANGELOG.md

@@ -5,6 +5,8 @@
 ## Improvements
 - PR #297 Upgrade to libcu++ on GitHub.
 
+- PR #332 fix directed_hausdorff_distance's space_offsets name + documentation
+
 ## Bug Fixes
 
 # cuSpatial 0.17.0 (Date TBD)

cpp/include/cuspatial/hausdorff.hpp

@@ -71,18 +71,21 @@ namespace cuspatial {
  *
  * @param[in] xs: x component of points
  * @param[in] ys: y component of points
- * @param[in] points_per_space: number of points in each space
+ * @param[in] space_offsets: beginning index of each space, plus the last space's end offset.
  *
  * @returns Hausdorff distances for each pair of spaces
  *
- * @throw cudf::cuda_error if `points_per_space` contains negative values
+ * @throw cudf::cuda_error if `xs` and `ys` lengths differ
+ * @throw cudf::cuda_error if `xs` and `ys` types differ
+ * @throw cudf::cuda_error if `space_offsets` size is less than `xs` and `xy`
+ * @throw cudf::cuda_error if `xs`, `ys`, or `space_offsets` has nulls
  *
  * @note Hausdorff distances are asymmetrical
  */
 std::unique_ptr<cudf::column> directed_hausdorff_distance(
   cudf::column_view const& xs,
   cudf::column_view const& ys,
-  cudf::column_view const& points_per_space,
+  cudf::column_view const& space_offsets,
   rmm::mr::device_memory_resource* mr = rmm::mr::get_current_device_resource());
 
 }  // namespace cuspatial

cpp/src/spatial/hausdorff.cu

@@ -151,20 +151,20 @@ struct hausdorff_functor {
 
 std::unique_ptr<cudf::column> directed_hausdorff_distance(cudf::column_view const& xs,
                                                           cudf::column_view const& ys,
-                                                          cudf::column_view const& points_per_space,
+                                                          cudf::column_view const& space_offsets,
                                                           rmm::mr::device_memory_resource* mr)
 {
   CUSPATIAL_EXPECTS(xs.type() == ys.type(), "Inputs `xs` and `ys` must have same type.");
   CUSPATIAL_EXPECTS(xs.size() == ys.size(), "Inputs `xs` and `ys` must have same length.");
 
-  CUSPATIAL_EXPECTS(not xs.has_nulls() and not ys.has_nulls() and not points_per_space.has_nulls(),
+  CUSPATIAL_EXPECTS(not xs.has_nulls() and not ys.has_nulls() and not space_offsets.has_nulls(),
                     "Inputs must not have nulls.");
 
-  CUSPATIAL_EXPECTS(xs.size() >= points_per_space.size(),
+  CUSPATIAL_EXPECTS(xs.size() >= space_offsets.size(),
                     "At least one point is required for each space");
 
   return cudf::type_dispatcher(
-    xs.type(), detail::hausdorff_functor(), xs, ys, points_per_space, rmm::cuda_stream_default, mr);
+    xs.type(), detail::hausdorff_functor(), xs, ys, space_offsets, rmm::cuda_stream_default, mr);
 }
 
 }  // namespace cuspatial

python/cuspatial/cuspatial/_lib/cpp/hausdorff.pxd

@@ -11,5 +11,5 @@ cdef extern from "cuspatial/hausdorff.hpp" namespace "cuspatial" nogil:
     cdef unique_ptr[column] directed_hausdorff_distance(
         const column_view& xs,
         const column_view& ys,
-        const column_view& points_per_space
+        const column_view& space_offsets
     ) except +

python/cuspatial/cuspatial/_lib/hausdorff.pyx

@@ -12,11 +12,11 @@ from libcpp.memory cimport unique_ptr
 def directed_hausdorff_distance(
     Column xs,
     Column ys,
-    Column points_per_space,
+    Column space_offsets,
 ):
     cdef column_view c_xs = xs.view()
     cdef column_view c_ys = ys.view()
-    cdef column_view c_points_per_space = points_per_space.view()
+    cdef column_view c_shape_offsets = space_offsets.view()
 
     cdef unique_ptr[column] result
 
@@ -25,7 +25,7 @@ def directed_hausdorff_distance(
             directed_cpp_hausdorff_distance(
                 c_xs,
                 c_ys,
-                c_points_per_space,
+                c_shape_offsets,
             )
         )
 

python/cuspatial/cuspatial/core/gis.py

@@ -23,7 +23,7 @@
 from cuspatial.utils.column_utils import normalize_point_columns
 
 
-def directed_hausdorff_distance(xs, ys, points_per_space):
+def directed_hausdorff_distance(xs, ys, space_offsets):
     """Compute the directed Hausdorff distances between all pairs of
     spaces.
 
@@ -33,8 +33,8 @@ def directed_hausdorff_distance(xs, ys, points_per_space):
         column of x-coordinates
     ys
         column of y-coordinates
-    points_per_space
-        number of points in each space
+    space_offsets
+        beginning index of each space, plus the last space's end offset.
 
     Returns
     -------
@@ -74,20 +74,20 @@ def directed_hausdorff_distance(xs, ys, points_per_space):
     >>> result = cuspatial.directed_hausdorff_distance(
             [0, 1, 0, 0], # xs
             [0, 0, 1, 2], # ys
-            [2,    2],    # points_per_space
+            [0, 2, 4],    # space_offsets
         )
     >>> print(result)
              0         1
         0  0.0  1.414214
         1  2.0  0.000000
     """
 
-    num_spaces = len(points_per_space)
+    num_spaces = len(space_offsets)
     if num_spaces == 0:
         return DataFrame()
     xs, ys = normalize_point_columns(as_column(xs), as_column(ys))
     result = cpp_directed_hausdorff_distance(
-        xs, ys, as_column(points_per_space, dtype="int32"),
+        xs, ys, as_column(space_offsets, dtype="int32"),
     )
     result = result.data_array_view
     result = result.reshape(num_spaces, num_spaces)