Add warning when constructing a PolyCollection/LineCollection with a projection (#1351)

* add warning

* add warning for projection

* add test case

* update phrasing

* more detailed warning

* update test warning

---------

Co-authored-by: Orhan Eroglu <[email protected]>

Author: philipc2

test/test_dataset.py

@@ -6,10 +6,8 @@
 from uxarray import UxDataset
 import pytest
 
-try:
-    import constants
-except ImportError:
-    from . import constants
+import numpy as np
+from . import constants
 
 current_path = Path(os.path.dirname(os.path.realpath(__file__)))
 
@@ -19,6 +17,16 @@
 dsfile_v1_geoflow = current_path / "meshfiles" / "ugrid" / "geoflow-small" / "v1.nc"
 mpas_ds_path = current_path / 'meshfiles' / "mpas" / "QU" / 'mesh.QU.1920km.151026.nc'
 
+
+
+
+@pytest.fixture()
+def healpix_sample_ds():
+    uxgrid = ux.Grid.from_healpix(zoom=1)
+    fc_var = ux.UxDataArray(data=np.ones((3, uxgrid.n_face)), dims=['time', 'n_face'], uxgrid=uxgrid)
+    nc_var = ux.UxDataArray(data=np.ones((3, uxgrid.n_node)), dims=['time', 'n_node'], uxgrid=uxgrid)
+    return ux.UxDataset({"fc": fc_var, "nc": nc_var}, uxgrid=uxgrid)
+
 def test_uxgrid_setget():
     """Load a dataset with its grid topology file using uxarray's
     open_dataset call and check its grid object."""
@@ -59,15 +67,3 @@ def test_get_dual():
 
     assert isinstance(dual, UxDataset)
     assert len(uxds.data_vars) == len(dual.data_vars)
-
-# Uncomment the following test if you want to include it, ensuring you handle potential failures.
-# def test_read_from_https():
-#     """Tests reading a dataset from a HTTPS link."""
-#     import requests
-#
-#     small_file_480km = requests.get(
-#         "https://web.lcrc.anl.gov/public/e3sm/inputdata/share/meshes/mpas/ocean/oQU480.230422.nc"
-#     ).content
-#
-#     ds_small_480km = ux.open_dataset(small_file_480km, small_file_480km)
-#     assert isinstance(ds_small_480km, ux.core.dataset.UxDataset)

test/test_plot.py

@@ -110,3 +110,12 @@ def test_to_raster():
     raster = uxds['bottomDepth'].to_raster(ax=ax)
 
     assert isinstance(raster, np.ndarray)
+
+
+def test_collections_projection_kwarg():
+    import cartopy.crs as ccrs
+    uxgrid = ux.open_grid(gridfile_ne30)
+
+    with pytest.warns(FutureWarning):
+        pc = uxgrid.to_polycollection(projection=ccrs.PlateCarree())
+        lc = uxgrid.to_linecollection(projection=ccrs.PlateCarree())

uxarray/grid/grid.py

@@ -2208,7 +2208,7 @@ def to_polycollection(
         **kwargs,
     ):
         """Constructs a ``matplotlib.collections.PolyCollection``` consisting
-        of polygons representing the faces of the current ``Grid``
+        of polygons representing the faces of the unstructured grid.
 
         Parameters
         ----------
@@ -2217,6 +2217,21 @@ def to_polycollection(
         """
         import cartopy.crs as ccrs
 
+        if "projection" in kwargs:
+            proj = kwargs.pop("projection")
+            warn(
+                (
+                    "'projection' is not a supported argument and will be ignored. "
+                    "Define the desired projection on the GeoAxes that this collection will be added to. "
+                    "Example:\n"
+                    "    fig, ax = plt.subplots(subplot_kw={'projection': ccrs.Robinson()})\n"
+                    "    ax.add_collection(poly_collection)\n"
+                    f"(received projection={proj!r})"
+                ),
+                category=FutureWarning,
+                stacklevel=2,
+            )
+
         if self._cached_poly_collection:
             return copy.deepcopy(self._cached_poly_collection)
 
@@ -2237,15 +2252,29 @@ def to_linecollection(
         **kwargs,
     ):
         """Constructs a ``matplotlib.collections.LineCollection``` consisting
-        of lines representing the edges of the current ``Grid``
+        of lines representing the edges of the unstructured grid.
 
         Parameters
         ----------
         **kwargs: dict
-            Key word arguments to pass into the construction of a PolyCollection
+            Key word arguments to pass into the construction of a LineCollection
         """
         import cartopy.crs as ccrs
 
+        if "projection" in kwargs:
+            proj = kwargs.pop("projection")
+            warn(
+                (
+                    "'projection' is not a supported argument and will be ignored. "
+                    "Define the desired projection on the GeoAxes that this collection will be added to. "
+                    "Example:\n"
+                    "    fig, ax = plt.subplots(subplot_kw={'projection': ccrs.Robinson()})\n"
+                    "    ax.add_collection(line_collection)\n"
+                    f"(received projection={proj!r})"
+                ),
+                category=FutureWarning,
+                stacklevel=2,
+            )
         if self._cached_line_collection:
             return copy.deepcopy(self._cached_line_collection)