Add xdggs (#8)

* move xdggs to earth sciences

* setup

* describe the xdggs index

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* point to the new location in `index.md`

* show the H3 grid

* visualize the result

* mention healpix and h3 as examples for DGGS

* reference the logo correctly

* actually add the grid image

* avoid using a slider, which would break for rendered notebooks

---------

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Deepak Cherian <dcherian@users.noreply.github.com>

Author: 3 people

docs/agnostic/xdggs.md

@@ -113,6 +113,7 @@
     "rasterix": ("https://rasterix.readthedocs.io/en/latest/", None),
     "shapely": ("https://shapely.readthedocs.io/en/latest/", None),
     "xvec": ("https://xvec.readthedocs.io/en/stable/", None),
+    "xdggs": ("https://xdggs.readthedocs.io/en/latest/", 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/conf.py

@@ -0,0 +1,69 @@
+---
+jupytext:
+  text_representation:
+    format_name: myst
+kernelspec:
+  display_name: Python 3
+  name: python
+---
+
+# xdggs: DGGSIndex
+
+````{grid}
+```{grid-item}
+:columns: 3
+```{image} https://xdggs.readthedocs.io/en/latest/_static/xdggs_logo.png
+---
+alt: xdggs logo
+width: 200px
+align: center
+---
+```
+```{grid-item}
+:columns: 9
+```{seealso}
+Learn more at the [xdggs](https://xdggs.readthedocs.io/en/latest/) documentation page.
+```
+````
+
+## Highlights
+
+xdggs provides a unified API for interacting with various Discrete Global Grid Systems (DGGS), like [HEALPix](https://healpix.sourceforge.io/html/intro.htm) or [H3](https://h3geo.org). It does so by parsing out grid metadata from the spatial coordinate containing the cell ids and persisting it on a "meta-index", an index that wraps another index (most commonly a `pandas` index).
+
+```{figure} h3.png
+The H3 grid, a hexagonal DGGS designed for navigation on land.
+```
+
+## Example
+
+Here's a dataset on a HEALPix grid:
+
+```{code-cell} python
+import xdggs
+
+ds = xdggs.tutorial.open_dataset("air_temperature", "healpix")
+ds
+```
+
+with that, we can decode the metadata:
+
+```{code-cell} python
+decoded = ds.dggs.decode()
+decoded
+```
+
+Note how the `cell_ids` coordinate is now associated with a `HealpixIndex`? This makes it harder to lose the parsed information, and thus having to parse it again.
+
+We can also have a look at the parsed metadata:
+
+```{code-cell} python
+decoded.dggs.grid_info
+```
+
+Here's how the dataset looks:
+
+```{code-cell} python
+decoded["air"].isel(time=0).dggs.explore(alpha=0.8)
+```
+
+In a future version of `xdggs` this may also support more operations, like alignment, selection using parent cell ids, or lazy coordinates for cell centers / cell boundaries.

docs/earth/h3.png

@@ -27,7 +27,6 @@ blocks/ndpoint
 caption: Domain Agnostic
 hidden:
 ---
-agnostic/xdggs
 agnostic/pint
 ```
 
@@ -39,6 +38,7 @@ hidden:
 earth/xproj
 earth/raster
 earth/xvec
+earth/xdggs
 earth/forecast
 earth/cfvertical
 ```