fix docs

h3ronpy/CHANGES.rst

@@ -12,6 +12,9 @@ Versioning <https://semver.org/spec/v2.0.0.html>`__.
 Unreleased
 ----------
 
+- *Breaking*: Remove lots the dataframe-library specific functions and instead work with arrow arrays and record-batches directly using the `Arrow PyCapsule interface <https://arrow.apache.org/docs/format/CDataInterface/PyCapsuleInterface.html>`_.
+  The core and polars parts of this library are no longer depending on `pyarrow` - instead the `lightweight 'arro3' library <https://github.com/kylebarron/arro3>`_ is used. The pandas-parts still require `pyarrow` which needs the be installed manually.
+- Support for numpy 2.
 - Upgrade to h3o 0.7.
 - Release the GIL more often to allow other threads to run.
 - The minimum supported python version is now 3.9.

h3ronpy/docs/source/api/index.rst

@@ -4,6 +4,5 @@ API documentation
 .. toctree::
 
    core
-   arrow
    pandas
    polars

h3ronpy/docs/source/api/polars.rst

@@ -86,18 +86,3 @@ All methods of the ``H3SeriesShortcuts`` class are available in the ``h3`` objec
 .. autoclass:: h3ronpy.polars.H3SeriesShortcuts
    :members:
    :undoc-members:
-
-Raster module
--------------
-
-.. automodule:: h3ronpy.polars.raster
-   :members:
-   :undoc-members:
-
-
-Vector module
--------------
-
-.. automodule:: h3ronpy.polars.vector
-   :members:
-   :undoc-members:

h3ronpy/docs/source/usage/grid.rst

@@ -8,6 +8,7 @@ Create a few test cells to the examples on this page:
     import numpy as np
     import h3.api.numpy_int as h3
     import pandas as pd
+    import pyarrow as pa
 
     from h3ronpy.pandas.vector import cells_dataframe_to_geodataframe
     from h3ronpy import DEFAULT_CELL_COLUMN_NAME
@@ -21,37 +22,37 @@ Create a few test cells to the examples on this page:
     )
 
 
-Grid-disks with :py:func:`h3ronpy.pandas.grid_disk`
+Grid-disks with :py:func:`h3ronpy.grid_disk`
 ---------------------------------------------------
 
 .. jupyter-execute::
 
-    from h3ronpy.pandas import grid_disk
+    from h3ronpy import grid_disk
 
     cells_dataframe_to_geodataframe(
         pd.DataFrame({
-            DEFAULT_CELL_COLUMN_NAME: grid_disk(cells, 9, flatten=True).unique()}
+            DEFAULT_CELL_COLUMN_NAME: pa.array(grid_disk(cells, 9, flatten=True)).to_pandas()}
         )
     ).plot()
 
 
-Grid-disk aggregates with :py:func:`h3ronpy.pandas.grid_disk_aggregate_k`
+Grid-disk aggregates with :py:func:`h3ronpy.grid_disk_aggregate_k`
 -------------------------------------------------------------------------
 
-This builds ontop of :py:func:`h3ronpy.pandas.grid_disk_distances` while directly
+This builds ontop of :py:func:`h3ronpy.grid_disk_distances` while directly
 performing simple aggregations to avoid returning potentially very large dataframes.
 
 .. jupyter-execute::
 
-    from h3ronpy.pandas import grid_disk_aggregate_k
+    from h3ronpy import grid_disk_aggregate_k
 
     cells_dataframe_to_geodataframe(
-        grid_disk_aggregate_k(cells, 9, "min")
+        pa.table(grid_disk_aggregate_k(cells, 9, "min")).to_pandas()
     ).plot(column="k", legend=True, legend_kwds={"label": "k", "orientation": "horizontal"},)
 
 
 .. jupyter-execute::
 
     cells_dataframe_to_geodataframe(
-        grid_disk_aggregate_k(cells, 9, "max")
+        pa.table(grid_disk_aggregate_k(cells, 9, "max")).to_pandas()
     ).plot(column="k", legend=True, legend_kwds={"label": "k", "orientation": "horizontal"},)

h3ronpy/docs/source/usage/raster.rst

@@ -66,11 +66,11 @@ Do some image processing - like this messy extraction of a vegetation mask here:
 Convert the raster numpy array to H3
 ------------------------------------
 
-Find the closest H3 resolution to use. See also the docstrings of the used functions and of the `h3ronpy.pandas.raster` module.
+Find the closest H3 resolution to use. See also the docstrings of the used functions and of the `h3ronpy.raster` module.
 
 .. jupyter-execute::
 
-    from h3ronpy.pandas.raster import nearest_h3_resolution
+    from h3ronpy.raster import nearest_h3_resolution
 
     h3_res = nearest_h3_resolution(vegetation.shape, src.transform, search_mode="smaller_than_pixel")
     print(f"Using H3 resolution {h3_res}")
