feat: add basic geopandas functionality (#962)

* feat: add basic geopandas functionality

* update examples for geoseries

* feat: add Series.geo helper to convert Series to a GeoSeries

* fix cirucular import

* Added a constructor

* add documentation for geoseries

* remove GeoSeries.x and GeoSeries.y temporarily

---------

Co-authored-by: Arwa <[email protected]>

Author: rey-esp

bigframes/geopandas/__init__.py

@@ -0,0 +1,17 @@
+# Copyright 2023 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from bigframes.geopandas.geoseries import GeoSeries
+
+__all__ = ["GeoSeries"]

bigframes/geopandas/geoseries.py

@@ -0,0 +1,28 @@
+# Copyright 2024 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+from __future__ import annotations
+
+import bigframes_vendored.geopandas.geoseries as vendored_geoseries
+import geopandas.array  # type: ignore
+
+import bigframes.series
+
+
+class GeoSeries(vendored_geoseries.GeoSeries, bigframes.series.Series):
+    __doc__ = vendored_geoseries.GeoSeries.__doc__
+
+    def __init__(self, data=None, index=None, **kwargs):
+        super().__init__(
+            data=data, index=index, dtype=geopandas.array.GeometryDtype(), **kwargs
+        )

bigframes/series.py

@@ -60,6 +60,9 @@
 import bigframes.operations.strings as strings
 import bigframes.operations.structs as structs
 
+if typing.TYPE_CHECKING:
+    import bigframes.geopandas.geoseries
+
 LevelType = typing.Union[str, int]
 LevelsType = typing.Union[LevelType, typing.Sequence[LevelType]]
 
@@ -91,6 +94,20 @@ def dtype(self):
     def dtypes(self):
         return self._dtype
 
+    @property
+    def geo(self) -> bigframes.geopandas.geoseries.GeoSeries:
+        """
+        Accessor object for geography properties of the Series values.
+
+        Returns:
+            bigframes.geopandas.geoseries.GeoSeries:
+                An accessor containing geography methods.
+
+        """
+        import bigframes.geopandas.geoseries
+
+        return bigframes.geopandas.geoseries.GeoSeries(self)
+
     @property
     @validations.requires_index
     def loc(self) -> bigframes.core.indexers.LocSeriesIndexer:

docs/reference/bigframes.geopandas/geoseries.rst

@@ -0,0 +1,17 @@
+
+=========
+GeoSeries
+=========
+
+.. contents:: Table of Contents
+   :depth: 2
+   :local:
+   :backlinks: none
+
+Series
+------
+
+.. autoclass:: bigframes.geopandas.geoseries.GeoSeries
+    :members:
+    :inherited-members:
+    :undoc-members:

docs/reference/bigframes.geopandas/index.rst

@@ -0,0 +1,9 @@
+
+===============================
+BigQuery DataFrames (geopandas)
+===============================
+
+.. toctree::
+    :maxdepth: 2
+
+    geoseries

docs/reference/index.rst

@@ -8,7 +8,8 @@ packages.
     :maxdepth: 2
 
     bigframes/index
-    bigframes.pandas/index
-    bigframes.ml/index
     bigframes.bigquery/index
+    bigframes.geopandas/index
+    bigframes.ml/index
+    bigframes.pandas/index
     bigframes.streaming/index

third_party/bigframes_vendored/geopandas/LICENSE.txt

@@ -0,0 +1,25 @@
+Copyright (c) 2013-2022, GeoPandas developers.
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are met:
+
+ * Redistributions of source code must retain the above copyright notice, this
+   list of conditions and the following disclaimer.
+ * Redistributions in binary form must reproduce the above copyright notice,
+   this list of conditions and the following disclaimer in the documentation
+   and/or other materials provided with the distribution.
+ * Neither the name of GeoPandas nor the names of its contributors may
+   be used to endorse or promote products derived from this software without
+   specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE FOR
+ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
+LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
+SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

third_party/bigframes_vendored/geopandas/geoseries.py

@@ -0,0 +1,30 @@
+# contains code from https://github.com/geopandas/geopandas/blob/main/geopandas/geoseries.py
+from __future__ import annotations
+
+
+class GeoSeries:
+    """
+    A Series object designed to store geometry objects.
+
+    **Examples:**
+
+        >>> import bigframes.geopandas
+        >>> import bigframes.pandas as bpd
+        >>> bpd.options.display.progress_bar = None
+        >>> from shapely.geometry import Point
+        >>> s = bigframes.geopandas.GeoSeries([Point(1, 1), Point(2, 2), Point(3, 3)])
+        >>> s
+        0    POINT (1 1)
+        1    POINT (2 2)
+        2    POINT (3 3)
+        dtype: geometry
+
+    Args:
+        data (array-like, dict, scalar value, bigframes.pandas.Series):
+            The geometries to store in the GeoSeries.
+        index (array-like, pandas.Index, bigframes.pandas.Index):
+            The index for the GeoSeries.
+        kwargs (dict):
+            Additional arguments passed to the Series constructor,
+            e.g. ``name``.
+    """