Create GeoSeries.contains_properly method using point_in_polygon.

[thomcom]

Closes #743
Closes #744

Description

This PR closes the above named issues relating to creating a .contains method and, more importantly, resolving boundary case inconsistency with point_in_polygon.

As it stands the colinearity test I've added to is_point_in_polygon doubles the runtime of brute-force point_in_polygon and has no visible effect on the runtime of quadtree_point_in_polygon.

- Note I need to double check the above benchmark, having set this project down for the last few weeks.

This depends on #750, please do not review the C++ code here until that PR is merged. Please do review the python code.

Benchmark

Benchmark results are in, looks like there's no measurable speed difference between 22.12 pre-boundary exclusion and our current implementation:

(rapids) rapids@compose:~/cuspatial/python/cuspatial/benchmarks$ pytest api/bench_api.py::bench_point_in_polygon
================================================== test session starts ===================================================
platform linux -- Python 3.8.15, pytest-7.2.0, pluggy-1.0.0
benchmark: 4.0.0 (defaults: timer=time.perf_counter disable_gc=False min_rounds=5 min_time=0.000005 max_time=1.0 calibration_precision=10 warmup=False warmup_iterations=100000)
rootdir: /home/tcomer/mnt/NVIDIA/rapids-docker/cuspatial/python/cuspatial/benchmarks, configfile: pytest.ini
plugins: cov-4.0.0, benchmark-4.0.0, cases-3.6.13, xdist-3.0.2, anyio-3.6.2, hypothesis-6.58.1
collected 1 item                                                                                                         

api/bench_api.py .                                                                                                 [100%]


---------------------------------------------- benchmark: 1 tests ---------------------------------------------
Name (time in s)              Min     Max    Mean  StdDev  Median     IQR  Outliers     OPS  Rounds  Iterations
---------------------------------------------------------------------------------------------------------------
bench_point_in_polygon     1.9636  1.9749  1.9678  0.0043  1.9660  0.0045       1;0  0.5082       5           1
---------------------------------------------------------------------------------------------------------------

Legend:
  Outliers: 1 Standard Deviation from Mean; 1.5 IQR (InterQuartile Range) from 1st Quartile and 3rd Quartile.
  OPS: Operations Per Second, computed as 1 / Mean
=================================================== 1 passed in 16.28s ===================================================
(rapids) rapids@compose:~/cuspatial/python/cuspatial/benchmarks$ git status
On branch feature/GeoSeries.contains

vs branch-22.12

(rapids) rapids@compose:~/cuspatial/python/cuspatial/benchmarks$ pytest api/bench_api.py::bench_point_in_polygon
================================== test session starts ===================================
platform linux -- Python 3.8.15, pytest-7.2.0, pluggy-1.0.0
benchmark: 4.0.0 (defaults: timer=time.perf_counter disable_gc=False min_rounds=5 min_time=0.000005 max_time=1.0 calibration_precision=10 warmup=False warmup_iterations=100000)
rootdir: /home/tcomer/mnt/NVIDIA/rapids-docker/cuspatial/python/cuspatial/benchmarks, configfile: pytest.ini
plugins: cov-4.0.0, benchmark-4.0.0, cases-3.6.13, xdist-3.0.2, anyio-3.6.2, hypothesis-6.58.1
collected 1 item                                                                         

api/bench_api.py .                                                                 [100%]


---------------------------------------------- benchmark: 1 tests ---------------------------------------------
Name (time in s)              Min     Max    Mean  StdDev  Median     IQR  Outliers     OPS  Rounds  Iterations
---------------------------------------------------------------------------------------------------------------
bench_point_in_polygon     1.9516  1.9843  1.9730  0.0126  1.9760  0.0127       1;0  0.5068       5           1
---------------------------------------------------------------------------------------------------------------

Legend:
  Outliers: 1 Standard Deviation from Mean; 1.5 IQR (InterQuartile Range) from 1st Quartile and 3rd Quartile.
  OPS: Operations Per Second, computed as 1 / Mean
=================================== 1 passed in 16.61s ===================================
(rapids) rapids@compose:~/cuspatial/python/cuspatial/benchmarks$ git status
On branch benchmark/branch-22.12

Still adding:

• Detailed description of xfail result.
• Self-review existing .contains implementation in python.
• Update .contains docs when necessary.
• Benchmark again and document here.
• Move binops_with_quadtree.py to next branch.
• .contains Examples

Checklist

• I am familiar with the Contributing Guidelines.
• New or existing tests cover these changes.
• The documentation is up to date with these changes.

[isVoid]

Just some more style requests, with an open question in the end. Great work!

[harrism]

Hmmm, shouldn't you be using shapely.contains_properly() for the expected result as we discussed in the meeting?

[thomcom]

The interfaces are not the same. Using shapely.contains_properly(x, y) is a method that takes two Shapely geometries and returns True or False. .contains is a GeoSeries method that operates on self and other. Refactoring these tests to use shapely only is not comparing apples to oranges.

[isVoid]

Naively you can use a for-loop...

expected = pd.Series()
for lhs, rhs in zip(gpdlhs, gpdrhs):
    expected = pd.concat([expected, [shapely.contains_properly(lhs, rhs)])

[harrism]

But comparing cuspatial.contains_properly to geopandas.contains is comparing apples to oranges.

[harrism]

BTW, does this support multipoint in polygon?

[thomcom]

BTW, does this support multipoint in polygon?

yes, there are tests for it.

[harrism]

@thomcom looks like you may have accidentally deleted all the tests (test_contains.py) in 4a651f1?

[harrism]

Just a few other tiny things.

[harrism]

Should this be in a Note section as well?

[thomcom]

@gpucibot merge