ENH: add covered_by() method for GeoSeries (#1462)

geopandas/_vectorized.py

@@ -625,6 +625,15 @@ def covers(data, other):
         return _binary_predicate("covers", data, other)
 
 
+def covered_by(data, other):
+    if compat.USE_PYGEOS:
+        return _binary_method("covered_by", data, other)
+    else:
+        raise NotImplementedError(
+            "covered_by is only implemented for pygeos, not shapely"
+        )
+
+
 def contains(data, other):
     if compat.USE_PYGEOS:
         return _binary_method("contains", data, other)

geopandas/array.py

@@ -463,6 +463,9 @@ class GeometryArray(ExtensionArray):
     def covers(self, other):
         return self._binary_method("covers", self, other)
 
+    def covered_by(self, other):
+        return self._binary_method("covered_by", self, other)
+
     def contains(self, other):
         return self._binary_method("contains", self, other)
 

geopandas/base.py

@@ -451,6 +451,25 @@ class GeoPandasBase(object):
         """
         return _binary_geo("covers", self, other)
 
+    def covered_by(self, other):
+        """
+        Returns a ``Series`` of ``dtype('bool')`` with value ``True`` for
+        each geometry that is entirely covered by `other`.
+
+        An object A is said to cover another object B if no points of B lie
+        in the exterior of A.
+
+        See
+        https://lin-ear-th-inking.blogspot.com/2007/06/subtleties-of-ogc-covers-spatial.html
+        for reference.
+
+        Parameters
+        ----------
+        other : Geoseries or geometric object
+            The Geoseries (elementwise) or geometric object to check is being covered.
+        """
+        return _binary_geo("covered_by", self, other)
+
     def distance(self, other):
         """Returns a ``Series`` containing the distance to `other`.
 

geopandas/tests/test_geom_methods.py

@@ -12,7 +12,7 @@ from geopandas import GeoDataFrame, GeoSeries
 from geopandas.base import GeoPandasBase
 
 from geopandas.tests.util import assert_geoseries_equal, geom_almost_equals, geom_equals
-from geopandas._compat import PANDAS_GE_024
+from geopandas import _compat as compat
 from pandas.testing import assert_frame_equal, assert_series_equal
 import pytest
 
@@ -422,6 +422,15 @@ class TestGeomMethods:
         exp = Series([False, False])
         assert_series_equal(res, exp)
 
+    @pytest.mark.skipif(
+        not compat.USE_PYGEOS,
+        reason="covered_by is only implemented for pygeos, not shapely",
+    )
+    def test_covered_by(self):
+        res = self.g1.covered_by(self.g1)
+        exp = Series([True, True])
+        assert_series_equal(res, exp)
+
     def test_is_valid(self):
         expected = Series(np.array([True] * len(self.g1)), self.g1.index)
         self._test_unary_real("is_valid", expected, self.g1)
@@ -696,7 +705,7 @@ class TestGeomMethods:
             names=[index_name, None],
         )
         expected_df = expected_df.set_index(expected_index)
-        if not PANDAS_GE_024:
+        if not compat.PANDAS_GE_024:
             expected_df = expected_df[["level_1", "geometry"]]
         assert_frame_equal(test_df, expected_df)