Add HEALPix Support (#1147)

* initial from_healpix

* add healpix as a dependency

* add healpix io module

* continue healpix reader, start user guide

* continue healpix reader, start user guide

* update user guide

* add tests

* update notebook

* work on userguide, data loading

* docstrings

* add docstrings

* add tests for data

* notebook revisions

* notebook revisions

* normalize before finding unique nodes

---------

Co-authored-by: Rajeev Jain <[email protected]>
Co-authored-by: Aaron Zedwick <[email protected]>

Author: 3 people

Diff for: ci/asv.yml

@@ -11,6 +11,7 @@ dependencies:
   - holoviews
   - matplotlib-base
   - matplotlib-inline
+  - healpix
   - netcdf4
   - numba
   - numpy

Diff for: ci/docs.yml

@@ -12,6 +12,7 @@ dependencies:
     - pytest
     - pytest-cov
     - scipy
+    - healpix
     - xarray
     - pip
     - ipykernel

Diff for: ci/environment.yml

@@ -11,6 +11,7 @@ dependencies:
   - geoviews
   - h5netcdf
   - hdf5
+  - healpix
   - holoviews
   - hvplot
   - matplotlib-base

Diff for: docs/api.rst

@@ -43,6 +43,7 @@ I/O & Conversion
    Grid.from_topology
    Grid.from_structured
    Grid.from_points
+   Grid.from_healpix
    Grid.to_xarray
    Grid.to_geodataframe
    Grid.to_polycollection
@@ -225,6 +226,7 @@ I/O & Conversion
 
    UxDataset.from_structured
    UxDataset.from_xarray
+   UxDataset.from_healpix
 
 Plotting
 --------

Diff for: docs/user-guide/grid-formats.rst

@@ -20,6 +20,7 @@ models have their own grid format (e.g. MPAS, ICON). Below is a list of support
 * GEOS CS
 * ICON
 * FESOM2
+* HEALPix
 
 UGRID
 =====
@@ -149,6 +150,21 @@ References
 ----------
 * https://fesom2.readthedocs.io/en/latest/index.html#
 
+HEALPix
+=======
+The Hierarchical Equal Area isoLatitude Pixelisation (HEALPix) algorithm is a method for the pixelisation of the
+2-sphere. It has three defining qualities.
+- The sphere is hierarchically tessellated into curvilinear quadrilaterals
+- Areas of all pixels at a given resolution are identical
+- Pixels are distributed on lines of constant latitude
+
+References
+----------
+* https://easy.gems.dkrz.de/Processing/healpix/index.html#hierarchical-healpix-output
+* https://healpix.sourceforge.io/
+* https://healpix.jpl.nasa.gov/
+* https://iopscience.iop.org/article/10.1086/427976
+
 Parsed Variables
 ================