Add xvec (#6)

Co-authored-by: Martin Fleischmann <martin@martinfleischmann.net>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

Author: 3 people

docs/conf.py

@@ -111,7 +111,9 @@
     "numpy": ("https://numpy.org/doc/stable", None),
     "xarray": ("https://docs.xarray.dev/en/stable/", None),
     "rasterix": ("https://rasterix.readthedocs.io/en/latest/", None),
+    "shapely": ("https://shapely.readthedocs.io/en/latest/", None),
     "xvec": ("https://xvec.readthedocs.io/en/stable/", None),
+    "geopandas": ("https://geopandas.readthedocs.io/en/stable/", None),
     "pint-xarray": ("https://pint-xarray.readthedocs.io/en/latest/", None),
     "pint": ("https://pint.readthedocs.io/en/stable/", None),
 }

docs/earth/xvec.md

@@ -1 +1,107 @@
+---
+jupytext:
+  text_representation:
+    format_name: myst
+kernelspec:
+  display_name: Python 3
+  name: python
+---
+
 # xvec: GeometryIndex
+
+````{grid} 12
+```{grid-item}
+:columns: 4
+```{image} https://xvec.readthedocs.io/en/stable/_images/logo.svg
+---
+alt: Alt text
+width: 600px
+align: center
+---
+```
+```{grid-item}
+:columns: 8
+```{seealso}
+Learn more at the [xvec](https://xvec.readthedocs.io) documentation.
+```
+````
+
+## Highlights
+
+```{margin}
+A more general definition is "a data cube that contains geometries as variables (e.g. moving features or time-evolving shapes)".
+```
+
+Xvec's use of custom indexes is exciting because it illustrates how a new Index can help define a new data model --- _vector data cube_: "an n-D array that has either at least one dimension indexed by a 2-D array of vector geometries".
+
+1. Indexing using geometries and associated predicates is supported using `.sel`
+1. A new `.xvec` accessor exposes additional querying functionality.
+1. Exposes complex functionality from other full-featured packages (e.g. shapely) to Xarray.
+
+## Example
+
+First we create a data cube with geometries
+
+```{code-cell}
+---
+tags: [hide-input]
+---
+import geopandas as gpd
+from geodatasets import get_path
+import shapely
+import xarray as xr
+import xvec
+
+xr.set_options(display_expand_indexes=True, display_expand_data=False, display_expand_attrs=False)
+
+counties = gpd.read_file(get_path("geoda.natregimes"))
+
+cube = xr.Dataset(
+    data_vars=dict(
+        population=(["county", "year"], counties[["PO60", "PO70", "PO80", "PO90"]]),
+        unemployment=(["county", "year"], counties[["UE60", "UE70", "UE80", "UE90"]]),
+        divorce=(["county", "year"], counties[["DV60", "DV70", "DV80", "DV90"]]),
+        age=(["county", "year"], counties[["MA60", "MA70", "MA80", "MA90"]]),
+    ),
+    coords=dict(county=counties.geometry, year=[1960, 1970, 1980, 1990]),
+)
+cube
+```
+
+Note how the `county` dimension is associated with a {py:class}`geopandas.GeometryArray`.
+
+### Assigning
+
+Now we can assign a {py:class}`xvec.GeometryIndex` to `county`.
+
+```{code-cell}
+cube = cube.xvec.set_geom_indexes("county")
+cube
+```
+
+### Indexing
+
+#### Geometries as labels
+
+```{code-cell}
+cube.sel(county=cube.county[0])
+```
+
+#### Complex spatial predicates
+
+Lets index to counties that intersect the provided bounding box
+
+```{code-cell}
+box = shapely.box(-97, 45, -99, 48)
+
+subset = cube.sel(county=box, method="intersects")
+subset
+```
+
+Notice how we did that with {py:meth}`xarray.DataArray.sel`?!
+
+```{code-cell}
+f, axes = subset.population.xvec.plot(col="year")
+for ax in axes.flat:
+    ax.plot(*box.boundary.xy, color='w')
+```

requirements.txt

@@ -15,6 +15,8 @@ sphinxext-opengraph[social_cards]
 xdggs
 rasterix
 rioxarray
+geopandas
+geodatasets
 xvec
 git+https://github.com/dcherian/rolodex
 pint-xarray