@@ -100,15 +100,16 @@ Converting H3 cells to raster
 .. jupyter-execute::
 
     import pandas as pd
+    import pyarrow as pa
     from h3ronpy.pandas.raster import rasterize_cells
     from rasterio.plot import show
 
     df = pd.read_parquet(project_root / "data/population-841fa8bffffffff.parquet")
     size = 1000
     nodata_value = -1
     array, transform = rasterize_cells(
-        df["h3index"],
-        df["pop_general"].astype("int32"),
+        pa.array(df["h3index"]),
+        pa.array(df["pop_general"].astype("int32")),
         size,
         nodata_value=nodata_value
     )

h3ronpy/docs/source/usage/vector.rst

@@ -91,7 +91,7 @@ It is also possible to convert single `shapely` geometries or any other type pro
 
 .. jupyter-execute::
 
-    from h3ronpy.pandas.vector import geometry_to_cells
+    from h3ronpy.vector import geometry_to_cells
 
     namibia_geom = namibia["geometry"].iloc[0]
     print(namibia_geom)

h3ronpy/python/h3ronpy/pandas/vector.py

@@ -1,11 +1,59 @@
+from functools import wraps
+from typing import Optional
+
 import geopandas as gpd
 import pandas as pd
 import pyarrow as pa
 import pyarrow.compute as pc
-import shapely
 
+import h3ronpy.vector as _hv
 from h3ronpy import DEFAULT_CELL_COLUMN_NAME, H3_CRS, ContainmentMode
-from h3ronpy.vector import cells_to_wkb_polygons, wkb_to_cells
+
+
+def _geoseries_from_wkb(func, doc: Optional[str] = None, name: Optional[str] = None):
+    @wraps(func)
+    def wrapper(*args, **kw):
+        return gpd.GeoSeries.from_wkb(func(*args, **kw), crs=H3_CRS)
+
+    # create a copy to avoid modifying the dict of the wrapped function
+    wrapper.__annotations__ = dict(**wrapper.__annotations__)
+    wrapper.__annotations__["return"] = gpd.GeoSeries
+    if doc is not None:
+        wrapper.__doc__ = doc
+    if name is not None:
+        wrapper.__name__ = name
+
+    return wrapper
+
+
+cells_to_polygons = _geoseries_from_wkb(
+    _hv.cells_to_wkb_polygons,
+    doc="Create a geoseries containing the polygon geometries of a cell array",
+    name="cells_to_polygons",
+)
+cells_to_points = _geoseries_from_wkb(
+    _hv.cells_to_wkb_points,
+    doc="Create a geoseries containing the centroid point geometries of a cell array",
+    name="cells_to_points",
+)
+vertexes_to_points = _geoseries_from_wkb(
+    _hv.vertexes_to_wkb_points,
+    doc="Create a geoseries containing the point geometries of a vertex array",
+    name="vertexes_to_points",
+)
+directededges_to_linestrings = _geoseries_from_wkb(
+    _hv.directededges_to_wkb_linestrings,
+    doc="Create a geoseries containing the linestrings geometries of a directededge array",
+    name="directededges_to_linestrings",
+)
+
+
+@wraps(_hv.wkb_to_cells)
+def geoseries_to_cells(geoseries: gpd.GeoSeries, *args, **kw):
+    return pa.array(_hv.wkb_to_cells(geoseries.to_wkb(), *args, **kw)).to_pandas()
+
+
+geoseries_to_cells.__name__ = "geoseries_to_cells"
 
 
 def cells_dataframe_to_geodataframe(
@@ -18,9 +66,9 @@ def cells_dataframe_to_geodataframe(
     :param cell_column_name: name of the column containing the h3 indexes
     :return: GeoDataFrame
     """
-    wkb_polygons = cells_to_wkb_polygons(df[cell_column_name])
-    geometry = shapely.from_wkb(wkb_polygons)
-    return gpd.GeoDataFrame(df, geometry=geometry, crs=H3_CRS)
+    # wkb_polygons = uv.cells_to_wkb_polygons(df[cell_column_name])
+    # geometry = shapely.from_wkb(wkb_polygons)
+    return gpd.GeoDataFrame(df, geometry=cells_to_polygons(df[cell_column_name]), crs=H3_CRS)
 
 
 def geodataframe_to_cells(
@@ -48,7 +96,7 @@ def geodataframe_to_cells(
     :param cell_column_name:
     :return:
     """
-    cells = wkb_to_cells(
+    cells = _hv.wkb_to_cells(
         gdf.geometry.to_wkb(),
         resolution,
         containment_mode=containment_mode,
@@ -90,4 +138,8 @@ def _explode_table_include_null(table: pa.Table, column: str) -> pa.Table:
 __all__ = [
     cells_dataframe_to_geodataframe.__name__,
     geodataframe_to_cells.__name__,
+    cells_to_polygons.__name__,
+    cells_to_points.__name__,
+    vertexes_to_points.__name__,
+    directededges_to_linestrings.__name__,
 ]