Add safeguards to only allow global HEALPix data (#1257)

* add safeguards to non-global HEALPix data

* use more robust method and add better docstrings

Author: philipc2

docs/api.rst

@@ -201,6 +201,7 @@ I/O & Conversion
    UxDataArray.to_polycollection
    UxDataArray.to_dataset
    UxDataArray.from_xarray
+   UxDataArray.from_healpix
 
 
 UxDataset

test/test_healpix.py

@@ -80,3 +80,10 @@ def test_from_healpix_dataset():
 
     uxda = ux.UxDataset.from_healpix(xrda, face_dim="n_face")
     assert isinstance(uxda, ux.UxDataset)
+
+
+def test_invalid_cells():
+    # 11 is not a valid number of global cells
+    xrda = xr.DataArray(data=np.ones(11), dims=['cell']).to_dataset(name='cell')
+    with pytest.raises(ValueError):
+        uxda = ux.UxDataset.from_healpix(xrda)

uxarray/core/dataarray.py

@@ -26,6 +26,7 @@
 from uxarray.grid import Grid
 from uxarray.grid.dual import construct_dual
 from uxarray.grid.validation import _check_duplicate_nodes_indices
+from uxarray.io._healpix import get_zoom_from_cells
 from uxarray.plot.accessor import UxDataArrayPlotAccessor
 from uxarray.remap.accessor import RemapAccessor
 from uxarray.subset import DataArraySubsetAccessor
@@ -1345,11 +1346,12 @@ def from_healpix(
                 f"Please set 'face_dim' to the dimension corresponding to the healpix face dimension."
             )
 
-        # Compute the HEALPix Zoom Level
-        zoom = np.emath.logn(4, (da.sizes[face_dim] / 12)).astype(int)
-
-        # Attach a  HEALPix Grid
-        uxgrid = Grid.from_healpix(zoom, pixels_only=pixels_only, **kwargs)
+        # Attach a HEALPix Grid
+        uxgrid = Grid.from_healpix(
+            zoom=get_zoom_from_cells(da.sizes[face_dim]),
+            pixels_only=pixels_only,
+            **kwargs,
+        )
 
         return cls.from_xarray(da, uxgrid, {face_dim: "n_face"})
 

uxarray/core/dataset.py

@@ -19,6 +19,7 @@
 from uxarray.grid import Grid
 from uxarray.grid.dual import construct_dual
 from uxarray.grid.validation import _check_duplicate_nodes_indices
+from uxarray.io._healpix import get_zoom_from_cells
 from uxarray.plot.accessor import UxDatasetPlotAccessor
 from uxarray.remap.accessor import RemapAccessor
 
@@ -317,11 +318,12 @@ def from_healpix(
                 f"Please set 'face_dim' to the dimension corresponding to the healpix face dimension."
             )
 
-        # Compute the HEALPix Zoom Level
-        zoom = np.emath.logn(4, (ds.sizes[face_dim] / 12)).astype(int)
-
-        # Attach a  HEALPix Grid
-        uxgrid = Grid.from_healpix(zoom, pixels_only=pixels_only, **kwargs)
+        # Attach a HEALPix Grid
+        uxgrid = Grid.from_healpix(
+            zoom=get_zoom_from_cells(ds.sizes[face_dim]),
+            pixels_only=pixels_only,
+            **kwargs,
+        )
 
         return cls.from_xarray(ds, uxgrid, {face_dim: "n_face"})
 

uxarray/io/_healpix.py

@@ -9,6 +9,39 @@
 from uxarray.constants import INT_DTYPE
 
 
+def get_zoom_from_cells(cells):
+    """
+    Compute the HEALPix zoom level n such that cells == 12 * 4**n.
+    Only global HEALPix grids (i.e. exactly 12 * 4**n cells) are supported.
+    Raises ValueError with detailed HEALPix guidance otherwise.
+    """
+    if not isinstance(cells, int) or cells < 12:
+        raise ValueError(
+            f"Invalid cells={cells!r}: a global HEALPix grid must have "
+            f"an integer number of cells ≥ 12 (12 base pixels at zoom=0)."
+        )
+
+    if cells % 12 != 0:
+        raise ValueError(
+            f"Invalid cells={cells}: global HEALPix grids have exactly 12 * 4**n cells"
+        )
+
+    power = cells // 12
+    zoom = 0
+
+    while power > 1 and power % 4 == 0:
+        power //= 4
+        zoom += 1
+
+    if power != 1:
+        raise ValueError(
+            f"Invalid cells={cells}: no integer n satisfies cells==12 * 4**n. "
+            f"Only global HEALPix grids (with cells = 12 × 4^n) are supported."
+        )
+
+    return zoom
+
+
 def pix2corner_ang(
     nside: int, ipix: Any, nest: bool = False, lonlat: bool = False
 ) -> Tuple[Any, Any, Any, Any]: